@indigoai-us/hq-cloud 6.14.0 → 6.14.2

package/src/telemetry-events.ts

@@ -0,0 +1,205 @@
+import type {
+  TelemetryEventsBatch,
+  TelemetryEventsIngestResult,
+} from "./vault-client.js";
+
+const MAX_EVENTS_PER_BATCH = 50;
+const DEFAULT_TIMEOUT_MS = 1500;
+const MAX_PROPERTIES = 40;
+const MAX_ARRAY_VALUES = 20;
+
+type TelemetryPrimitive = string | number;
+export type TelemetryProperties = Record<
+  string,
+  TelemetryPrimitive | TelemetryPrimitive[] | null | undefined
+>;
+
+export interface TelemetryEvent {
+  eventName: string;
+  source: string;
+  occurredAt?: string;
+  companyUid?: string;
+  agentUid?: string;
+  sessionId?: string;
+  schemaVersion?: 1;
+  properties?: TelemetryProperties;
+}
+
+export interface TelemetryClaims {
+  "custom:entityType"?: unknown;
+  "custom:entityUid"?: unknown;
+}
+
+export interface CloudTelemetryClient {
+  postTelemetryEvents?: (
+    batch: TelemetryEventsBatch,
+    options?: { timeoutMs?: number },
+  ) => Promise<TelemetryEventsIngestResult>;
+}
+
+export interface EmitCloudTelemetryOptions {
+  claims?: TelemetryClaims | null;
+  timeoutMs?: number;
+  log?: (message: string) => void;
+}
+
+const SAFE_KEY = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+const SAFE_LABEL = /^[A-Za-z0-9._:-]{1,128}$/;
+const BLOCKED_STRING_PROPERTY_KEY =
+  /(path|filename|name|email|secret|token|text|message|prompt|body|content|cwd|dir|url|uri|prefix|link)/i;
+
+export function agentUidFromClaims(
+  claims: TelemetryClaims | null | undefined,
+): string | undefined {
+  if (
+    claims?.["custom:entityType"] === "agent" &&
+    typeof claims["custom:entityUid"] === "string" &&
+    claims["custom:entityUid"].startsWith("agt_")
+  ) {
+    return claims["custom:entityUid"];
+  }
+  return undefined;
+}
+
+export async function emitCloudTelemetry(
+  client: CloudTelemetryClient | null | undefined,
+  events: TelemetryEvent | TelemetryEvent[],
+  options: EmitCloudTelemetryOptions = {},
+): Promise<void> {
+  if (!client?.postTelemetryEvents) return;
+
+  const derivedAgentUid = agentUidFromClaims(options.claims);
+  const now = new Date().toISOString();
+  const sanitized = (Array.isArray(events) ? events : [events])
+    .slice(0, MAX_EVENTS_PER_BATCH)
+    .map((event) => sanitizeEvent(event, now, derivedAgentUid))
+    .filter((event): event is TelemetryEventsBatch["events"][number] => event !== null);
+
+  if (sanitized.length === 0) return;
+
+  const timeoutMs = normalizeTimeout(options.timeoutMs);
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeout = setTimeout(
+      () => reject(new Error(`telemetry events timed out after ${timeoutMs}ms`)),
+      timeoutMs,
+    );
+    timeout.unref?.();
+  });
+
+  const postPromise = client
+    .postTelemetryEvents({ events: sanitized }, { timeoutMs })
+    .catch((err) => {
+      throw err;
+    });
+  postPromise.catch(() => undefined);
+
+  try {
+    await Promise.race([postPromise, timeoutPromise]);
+  } catch (err) {
+    warn(options.log, `postTelemetryEvents failed (${describeError(err)})`);
+  } finally {
+    if (timeout !== undefined) clearTimeout(timeout);
+  }
+}
+
+function sanitizeEvent(
+  event: TelemetryEvent,
+  fallbackOccurredAt: string,
+  derivedAgentUid: string | undefined,
+): TelemetryEventsBatch["events"][number] | null {
+  const eventName = safeLabel(event.eventName);
+  const source = safeLabel(event.source);
+  if (!eventName || !source) return null;
+
+  const occurredAt = safeIso(event.occurredAt) ?? fallbackOccurredAt;
+  const properties = sanitizeProperties(event.properties);
+  const companyUid = safeLabel(event.companyUid);
+  const agentUid = safeLabel(event.agentUid) ?? derivedAgentUid;
+  const sessionId = safeLabel(event.sessionId);
+
+  return {
+    eventName,
+    app: "hq-cloud",
+    source,
+    occurredAt,
+    ...(companyUid ? { companyUid } : {}),
+    ...(agentUid ? { agentUid } : {}),
+    ...(sessionId ? { sessionId } : {}),
+    schemaVersion: 1,
+    ...(properties ? { properties } : {}),
+  };
+}
+
+function sanitizeProperties(
+  properties: TelemetryProperties | undefined,
+): Record<string, unknown> | undefined {
+  if (!properties) return undefined;
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(properties)) {
+    if (Object.keys(out).length >= MAX_PROPERTIES) break;
+    if (!SAFE_KEY.test(key)) continue;
+    const sanitized = sanitizePropertyValue(key, value);
+    if (sanitized !== undefined) out[key] = sanitized;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+function sanitizePropertyValue(
+  key: string,
+  value: unknown,
+): TelemetryPrimitive | TelemetryPrimitive[] | undefined {
+  if (value === null || value === undefined) return undefined;
+  if (Array.isArray(value)) {
+    const values = value
+      .slice(0, MAX_ARRAY_VALUES)
+      .map((item) => sanitizeScalar(key, item))
+      .filter((item): item is TelemetryPrimitive => item !== undefined);
+    return values.length > 0 ? values : undefined;
+  }
+  return sanitizeScalar(key, value);
+}
+
+function sanitizeScalar(
+  key: string,
+  value: unknown,
+): TelemetryPrimitive | undefined {
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : undefined;
+  }
+  if (typeof value !== "string") return undefined;
+  if (BLOCKED_STRING_PROPERTY_KEY.test(key)) return undefined;
+  return safeLabel(value);
+}
+
+function safeLabel(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (!SAFE_LABEL.test(trimmed)) return undefined;
+  return trimmed;
+}
+
+function safeIso(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : undefined;
+}
+
+function normalizeTimeout(value: number | undefined): number {
+  if (value !== undefined && Number.isFinite(value) && value > 0) {
+    return Math.trunc(value);
+  }
+  return DEFAULT_TIMEOUT_MS;
+}
+
+function warn(log: ((message: string) => void) | undefined, message: string): void {
+  try {
+    (log ?? console.warn)(`[telemetry-events] ${message}`);
+  } catch {
+    /* diagnostics must never affect the caller */
+  }
+}
+
+function describeError(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/telemetry.ts

@@ -342,7 +342,7 @@ export async function collectAndSendTelemetry(
   // When `hqRoot` is omitted the map is empty → every event stays unattributed.
   const repoCompanyMap: RepoCompanyMap = opts.hqRoot
     ? await buildRepoCompanyMap(opts.hqRoot)
-    : { entries: [] };
+    : { entries: [], bySlug: new Map() };
 
   // 1. Opt-in check (server-authoritative, with local fallback).
   let enabled: boolean;

package/src/vault-client.test.ts

@@ -16,6 +16,7 @@ import {
   type EntityInfo,
   type ExplicitGrant,
   type MembershipSyncConfig,
+  type TelemetryEventsBatch,
 } from "./vault-client.js";
 
 // ---------------------------------------------------------------------------
@@ -275,6 +276,40 @@ describe("API surface", () => {
     });
   });
 
