@indigoai-us/hq-cloud 6.14.28 → 6.14.30

package/src/telemetry.ts

@@ -7,9 +7,8 @@
  * (`hq-sync-runner`, `hq-cli`, mobile wrappers) emits telemetry uniformly.
  *
  * What it does: after each successful sync (`all-complete` arm of
- * `bin/sync-runner.ts`), walks `~/.claude/projects/**\/*.jsonl`, diffs each
- * file against a persisted byte-offset cursor at `~/.hq/telemetry-cursor.json`,
- * sanitizes new rows through a tight allowlist that matches the server's
+ * `bin/sync-runner.ts`), walks Claude session logs plus live and archived Codex
+ * rollouts, then diffs each file against the persisted byte-offset cursor at `~/.hq/telemetry-cursor.json`, sanitizes new rows through a tight allowlist that matches the server's
  * KEEP_FIELDS set in `apps/hq-pro/src/vault-service/handlers/usage.ts`,
  * batches into server-sized POST bodies, and ships them to `/v1/usage`.
  *
@@ -23,6 +22,7 @@
  * transient outage retries automatically on the next sync.
  */
 
+import { createHash } from "node:crypto";
 import { promises as fs } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -75,6 +75,8 @@ export interface CollectTelemetryOptions {
   hqRoot?: string;
   /** Override `~/.claude/projects` for tests. */
   claudeProjectsRoot?: string;
+  /** Override `~/.codex` for tests. Both live and archived rollouts are scanned. */
+  codexRoot?: string;
   /** Override `~/.hq/telemetry-cursor.json` for tests. */
   cursorPath?: string;
   /** Override `~/.hq/menubar.json` (the offline opt-in fallback) for tests. */
@@ -98,14 +100,27 @@ export interface CollectTelemetryResult {
 
 // ── Cursor schema ─────────────────────────────────────────────────────────────
 
+interface CodexUsageContext {
+  session_id?: string;
+  cwd?: string;
+  git_branch?: string;
+  session_model?: string;
+  collaboration_model?: string;
+  turn_model?: string;
+}
+
 interface CursorEntry {
   offset: number;
   mtime: number;
+  /** Runtime context needed to resume a Codex rollout from a byte offset. */
+  context?: CodexUsageContext;
 }
 
 interface TelemetryCursor {
   version: string;
   files: Record<string, CursorEntry>;
+  /** Preserved for cursor compatibility with the desktop collector. */
+  codex_next_rollout?: string;
 }
 
 function emptyCursor(): TelemetryCursor {
@@ -117,7 +132,13 @@ async function loadCursor(cursorPath: string): Promise<TelemetryCursor> {
     const raw = await fs.readFile(cursorPath, "utf-8");
     const parsed = JSON.parse(raw) as Partial<TelemetryCursor>;
     if (parsed && typeof parsed === "object" && parsed.files && typeof parsed.files === "object") {
-      return { version: parsed.version ?? "1", files: parsed.files as Record<string, CursorEntry> };
+      return {
+        version: parsed.version ?? "1",
+        files: parsed.files as Record<string, CursorEntry>,
+        ...(typeof parsed.codex_next_rollout === "string"
+          ? { codex_next_rollout: parsed.codex_next_rollout }
+          : {}),
+      };
     }
   } catch {
     // Missing / unparseable — start fresh.
@@ -377,6 +398,163 @@ async function listJsonlFiles(root: string): Promise<string[]> {
   return out;
 }
 
+// ── Codex rollout adapter ────────────────────────────────────────────────────
+
+const MAX_ID_BYTES = 256;
+const MAX_TIMESTAMP_BYTES = 128;
+const MAX_PATH_BYTES = 4 * 1024;
+const MAX_MODEL_BYTES = 256;
+
+function boundedString(value: unknown, maxBytes: number): string | undefined {
+  return typeof value === "string" &&
+    value.length > 0 &&
+    Buffer.byteLength(value, "utf-8") <= maxBytes
+    ? value
+    : undefined;
+}
+
+function tokenCount(value: unknown): number {
+  return typeof value === "number" &&
+    Number.isSafeInteger(value) &&
+    value >= 0
+    ? value
+    : 0;
+}
+
+function cloneCodexContext(context: CodexUsageContext): CodexUsageContext {
+  return { ...context };
+}
+
+function codexModel(context: CodexUsageContext): string | undefined {
+  return context.turn_model ?? context.collaboration_model ?? context.session_model;
+}
+
+function codexGitBranch(payload: Record<string, unknown>): string | undefined {
+  const direct =
+    boundedString(payload.gitBranch, MAX_PATH_BYTES) ??
+    boundedString(payload.git_branch, MAX_PATH_BYTES);
+  if (direct) return direct;
+  const git = payload.git;
+  return git && typeof git === "object" && !Array.isArray(git)
+    ? boundedString((git as Record<string, unknown>).branch, MAX_PATH_BYTES)
+    : undefined;
+}
+
+function collaborationModel(
+  payload: Record<string, unknown>,
+): string | undefined {
+  const settings = payload.settings;
+  if (!settings || typeof settings !== "object" || Array.isArray(settings)) {
+    return undefined;
+  }
+  return boundedString((settings as Record<string, unknown>).model, MAX_MODEL_BYTES);
+}
+
+function stableCodexEventId(
+  rolloutIdentity: string,
+  startOffset: number,
+  endOffset: number,
+): string {
+  const offsets = Buffer.alloc(16);
+  offsets.writeBigUInt64BE(BigInt(startOffset), 0);
+  offsets.writeBigUInt64BE(BigInt(endOffset), 8);
+  return "codex-" + createHash("sha256")
+    .update(rolloutIdentity)
+    .update(Buffer.from([0]))
+    .update(offsets)
+    .digest("hex");
+}
+
+/** Adapt a Codex rollout record to the Claude-shaped sanitizer input. */
+function codexUsageRow(
+  row: unknown,
+  context: CodexUsageContext,
+  rolloutIdentity: string,
+  startOffset: number,
+  endOffset: number,
+): Record<string, unknown> | null {
+  if (!row || typeof row !== "object" || Array.isArray(row)) return null;
+  const obj = row as Record<string, unknown>;
+  const kind = obj.type;
+  const rawPayload = obj.payload;
+  const payload =
+    rawPayload && typeof rawPayload === "object" && !Array.isArray(rawPayload)
+      ? (rawPayload as Record<string, unknown>)
+      : undefined;
+
+  if (kind === "session_meta") {
+    if (!payload) return null;
+    context.session_id = boundedString(payload.id, MAX_ID_BYTES) ?? context.session_id;
+    context.cwd = boundedString(payload.cwd, MAX_PATH_BYTES);
+    context.git_branch = codexGitBranch(payload);
+    context.session_model = boundedString(payload.model, MAX_MODEL_BYTES);
+    return null;
+  }
+  if (kind === "turn_context") {
+    context.turn_model = payload
+      ? boundedString(payload.model, MAX_MODEL_BYTES)
+      : undefined;
+    const mode = payload?.collaboration_mode;
+    if (mode && typeof mode === "object" && !Array.isArray(mode)) {
+      const model = collaborationModel(mode as Record<string, unknown>);
+      if (model) context.collaboration_model = model;
+    }
+    return null;
+  }
+  if (kind === "collaboration_mode") {
+    context.collaboration_model = payload
+      ? collaborationModel(payload)
+      : undefined;
+    return null;
+  }
+  if (kind !== "event_msg" || !payload) return null;
+  if (payload.type === "collaboration_mode") {
+    context.collaboration_model = collaborationModel(payload);
+    return null;
+  }
+  if (payload.type !== "token_count") return null;
+
+  const info = payload.info;
+  if (!info || typeof info !== "object" || Array.isArray(info)) return null;
+  const last = (info as Record<string, unknown>).last_token_usage;
+  if (!last || typeof last !== "object" || Array.isArray(last)) return null;
+  const usage = last as Record<string, unknown>;
+  const outputTokens =
+    tokenCount(usage.output_tokens) + tokenCount(usage.reasoning_output_tokens);
+  const model = codexModel(context);
+  const normalized: Record<string, unknown> = {
+    uuid:
+      boundedString(obj.uuid, MAX_ID_BYTES) ??
+      stableCodexEventId(rolloutIdentity, startOffset, endOffset),
+    message: {
+      usage: {
+        input_tokens: tokenCount(usage.input_tokens),
+        output_tokens: outputTokens,
+        ...(typeof usage.cached_input_tokens === "number"
+          ? { cache_read_input_tokens: tokenCount(usage.cached_input_tokens) }
+          : {}),
+      },
+      ...(model ? { model } : {}),
+    },
+  };
+  if (context.session_id) normalized.sessionId = context.session_id;
+  const timestamp = boundedString(obj.timestamp, MAX_TIMESTAMP_BYTES);
+  if (timestamp) normalized.timestamp = timestamp;
+  if (context.cwd) normalized.cwd = context.cwd;
+  if (context.git_branch) normalized.gitBranch = context.git_branch;
+  return normalized;
+}
+
+async function listCodexRolloutFiles(codexRoot: string): Promise<string[]> {
+  const [live, archived] = await Promise.all([
+    listJsonlFiles(path.join(codexRoot, "sessions")),
+    listJsonlFiles(path.join(codexRoot, "archived_sessions")),
+  ]);
+  return [...live, ...archived].filter((file) =>
+    path.basename(file).startsWith("rollout-"),
+  );
+}
+
 // ── Batching primitives ───────────────────────────────────────────────────────
 
 const MAX_BATCH_EVENTS = 100;
@@ -387,6 +565,7 @@ interface RowSource {
   filePath: string;
   endOffset: number;
   mtime: number;
+  context?: CodexUsageContext;
 }
 
 /**
@@ -455,7 +634,7 @@ function boundRowForPost(
 // ── Main entry point ──────────────────────────────────────────────────────────
 
 /**
- * Scan, sanitize, and POST any new Claude Code session rows.
+ * Scan, sanitize, and POST new Claude Code and Codex usage rows.
  *
  * Fire-and-forget from the caller's perspective: errors are caught internally
  * and surfaced only via `log`. The returned summary lets observers (e.g.
@@ -467,6 +646,7 @@ export async function collectAndSendTelemetry(
 ): Promise<CollectTelemetryResult> {
   const home = os.homedir();
   const claudeProjectsRoot = opts.claudeProjectsRoot ?? path.join(home, ".claude", "projects");
+  const codexRoot = opts.codexRoot ?? path.join(home, ".codex");
   const cursorPath = opts.cursorPath ?? path.join(home, ".hq", "telemetry-cursor.json");
   const menubarPath = opts.menubarPath ?? path.join(home, ".hq", "menubar.json");
   const log = opts.log ?? (() => {});
@@ -565,7 +745,14 @@ export async function collectAndSendTelemetry(
   const rotationResets: Record<string, CursorEntry> = {};
   const newlyCommitted: Record<string, CursorEntry> = {};
 
-  const files = await listJsonlFiles(claudeProjectsRoot);
+  const [claudeFiles, codexFiles] = await Promise.all([
+    listJsonlFiles(claudeProjectsRoot),
+    listCodexRolloutFiles(codexRoot),
+  ]);
+  const files: Array<{ filePath: string; kind: "claude" | "codex" }> = [
+    ...claudeFiles.map((filePath) => ({ filePath, kind: "claude" as const })),
+    ...codexFiles.map((filePath) => ({ filePath, kind: "codex" as const })),
+  ];
 
   // 3. Walk each file, sanitize new rows, batch, flush at the server contract.
   //
@@ -599,15 +786,26 @@ export async function collectAndSendTelemetry(
       batchesSent++;
       eventsSent += events.length;
       // Advance cursor to max(endOffset) per file in this batch.
-      const maxPerFile = new Map<string, { mtime: number; offset: number }>();
+      const maxPerFile = new Map<
+        string,
+        { mtime: number; offset: number; context?: CodexUsageContext }
+      >();
       for (const src of sources) {
         const cur = maxPerFile.get(src.filePath);
         if (!cur || src.endOffset > cur.offset) {
-          maxPerFile.set(src.filePath, { mtime: src.mtime, offset: src.endOffset });
+          maxPerFile.set(src.filePath, {
+            mtime: src.mtime,
+            offset: src.endOffset,
+            ...(src.context ? { context: cloneCodexContext(src.context) } : {}),
+          });
         }
       }
       for (const [fp, entry] of maxPerFile) {
-        newlyCommitted[fp] = { offset: entry.offset, mtime: entry.mtime };
+        newlyCommitted[fp] = {
+          offset: entry.offset,
+          mtime: entry.mtime,
+          ...(entry.context ? { context: entry.context } : {}),
+        };
       }
     } catch (err) {
       log(`[telemetry] postUsage failed (${(err as Error).message ?? err}) — cursor not advanced for ${sources.length} rows`);
@@ -615,7 +813,7 @@ export async function collectAndSendTelemetry(
     }
   };
 
-  for (const filePath of files) {
+  for (const { filePath, kind } of files) {
     let stat;
     try {
       stat = await fs.stat(filePath);
@@ -627,11 +825,14 @@ export async function collectAndSendTelemetry(
 
     const stored = cursor.files[filePath] ?? { offset: 0, mtime: 0 };
     let offset = stored.offset;
+    let codexContext: CodexUsageContext | undefined =
+      kind === "codex" ? cloneCodexContext(stored.context ?? {}) : undefined;
 
     const rotated =
       currentSize < offset || (stored.mtime > 0 && currentMtime < stored.mtime);
     if (rotated) {
       offset = 0;
+      if (kind === "codex") codexContext = {};
       rotationResets[filePath] = { offset: 0, mtime: currentMtime };
     }
 
@@ -671,17 +872,28 @@ export async function collectAndSendTelemetry(
       } catch {
         continue;
       }
+      const startOffset = i === 0 ? offset : lineEndOffsets[i - 1];
+      const sourceRow =
+        kind === "codex"
+          ? codexUsageRow(
+              parsed,
+              codexContext!,
+              filePath,
+              startOffset,
+              lineEndOffsets[i],
+            )
+          : parsed;
       // Resolve this row's cwd → owning company (cmp_* uid) before sanitizing,
       // using the per-run map. Unresolved → undefined → companyUid omitted.
       const rowCwd =
-        parsed && typeof parsed === "object" && !Array.isArray(parsed)
-          ? (parsed as Record<string, unknown>).cwd
+        sourceRow && typeof sourceRow === "object" && !Array.isArray(sourceRow)
+          ? (sourceRow as Record<string, unknown>).cwd
           : undefined;
       const companyUid = resolveCompanyForCwd(
         typeof rowCwd === "string" ? rowCwd : undefined,
         repoCompanyMap,
       );
-      const sanitized = sanitizeRow(parsed, companyUid);
+      const sanitized = sanitizeRow(sourceRow, companyUid);
       if (!sanitized) continue;
       const maxRowBytes = MAX_BATCH_BYTES - ENVELOPE_BYTES;
       const wasOversized = jsonBytes(sanitized) > maxRowBytes;
@@ -722,6 +934,7 @@ export async function collectAndSendTelemetry(
         filePath,
         endOffset: lineEndOffsets[i],
         mtime: currentMtime,
+        ...(codexContext ? { context: cloneCodexContext(codexContext) } : {}),
       });
     }
   }
@@ -733,7 +946,13 @@ export async function collectAndSendTelemetry(
   for (const [fp, entry] of Object.entries(rotationResets)) finalFiles[fp] = entry;
   for (const [fp, entry] of Object.entries(newlyCommitted)) finalFiles[fp] = entry;
 
-  await saveCursor(cursorPath, { version: "1", files: finalFiles });
+  await saveCursor(cursorPath, {
+    version: "1",
+    files: finalFiles,
+    ...(cursor.codex_next_rollout
+      ? { codex_next_rollout: cursor.codex_next_rollout }
+      : {}),
+  });
 
   return {
     enabled: true,

package/src/vault-client.ts

@@ -513,6 +513,34 @@ export interface SkillInvocationBatch {
 /** Same wire shape as `UsageIngestResult`; aliased for call-site clarity. */
 export type SkillInvocationIngestResult = UsageIngestResult;
 
+// ---------------------------------------------------------------------------
+// Outcome events (hq-pro `/v1/outcome-events`)
+// ---------------------------------------------------------------------------
+
+export interface OutcomeEventsBatch {
+  /**
+   * Outcome-event rows. Each row is a plain object containing only the fields
+   * in the server's KEEP allowlist (type, occurredAt, companyUid, repo, branch,
+   * dedupeKey, and the type-specific refs projectName / storyId). Unlike the
+   * usage/skill batch, this batch carries NO machineId/installerVersion — the
+   * ingest handler (`apps/hq-pro/src/vault-service/handlers/outcome-events.ts`)
+   * accepts only `{ events }`. `personUid` MUST NOT appear on the batch or any
+   * event — hq-pro resolves the caller server-side from the Cognito JWT and
+   * REJECTS a body-supplied person identifier. Any field outside the allowlist
+   * is rejected with a 4xx `invalid-event`, so the emitter in
+   * `./outcome-telemetry.ts` is the only thing allowed to produce these.
+   */
+  events: Array<Record<string, unknown>>;
+}
+
+export interface OutcomeEventsIngestResult {
+  ok: boolean;
+  /** Rows newly written this request. */
+  written: number;
+  /** Rows collapsed by the server-side conditional put (idempotent replay). */
+  deduped: number;
+}
+
 // ---------------------------------------------------------------------------
 // Retry config
 // ---------------------------------------------------------------------------
@@ -692,6 +720,16 @@ const usageIngestResultSchema: VaultResponseSchema<UsageIngestResult> = z
   })
   .strip();
 
+const outcomeEventsIngestResultSchema: VaultResponseSchema<OutcomeEventsIngestResult> = z
+  .object({
+    ok: z.boolean(),
+    written: z.number().nonnegative(),
+    // Older/partial servers may omit `deduped`; default to 0 so a 2xx that
+    // reports only `written` still decodes (best-effort, matches usage rollout).
+    deduped: z.number().nonnegative().optional().transform((v) => v ?? 0),
+  })
+  .strip() as unknown as VaultResponseSchema<OutcomeEventsIngestResult>;
+
 /**
  * Accept the canonical v1 response and the previous raw-event aliases, then
  * normalize at this boundary so telemetry remains best-effort during rollout.
@@ -1446,6 +1484,23 @@ export class VaultClient {
     return this.post("/v1/skill-invocations", batch, usageIngestResultSchema);
   }
 
+  /**
+   * `POST /v1/outcome-events` — upload a batch of delivery-outcome events
+   * (story-completed / project-shipped, per outcome-leaderboard US-004).
+   *
+   * Same trust model as `postUsage`: `personUid` MUST NOT appear on the batch
+   * or any event — hq-pro resolves the caller from the JWT and rejects a
+   * body-supplied person identifier. Gated by the same telemetry opt-in as
+   * `/v1/usage`. Server-side conditional PutItem on the composite dedupeKey
+   * makes re-syncs and multi-machine replays idempotent (they count as
+   * `deduped`, never a double-write).
+   */
+  async postOutcomeEvents(
+    batch: OutcomeEventsBatch,
+  ): Promise<OutcomeEventsIngestResult> {
+    return this.post("/v1/outcome-events", batch, outcomeEventsIngestResultSchema);
+  }
+
   /**
    * `POST /v1/telemetry/events` — upload a capped batch of hq-cloud ACTION
    * events.