@indigoai-us/hq-cloud 5.45.0 → 5.46.0

package/src/skill-telemetry.ts

@@ -0,0 +1,499 @@
+/**
+ * Skill-invocation telemetry collector.
+ *
+ * Sibling to `./telemetry.ts` (the token-usage collector). Where that one
+ * promotes token-accounting fields off each Claude Code session row, this one
+ * extracts *which skill / slash-command was invoked*, reading the SAME
+ * `~/.claude/projects/**\/*.jsonl` session logs but with an independent
+ * byte-offset cursor at `~/.hq/skill-telemetry-cursor.json` and shipping to
+ * `/v1/skill-invocations`.
+ *
+ * Why a separate collector rather than folding into `./telemetry.ts`: the
+ * token path is proven and its per-batch cursor mechanics are load-bearing.
+ * Skill events are sparse, so this collector uses a simpler all-or-nothing
+ * per-run cursor commit (re-delivery is idempotent server-side via the
+ * composite eventKey). Keeping it standalone means a bug here can never
+ * regress token telemetry.
+ *
+ * Two capture paths, both recoverable from the transcript (verified against
+ * real sessions):
+ *   - User-typed slash command → a `user` row whose content carries
+ *     `<command-name>/foo</command-name>` (+ optional `<command-args>`).
+ *   - Model-invoked skill → an `assistant` row with a `tool_use` block whose
+ *     `name === "Skill"` and `input.skill` names the skill.
+ * The two are mutually exclusive per invocation, so there is no double-count.
+ *
+ * Privacy: raw `<command-args>` / `input.args` content is NEVER sent to the
+ * cloud — only a `hasArgs` boolean. This matches the message-stripping posture
+ * of `./telemetry.ts::sanitizeRow`, which deliberately drops all prompt/tool
+ * content client-side. Flip `INCLUDE_ARGS_PREVIEW` only with a deliberate
+ * privacy review and a matching server-side allowlist change.
+ *
+ * Trust model + error handling are identical to `./telemetry.ts`: personUid is
+ * resolved server-side from the JWT (never the body), and all errors are
+ * swallowed so telemetry never aborts or delays a sync.
+ */
+
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import type {
+  SkillInvocationBatch,
+  SkillInvocationIngestResult,
+  TelemetryOptInResponse,
+} from "./vault-client.js";
+
+// ── Public surface ────────────────────────────────────────────────────────────
+
+export interface SkillTelemetryClientSurface {
+  getTelemetryOptIn(): Promise<TelemetryOptInResponse>;
+  postSkillInvocations(
+    batch: SkillInvocationBatch,
+  ): Promise<SkillInvocationIngestResult>;
+}
+
+export interface CollectSkillTelemetryOptions {
+  client: SkillTelemetryClientSurface;
+  machineId: string;
+  installerVersion: string;
+  /**
+   * When set, only invocations whose recorded `cwd` equals this path are
+   * emitted — scoping capture to the HQ project and excluding skill usage in
+   * unrelated repos on the same machine. The walk still covers all of
+   * `~/.claude/projects` (so the cursor stays consistent and no session is
+   * silently missed by a project-dir-name encoding guess), but non-matching
+   * events are dropped before they are batched. Omit to capture every project.
+   */
+  hqRoot?: string;
+  /** Override `~/.claude/projects` for tests. */
+  claudeProjectsRoot?: string;
+  /** Override `~/.hq/skill-telemetry-cursor.json` for tests. */
+  cursorPath?: string;
+  /** Override `~/.hq/menubar.json` (the offline opt-in fallback) for tests. */
+  menubarPath?: string;
+  /** Diagnostic sink. No-op by default. */
+  log?: (msg: string) => void;
+}
+
+export interface CollectSkillTelemetryResult {
+  enabled: boolean;
+  optInSource: "server" | "menubar-fallback" | "skipped";
+  filesScanned: number;
+  eventsSent: number;
+  batchesSent: number;
+}
+
+/** A single extracted skill-invocation event. Mirrors the server allowlist in
+ *  `apps/hq-pro/src/vault-service/handlers/skill-invocations.ts` (KEEP_FIELDS).
+ *  Any drift surfaces as `unexpected-event-field` in the ingest result. */
+export interface SkillEvent {
+  skill: string;
+  source: "typed" | "model";
+  sessionId?: string;
+  timestamp?: string;
+  uuid?: string;
+  cwd?: string;
+  hasArgs: boolean;
+}
+
+// Privacy switch — keep false (see file header). When false, raw argument text
+// never leaves the machine; only the `hasArgs` boolean is emitted.
+const INCLUDE_ARGS_PREVIEW = false;
+
+// ── Cursor schema (independent from the token collector's) ──────────────────────
+
+interface CursorEntry {
+  offset: number;
+  mtime: number;
+}
+
+interface SkillCursor {
+  version: string;
+  files: Record<string, CursorEntry>;
+}
+
+async function loadCursor(cursorPath: string): Promise<SkillCursor> {
+  try {
+    const raw = await fs.readFile(cursorPath, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<SkillCursor>;
+    if (parsed && typeof parsed === "object" && parsed.files && typeof parsed.files === "object") {
+      return { version: parsed.version ?? "1", files: parsed.files as Record<string, CursorEntry> };
+    }
+  } catch {
+    // Missing / unparseable — start fresh.
+  }
+  return { version: "1", files: {} };
+}
+
+async function saveCursor(cursorPath: string, cursor: SkillCursor): Promise<void> {
+  await fs.mkdir(path.dirname(cursorPath), { recursive: true });
+  const tmp = `${cursorPath}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(cursor, null, 2), "utf-8");
+  await fs.rename(tmp, cursorPath);
+}
+
+async function readLocalTelemetryEnabled(menubarPath: string): Promise<boolean> {
+  try {
+    const raw = await fs.readFile(menubarPath, "utf-8");
+    const parsed = JSON.parse(raw) as { telemetryEnabled?: unknown };
+    return parsed.telemetryEnabled === true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Extractor ───────────────────────────────────────────────────────────────
+
+const CMD_NAME = /<command-name>\s*\/?([^<]+?)\s*<\/command-name>/;
+const CMD_ARGS = /<command-args>([\s\S]*?)<\/command-args>/;
+
+function rowText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((b) => (b && typeof b === "object" && typeof (b as Record<string, unknown>).text === "string"
+        ? ((b as Record<string, unknown>).text as string)
+        : ""))
+      .join(" ");
+  }
+  return "";
+}
+
+/**
+ * Extract zero or more skill-invocation events from a single parsed session
+ * row. A `user` row yields at most one typed command; an `assistant` row can
+ * carry multiple `Skill` tool_use blocks (rare, but handled).
+ */
+export function extractSkillEvents(row: unknown): SkillEvent[] {
+  if (!row || typeof row !== "object" || Array.isArray(row)) return [];
+  const obj = row as Record<string, unknown>;
+  const type = obj.type;
+  const msg =
+    obj.message && typeof obj.message === "object" && !Array.isArray(obj.message)
+      ? (obj.message as Record<string, unknown>)
+      : undefined;
+  if (!msg) return [];
+
+  const sessionId = typeof obj.sessionId === "string" ? obj.sessionId : undefined;
+  const timestamp = typeof obj.timestamp === "string" ? obj.timestamp : undefined;
+  const cwd = typeof obj.cwd === "string" ? obj.cwd : undefined;
+  const rowUuid = typeof obj.uuid === "string" ? obj.uuid : undefined;
+
+  // Path A — user-typed slash command.
+  if (type === "user") {
+    const text = rowText(msg.content);
+    const m = CMD_NAME.exec(text);
+    if (!m) return [];
+    const a = CMD_ARGS.exec(text);
+    return [
+      {
+        skill: m[1].trim(),
+        source: "typed",
+        sessionId,
+        timestamp,
+        cwd,
+        uuid: rowUuid,
+        hasArgs: Boolean(a && a[1].trim()),
+      },
+    ];
+  }
+
+  // Path B — model-invoked Skill tool_use.
+  if (type === "assistant" && Array.isArray(msg.content)) {
+    const out: SkillEvent[] = [];
+    for (const blk of msg.content as unknown[]) {
+      if (!blk || typeof blk !== "object") continue;
+      const b = blk as Record<string, unknown>;
+      if (b.type !== "tool_use" || b.name !== "Skill") continue;
+      const input =
+        b.input && typeof b.input === "object" && !Array.isArray(b.input)
+          ? (b.input as Record<string, unknown>)
+          : {};
+      const skill = typeof input.skill === "string" ? input.skill : "";
+      if (!skill) continue;
+      const args = input.args;
+      out.push({
+        skill,
+        source: "model",
+        sessionId,
+        timestamp,
+        cwd,
+        // Prefer the tool_use block id (stable, globally unique) for dedup.
+        uuid: typeof b.id === "string" ? b.id : rowUuid,
+        hasArgs: typeof args === "string" ? args.trim().length > 0 : Boolean(args),
+      });
+    }
+    return out;
+  }
+
+  return [];
+}
+
+/** Shape the event for the wire. Drops raw args unless explicitly enabled. */
+function toWireRow(ev: SkillEvent): Record<string, unknown> {
+  const row: Record<string, unknown> = {
+    skill: ev.skill,
+    source: ev.source,
+    hasArgs: ev.hasArgs,
+  };
+  if (ev.sessionId !== undefined) row.sessionId = ev.sessionId;
+  if (ev.timestamp !== undefined) row.timestamp = ev.timestamp;
+  if (ev.uuid !== undefined) row.uuid = ev.uuid;
+  if (ev.cwd !== undefined) row.cwd = ev.cwd;
+  // INCLUDE_ARGS_PREVIEW is intentionally a compile-time constant `false`;
+  // the guarded branch documents the (currently disabled) egress path.
+  if (INCLUDE_ARGS_PREVIEW) {
+    // Reserved: a server allowlist change must land before this is enabled.
+  }
+  return row;
+}
+
+// ── File walker ───────────────────────────────────────────────────────────────
+
+async function listJsonlFiles(root: string): Promise<string[]> {
+  const out: string[] = [];
+  async function walk(dir: string): Promise<void> {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const ent of entries) {
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        await walk(full);
+      } else if (ent.isFile() && ent.name.endsWith(".jsonl")) {
+        out.push(full);
+      }
+    }
+  }
+  await walk(root);
+  return out;
+}
+
+const MAX_BATCH_BYTES = 1_000_000;
+
+// ── Main entry point ──────────────────────────────────────────────────────────
+
+/**
+ * Scan, extract, and POST any new skill-invocation events.
+ *
+ * Cursor model (per-batch commit, matching the token collector for robustness):
+ * each file is scanned from its stored byte offset to EOF; extracted events
+ * carry the byte offset of the line they came from. Events are flushed in
+ * ≤1 MiB batches, and the cursor advances **per successful batch** — so if one
+ * batch in a large (e.g. first-run backfill) fails, the batches that already
+ * succeeded stay committed and only the rest re-send next sync.
+ *
+ * Per-file commit rule:
+ *   - All of a file's events sent OK (including zero-event files) → commit EOF,
+ *     so quiet/non-skill tails are never re-scanned.
+ *   - Some of a file's events failed → commit the max byte offset whose batch
+ *     succeeded (partial progress); the remainder re-sends next sync.
+ * Server-side dedup on the composite eventKey makes any re-send idempotent.
+ * Rotation/truncation resets the offset to 0 (re-read from the top).
+ */
+export async function collectAndSendSkillTelemetry(
+  opts: CollectSkillTelemetryOptions,
+): Promise<CollectSkillTelemetryResult> {
+  const home = os.homedir();
+  const claudeProjectsRoot =
+    opts.claudeProjectsRoot ?? path.join(home, ".claude", "projects");
+  const cursorPath =
+    opts.cursorPath ?? path.join(home, ".hq", "skill-telemetry-cursor.json");
+  const menubarPath = opts.menubarPath ?? path.join(home, ".hq", "menubar.json");
+  const log = opts.log ?? (() => {});
+
+  // Normalize the scope path once (drop a single trailing slash, keeping "/").
+  const normalizePath = (p: string): string => (p.length > 1 ? p.replace(/\/+$/, "") : p);
+  const scopeCwd = opts.hqRoot !== undefined ? normalizePath(opts.hqRoot) : undefined;
+
+  // 1. Opt-in check — reuse the same gate as token telemetry.
+  let enabled: boolean;
+  let optInSource: CollectSkillTelemetryResult["optInSource"];
+  try {
+    const resp = await opts.client.getTelemetryOptIn();
+    enabled = resp.enabled === true;
+    optInSource = "server";
+  } catch (err) {
+    log(`[skill-telemetry] opt-in check failed (${(err as Error).message ?? err}) — falling back to local menubar.json`);
+    enabled = await readLocalTelemetryEnabled(menubarPath);
+    optInSource = "menubar-fallback";
+  }
+
+  if (!enabled) {
+    return { enabled: false, optInSource, filesScanned: 0, eventsSent: 0, batchesSent: 0 };
+  }
+
+  // 2. Cursor + file enumeration.
+  const cursor = await loadCursor(cursorPath);
+  const files = await listJsonlFiles(claudeProjectsRoot);
+
+  // 3. Scan every file from its stored offset, collecting events tagged with
+  //    the byte offset of the line they came from (for per-batch commit).
+  interface FileScan {
+    eof: number;
+    mtime: number;
+    eventCount: number; // events extracted from this file this run
+  }
+  interface Sourced {
+    row: Record<string, unknown>;
+    filePath: string;
+    endOffset: number; // absolute byte offset at the end of the source line
+  }
+
+  const fileScans: Record<string, FileScan> = {};
+  const rotationResets: Record<string, CursorEntry> = {};
+  const sourced: Sourced[] = [];
+
+  for (const filePath of files) {
+    let stat;
+    try {
+      stat = await fs.stat(filePath);
+    } catch {
+      continue;
+    }
+    const currentSize = stat.size;
+    const currentMtime = Math.floor(stat.mtimeMs / 1000);
+
+    const stored = cursor.files[filePath] ?? { offset: 0, mtime: 0 };
+    let offset = stored.offset;
+
+    // Rotation / truncation → re-read from the top.
+    const rotated =
+      currentSize < offset || (stored.mtime > 0 && currentMtime < stored.mtime);
+    if (rotated) {
+      offset = 0;
+      rotationResets[filePath] = { offset: 0, mtime: currentMtime };
+    }
+
+    // Record the scan even when there are no new bytes — a fully-drained file
+    // (eventCount 0, offset already at EOF) should still settle at EOF below.
+    fileScans[filePath] = { eof: currentSize, mtime: currentMtime, eventCount: 0 };
+
+    if (offset >= currentSize && !rotated) continue;
+
+    let content: string;
+    try {
+      const fh = await fs.open(filePath, "r");
+      try {
+        const length = Math.max(0, currentSize - offset);
+        const buf = Buffer.alloc(length);
+        await fh.read(buf, 0, length, offset);
+        content = buf.toString("utf-8");
+      } finally {
+        await fh.close();
+      }
+    } catch {
+      // Could not read — drop the scan so we don't claim progress for it.
+      delete fileScans[filePath];
+      continue;
+    }
+
+    // Compute the absolute end-byte offset of each line in the read region.
+    const segments = content.split("\n");
+    let cumulative = offset;
+    for (let i = 0; i < segments.length; i++) {
+      cumulative += Buffer.byteLength(segments[i], "utf-8");
+      if (i < segments.length - 1) cumulative += 1; // the split newline byte
+      const endOffset = cumulative;
+
+      const trimmed = segments[i].trim();
+      if (trimmed.length === 0) continue;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(trimmed);
+      } catch {
+        continue;
+      }
+      for (const ev of extractSkillEvents(parsed)) {
+        // Scope filter: only emit invocations made from the HQ project.
+        if (scopeCwd !== undefined && (ev.cwd === undefined || normalizePath(ev.cwd) !== scopeCwd)) {
+          continue;
+        }
+        sourced.push({ row: toWireRow(ev), filePath, endOffset });
+        fileScans[filePath].eventCount++;
+      }
+    }
+  }
+
+  // 4. Flush in ≤1 MiB batches, advancing per-file progress on each 2xx.
+  let eventsSent = 0;
+  let batchesSent = 0;
+
+  // Per file: count of events successfully sent + max committed byte offset.
+  const sentCount: Record<string, number> = {};
+  const committedOffset: Record<string, number> = {};
+
+  const envelopeBytes = Buffer.byteLength(
+    JSON.stringify({ machineId: opts.machineId, installerVersion: opts.installerVersion, events: [] }),
+    "utf-8",
+  );
+
+  let batch: Sourced[] = [];
+  let batchBytes = envelopeBytes;
+
+  const flush = async (): Promise<void> => {
+    if (batch.length === 0) return;
+    const toSend = batch;
+    batch = [];
+    batchBytes = envelopeBytes;
+    try {
+      await opts.client.postSkillInvocations({
+        machineId: opts.machineId,
+        installerVersion: opts.installerVersion,
+        events: toSend.map((s) => s.row),
+      });
+      batchesSent++;
+      eventsSent += toSend.length;
+      // Advance per-file progress for the events in this (successful) batch.
+      for (const s of toSend) {
+        sentCount[s.filePath] = (sentCount[s.filePath] ?? 0) + 1;
+        const prev = committedOffset[s.filePath] ?? 0;
+        if (s.endOffset > prev) committedOffset[s.filePath] = s.endOffset;
+      }
+    } catch (err) {
+      log(`[skill-telemetry] postSkillInvocations failed (${(err as Error).message ?? err}) — these rows re-send next sync`);
+      // Cursor not advanced for this batch; eventKey dedups the eventual re-send.
+    }
+  };
+
+  for (const s of sourced) {
+    const rowBytes = Buffer.byteLength(JSON.stringify(s.row), "utf-8");
+    const addCost = rowBytes + (batch.length > 0 ? 1 : 0);
+    if (batch.length > 0 && batchBytes + addCost > MAX_BATCH_BYTES) {
+      await flush();
+      batchBytes = envelopeBytes + rowBytes;
+    } else {
+      batchBytes += addCost;
+    }
+    batch.push(s);
+  }
+  await flush();
+
+  // 5. Build the new cursor: loaded < rotationResets < per-file commit.
+  //    A file settles at EOF only when every event extracted from it this run
+  //    was sent OK (zero-event files included); otherwise it settles at the
+  //    highest byte offset whose batch succeeded, so the rest re-sends.
+  const finalFiles: Record<string, CursorEntry> = { ...cursor.files };
+  for (const [fp, entry] of Object.entries(rotationResets)) finalFiles[fp] = entry;
+  for (const [fp, scan] of Object.entries(fileScans)) {
+    if ((sentCount[fp] ?? 0) >= scan.eventCount) {
+      finalFiles[fp] = { offset: scan.eof, mtime: scan.mtime };
+    } else if (fp in committedOffset) {
+      finalFiles[fp] = { offset: committedOffset[fp], mtime: scan.mtime };
+    }
+    // else: no progress for this file — leave loaded/rotation-reset offset.
+  }
+  await saveCursor(cursorPath, { version: "1", files: finalFiles });
+
+  return {
+    enabled: true,
+    optInSource,
+    filesScanned: files.length,
+    eventsSent,
+    batchesSent,
+  };
+}

package/src/vault-client.ts

@@ -352,6 +352,27 @@ export interface UsageIngestResult {
   skipped: Array<{ index: number; code: string; error: string }>;
 }
 
+// ---------------------------------------------------------------------------
+// Skill-invocation telemetry (hq-pro `/v1/skill-invocations`)
+// ---------------------------------------------------------------------------
+
+export interface SkillInvocationBatch {
+  machineId: string;
+  installerVersion: string;
+  /**
+   * Skill-invocation event rows. Each row contains only the fields in the
+   * server's KEEP allowlist (skill, source, sessionId, timestamp, uuid, cwd,
+   * hasArgs). Raw argument text is never included — see the privacy note in
+   * `./skill-telemetry.ts`. Any extra field is rejected by hq-pro with
+   * `unexpected-event-field`, so the extractor in `./skill-telemetry.ts` is the
+   * only thing allowed to produce these.
+   */
+  events: Array<Record<string, unknown>>;
+}
+
+/** Same wire shape as `UsageIngestResult`; aliased for call-site clarity. */
+export type SkillInvocationIngestResult = UsageIngestResult;
+
 // ---------------------------------------------------------------------------
 // Retry config
 // ---------------------------------------------------------------------------
@@ -773,6 +794,19 @@ export class VaultClient {
     return this.post<UsageIngestResult>("/v1/usage", batch);
   }
 
+  /**
+   * `POST /v1/skill-invocations` — upload a batch of skill-invocation events.
+   *
+   * Same trust + size model as `postUsage`: `personUid` MUST NOT appear in the
+   * batch (server resolves it from the JWT). Gated by the same telemetry
+   * opt-in as `/v1/usage`.
+   */
+  async postSkillInvocations(
+    batch: SkillInvocationBatch,
+  ): Promise<SkillInvocationIngestResult> {
+    return this.post<SkillInvocationIngestResult>("/v1/skill-invocations", batch);
+  }
+
   // -- HTTP primitives with retry -------------------------------------------
 
   private async get<T>(path: string): Promise<T> {