+  it("postTelemetryEvents sends action events without personUid", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { ok: true, written: 1, skipped: [] }),
+    );
+    const batch: TelemetryEventsBatch = {
+      events: [
+        {
+          eventName: "sync_runner_completed",
+          app: "hq-cloud",
+          source: "sync-runner",
+          occurredAt: "2026-07-07T12:00:00.000Z",
+          companyUid: "cmp_abc",
+          sessionId: "sync_123",
+          schemaVersion: 1,
+          properties: {
+            result: "completed",
+            fileCount: 2,
+          },
+        },
+      ],
+    };
+
+    const result = await client.postTelemetryEvents(batch);
+
+    expect(result).toEqual({ ok: true, written: 1, skipped: [] });
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://vault.test.example.com/v1/telemetry/events");
+    expect((init.method as string).toUpperCase()).toBe("POST");
+    const body = JSON.parse(init.body as string) as Record<string, unknown>;
+    expect(body).toEqual(batch);
+    expect(JSON.stringify(body)).not.toContain("personUid");
+  });
+
   it("updateRole sends correct payload", async () => {
     fetchSpy.mockResolvedValueOnce(
       jsonResponse(200, {
@@ -1067,7 +1102,10 @@ describe("setMembershipSyncConfig (US-004)", () => {
     await expect(
       client.setMembershipSyncConfig("psn_1#cmp_abc", { syncMode: "all" }),
     ).rejects.toThrow(/ETIMEDOUT/);
-    expect(fetchSpy).toHaveBeenCalledTimes(4);
+    const syncConfigCalls = fetchSpy.mock.calls.filter(([url]) =>
+      String(url).includes("/v1/memberships/psn_1%23cmp_abc/sync-config"),
+    );
+    expect(syncConfigCalls).toHaveLength(4);
   });
 });
 

package/src/vault-client.ts

@@ -8,6 +8,7 @@
 
 import type { ClientInfo, VaultServiceConfig } from "./types.js";
 import { buildClientHeaders } from "./client-info.js";
+import { emitCloudTelemetry } from "./telemetry-events.js";
 import { z } from "zod";
 
 // ---------------------------------------------------------------------------
@@ -432,6 +433,34 @@ export interface UsageIngestResult {
   skipped: Array<{ index: number; code: string; error: string }>;
 }
 
+// ---------------------------------------------------------------------------
+// Cloud action telemetry (hq-pro `/v1/telemetry/events`)
+// ---------------------------------------------------------------------------
+
+export interface RawTelemetryEventInput {
+  eventName: string;
+  app: "hq-cloud";
+  source: string;
+  occurredAt: string;
+  companyUid?: string;
+  agentUid?: string;
+  sessionId?: string;
+  schemaVersion?: 1;
+  properties?: Record<string, unknown>;
+}
+
+export interface TelemetryEventsBatch {
+  /**
+   * Action events emitted by sync/CLI surfaces. `personUid` MUST NOT appear in
+   * either the batch or any event — hq-pro resolves the caller server-side from
+   * the Cognito JWT and rejects client-supplied person identifiers.
+   */
+  events: RawTelemetryEventInput[];
+}
+
+/** Same wire shape as `UsageIngestResult`; aliased for call-site clarity. */
+export type TelemetryEventsIngestResult = UsageIngestResult;
+
 // ---------------------------------------------------------------------------
 // Skill-invocation telemetry (hq-pro `/v1/skill-invocations`)
 // ---------------------------------------------------------------------------
@@ -442,11 +471,11 @@ export interface SkillInvocationBatch {
   /**
    * Skill-invocation event rows. Each row contains only the fields in the
    * server's KEEP allowlist (skill, source, sessionId, timestamp, uuid, cwd,
-   * hasArgs, and the optional companyUid edge-attribution field — US-002).
-   * 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.
+   * hasArgs, the optional companyUid edge-attribution field — US-002, and the
+   * optional skillVersion content-hash marker — US-015). 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>>;
 }
@@ -461,6 +490,11 @@ export type SkillInvocationIngestResult = UsageIngestResult;
 const MAX_RETRIES = 3;
 const BASE_DELAY_MS = 500;
 
+interface VaultRequestOptions {
+  timeoutMs?: number;
+  maxRetries?: number;
+}
+
 function isTransient(status: number): boolean {
   return status === 429 || status >= 500;
 }
@@ -769,6 +803,12 @@ function summarizeZodIssues(issues: readonly z.core.$ZodIssue[]): string {
     .join("; ");
 }
 
+function companyUidFromMembershipId(membershipId: string): string | undefined {
+  const parts = membershipId.split("#");
+  const candidate = parts.length > 1 ? parts[parts.length - 1] : undefined;
+  return candidate?.startsWith("cmp_") ? candidate : undefined;
+}
+
 // ---------------------------------------------------------------------------
 // VaultClient
 // ---------------------------------------------------------------------------
@@ -1019,12 +1059,39 @@ export class VaultClient {
     membershipId: string,
     partial: SetMembershipSyncConfigInput,
   ): Promise<MembershipSyncConfig> {
-    return this.request(
-      "PUT",
-      `/v1/memberships/${encodeURIComponent(membershipId)}/sync-config`,
-      partial,
-      membershipSyncConfigSchema,
-    );
+    const companyUid = companyUidFromMembershipId(membershipId);
+    try {
+      const result = await this.request(
+        "PUT",
+        `/v1/memberships/${encodeURIComponent(membershipId)}/sync-config`,
+        partial,
+        membershipSyncConfigSchema,
+      );
+      void emitCloudTelemetry(this, {
+        eventName: "membership_sync_config_changed",
+        source: "vault-client",
+        ...(companyUid ? { companyUid } : {}),
+        properties: {
+          syncMode: result.syncMode,
+          customPathCount: result.customPaths?.length ?? 0,
+          result: "success",
+          defaultState: result.isDefault ? "default" : "configured",
+        },
+      });
+      return result;
+    } catch (err) {
+      void emitCloudTelemetry(this, {
+        eventName: "membership_sync_config_changed",
+        source: "vault-client",
+        ...(companyUid ? { companyUid } : {}),
+        properties: {
+          syncMode: partial.syncMode,
+          customPathCount: partial.customPaths?.length ?? 0,
+          result: "failure",
+        },
+      });
+      throw err;
+    }
   }
 
   // -- Entity operations ----------------------------------------------------
@@ -1265,6 +1332,25 @@ export class VaultClient {
     return this.post("/v1/skill-invocations", batch, usageIngestResultSchema);
   }
 
+  /**
+   * `POST /v1/telemetry/events` — upload a capped batch of hq-cloud ACTION
+   * events.
+   *
+   * Same trust model as `postUsage`: `personUid` MUST NOT appear in the body;
+   * hq-pro resolves the caller from the JWT and validates any `companyUid`
+   * against the caller's memberships. This endpoint is for server/CLI action
+   * telemetry and is not gated by the personal `/v1/usage` opt-in flag.
+   */
+  async postTelemetryEvents(
+    batch: TelemetryEventsBatch,
+    options: { timeoutMs?: number } = {},
+  ): Promise<TelemetryEventsIngestResult> {
+    return this.post("/v1/telemetry/events", batch, usageIngestResultSchema, {
+      timeoutMs: options.timeoutMs ?? 1500,
+      maxRetries: 0,
+    });
+  }
+
   // -- HTTP primitives with retry -------------------------------------------
 
   private async get<T>(path: string, schema: VaultResponseSchema<T>): Promise<T> {
@@ -1275,8 +1361,9 @@ export class VaultClient {
     path: string,
     body: unknown | undefined,
     schema: VaultResponseSchema<T>,
+    options?: VaultRequestOptions,
   ): Promise<T> {
-    return this.request("POST", path, body, schema);
+    return this.request("POST", path, body, schema, options);
   }
 
   private async request<T>(
@@ -1284,10 +1371,12 @@ export class VaultClient {
     path: string,
     body: unknown,
     schema: VaultResponseSchema<T>,
+    options: VaultRequestOptions = {},
   ): Promise<T> {
     let lastError: Error | undefined;
+    const maxRetries = options.maxRetries ?? MAX_RETRIES;
 
-    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
       if (attempt > 0) {
         const delay = BASE_DELAY_MS * Math.pow(2, attempt - 1);
         await sleep(delay);
@@ -1300,6 +1389,16 @@ export class VaultClient {
       };
 
       const init: RequestInit = { method, headers };
+      const controller =
+        options.timeoutMs !== undefined && options.timeoutMs > 0
+          ? new AbortController()
+          : undefined;
+      let timeout: ReturnType<typeof setTimeout> | undefined;
+      if (controller) {
+        timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+        timeout.unref?.();
+        init.signal = controller.signal;
+      }
 
       if (body !== undefined) {
         headers["Content-Type"] = "application/json";
@@ -1311,8 +1410,10 @@ export class VaultClient {
         res = await fetch(`${this.apiUrl}${path}`, init);
       } catch (err) {
         lastError = err instanceof Error ? err : new Error(String(err));
-        if (attempt < MAX_RETRIES) continue;
+        if (attempt < maxRetries) continue;
         throw lastError;
+      } finally {
+        if (timeout !== undefined) clearTimeout(timeout);
       }
 
       if (res.ok) {

package/src/watcher.test.ts

@@ -331,6 +331,46 @@ describe("US-002: createWatchPathFilter — personal-vault exclusions", () => {
     expect(personal(path.join(ROOT, "workspace"), false)).toBe(false);
   });
 
+  // ── workspace/agency subtree carve-out (personal mode) ──────────────────
+  // The personal push uploads workspace/agency/** (computeAgencySyncPaths), so
+  // the personal watcher must emit those changes event-driven, not leave them
+  // for the 60s poll. Mirrors the continuity-pointer carve-out, for a subtree.
+  it("DOES emit for workspace/agency files in personalMode (synced subtree)", () => {
+    expect(
+      personal(path.join(ROOT, "workspace/agency/indigo/nick/chat.jsonl")),
+    ).toBe(true);
+    expect(
+      personal(path.join(ROOT, "workspace/agency/indigo/nick/status.json")),
+    ).toBe(true);
+    // The agency root itself, as a file event, also emits.
+    expect(personal(path.join(ROOT, "workspace/agency"))).toBe(true);
+  });
+
+  it("allows chokidar to DESCEND to workspace/agency in personalMode (dir probes)", () => {
+    // workspace/ and workspace/agency queried as dirs must return true so the
+    // chokidar backend descends instead of pruning workspace/ at the top.
+    expect(personal(path.join(ROOT, "workspace"), true)).toBe(true);
+    expect(personal(path.join(ROOT, "workspace/agency"), true)).toBe(true);
+    expect(
+      personal(path.join(ROOT, "workspace/agency/indigo"), true),
+    ).toBe(true);
+  });
+
+  it("agency carve-out is exact-segment (does NOT leak to workspace/agencyX)", () => {
+    // Only workspace/agency (and its subtree) is re-included; a sibling whose
+    // name merely starts with 'agency' stays excluded like other workspace litter.
+    expect(personal(path.join(ROOT, "workspace/agencyX/foo.txt"))).toBe(false);
+    expect(personal(path.join(ROOT, "workspace/agency-notes.md"))).toBe(false);
+  });
+
+  it("agency carve-out does not re-include other workspace/ litter", () => {
+    // Regression: the new carve-out must not widen the workspace exclusion for
+    // anything other than agency + the continuity pointer.
+    expect(personal(path.join(ROOT, "workspace/locks/x.lock"))).toBe(false);
+    expect(personal(path.join(ROOT, "workspace/threads/T-old.json"))).toBe(false);
+    expect(personal(path.join(ROOT, "workspace/worktrees/x/a.ts"))).toBe(false);
+  });
+
   it("does not apply the carve-out in non-personal mode", () => {
     // In non-personal mode the excluded-top-level layer never runs, so the
     // carve-out is irrelevant; handoff.json passes via the ordinary ignore
@@ -350,6 +390,48 @@ describe("US-002: createWatchPathFilter — personal-vault exclusions", () => {
     // mode the ignore stack alone governs and lets it through.
     expect(nonPersonal(path.join(ROOT, "companies/indigo/board.json"))).toBe(true);
   });
+
+  // ── Never-synced heavy buckets pruned in BOTH modes ─────────────────────
+  // In --companies mode personalMode=false, so the excluded-top-level layer
+  // never ran and the watcher descended into the local git worktrees
+  // (workspace/worktrees/, ~200k transient files from agent coding runs) and
+  // the on-box repos checkout (repos/). Neither ever vault-syncs in any mode,
+  // so watching them only burns inotify watches (near the OS limit) + CPU on
+  // build churn it discards, and can trip the overflow→full-reconcile fallback.
+  it("non-personal mode EXCLUDES never-synced heavy buckets (workspace/worktrees, repos)", () => {
+    expect(
+      nonPersonal(path.join(ROOT, "workspace/worktrees/hq-console/src/a.ts")),
+    ).toBe(false);
+    // The bucket dir itself is pruned so chokidar never descends into it.
+    expect(nonPersonal(path.join(ROOT, "workspace/worktrees"), true)).toBe(false);
+    expect(
+      nonPersonal(path.join(ROOT, "repos/private/hq-cloud/src/x.ts")),
+    ).toBe(false);
+    expect(nonPersonal(path.join(ROOT, "repos"), true)).toBe(false);
+  });
+
+  it("non-personal mode STILL watches synced content (companies/, workspace/agency, continuity)", () => {
+    expect(
+      nonPersonal(path.join(ROOT, "companies/indigo/board.json")),
+    ).toBe(true);
+    expect(
+      nonPersonal(path.join(ROOT, "workspace/agency/indigo/nick/status.json")),
+    ).toBe(true);
+    expect(
+      nonPersonal(path.join(ROOT, "workspace/threads/handoff.json")),
+    ).toBe(true);
+    // chokidar must still descend into workspace/ to reach agency + continuity.
+    expect(nonPersonal(path.join(ROOT, "workspace"), true)).toBe(true);
+    // A worktrees SIBLING under workspace/ is unaffected (only worktrees pruned).
+    expect(
+      nonPersonal(path.join(ROOT, "workspace/agency"), true),
+    ).toBe(true);
+  });
+
+  it("personal mode still excludes worktrees + repos (regression, unchanged)", () => {
+    expect(personal(path.join(ROOT, "workspace/worktrees/x/a.ts"))).toBe(false);
+    expect(personal(path.join(ROOT, "repos/private/x/a.ts"))).toBe(false);
+  });
 });
 
 describe("US-002: TreeWatcher — debounce coalesce (FakeClock seam)", () => {