@mycadet/assistant 0.12.9 → 0.12.11

package/src/runtime/routes/internal-telemetry-routes.ts

@@ -1,142 +0,0 @@
-/**
- * Internal telemetry routes — receive operational signals forwarded from the
- * gateway over the internal (service-token) transport.
- *
- * POST /v1/internal/telemetry/auth-fallback — record aggregated counts of
- * requests served via the legacy loopback auth fallback. The gateway counts
- * fallbacks in memory and flushes them here per window; the usage telemetry
- * reporter ships the persisted rows to the cloud.
- *
- * POST /v1/internal/telemetry/watchdog — relay a gateway-origin watchdog
- * event straight to platform ingest via the direct (unbuffered) emit path,
- * bypassing the SQLite watchdog buffer. Used for integrity alarms (e.g.
- * `gateway_guardian_missing`) that must not depend on the state they report
- * on. Consent/platform gating happens inside the direct emit.
- */
-
-import { z } from "zod";
-
-import { getRawShareAnalytics } from "../../cloud/consent-cache.js";
-import {
-  type AuthFallbackCount,
-  recordAuthFallbackCounts,
-} from "../../security/auth-fallback-events-store.js";
-import { emitWatchdogEventDirect } from "../../telemetry/watchdog-direct-emit.js";
-import { getLogger } from "../../util/logger.js";
-import { GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
-import { BadRequestError, ServiceUnavailableError } from "./errors.js";
-import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
-
-const log = getLogger("internal-telemetry-routes");
-
-const authFallbackBody = z.object({
-  window_start: z.number().int().nonnegative(),
-  window_end: z.number().int().nonnegative(),
-  counts: z
-    .array(
-      z.object({
-        guard: z.string().min(1),
-        path: z.string().min(1),
-        failure_kind: z.string().min(1),
-        count: z.number().int().positive(),
-      }),
-    )
-    .min(1),
-});
-
-function handleRecordAuthFallback({ body }: RouteHandlerArgs) {
-  const parsed = authFallbackBody.safeParse(body);
-  if (!parsed.success) {
-    throw new BadRequestError(
-      `Invalid auth-fallback payload: ${parsed.error.message}`,
-    );
-  }
-  const { window_start, window_end, counts } = parsed.data;
-  const mapped: AuthFallbackCount[] = counts.map((c) => ({
-    guard: c.guard,
-    path: c.path,
-    failureKind: c.failure_kind,
-    count: c.count,
-  }));
-
-  const recorded = recordAuthFallbackCounts(window_start, window_end, mapped);
-  if (recorded === 0) {
-    if (getRawShareAnalytics() !== false) {
-      // Consent is not a confirmed opt-out but nothing was recorded (the
-      // body guarantees counts), so the telemetry DB is unavailable. Fail so
-      // the gateway's reporter merges the batch back and retries next flush
-      // instead of losing it.
-      throw new ServiceUnavailableError(
-        "Telemetry database unavailable; retry the auth-fallback batch",
-      );
-    }
-    // Confirmed share_analytics opt-out: drop the counts to honor it.
-    return { skipped: true };
-  }
-  log.debug({ recorded }, "Recorded auth-fallback counts");
-  return { recorded };
-}
-
-const watchdogRelayBody = z.object({
-  check_name: z.string().min(1).max(128),
-  detail: z.record(z.string(), z.unknown()).nullable().optional(),
-  value: z.number().nullable().optional(),
-});
-
-async function handleRelayWatchdogEvent({ body }: RouteHandlerArgs) {
-  const parsed = watchdogRelayBody.safeParse(body);
-  if (!parsed.success) {
-    throw new BadRequestError(
-      `Invalid watchdog payload: ${parsed.error.message}`,
-    );
-  }
-  const { check_name, detail, value } = parsed.data;
-  // Never throws; opt-out and platform gates are enforced inside.
-  await emitWatchdogEventDirect(check_name, detail ?? null, value ?? null);
-  return { ok: true as const };
-}
-
-export const ROUTES: RouteDefinition[] = [
-  {
-    operationId: "internal_telemetry_auth_fallback",
-    endpoint: "internal/telemetry/auth-fallback",
-    method: "POST",
-    policy: {
-      requiredScopes: ["internal.write"],
-      allowedPrincipalTypes: GATEWAY_PRINCIPALS,
-    },
-    summary: "Record auth-fallback counts",
-    description:
-      "Receives aggregated legacy-loopback auth-fallback counts forwarded by " +
-      "the gateway and persists them for telemetry reporting.",
-    tags: ["internal", "telemetry"],
-    requestBody: authFallbackBody,
-    responseBody: z.union([
-      z.object({ recorded: z.number().int().nonnegative() }),
-      z.object({
-        skipped: z
-          .literal(true)
-          .describe("Counts dropped because usage data collection is disabled"),
-      }),
-    ]),
-    handler: handleRecordAuthFallback,
-  },
-  {
-    operationId: "internal_telemetry_watchdog",
-    endpoint: "internal/telemetry/watchdog",
-    method: "POST",
-    policy: {
-      requiredScopes: ["internal.write"],
-      allowedPrincipalTypes: GATEWAY_PRINCIPALS,
-    },
-    summary: "Relay a watchdog telemetry event",
-    description:
-      "Emits a gateway-origin watchdog telemetry event directly to platform " +
-      "ingest, bypassing the SQLite watchdog buffer, so integrity alarms " +
-      "never depend on the state they report on.",
-    tags: ["internal", "telemetry"],
-    requestBody: watchdogRelayBody,
-    responseBody: z.object({ ok: z.literal(true) }),
-    handler: handleRelayWatchdogEvent,
-  },
-];

package/src/runtime/routes/telemetry-routes.ts

@@ -1,274 +0,0 @@
-/**
- * Route handlers for telemetry lifecycle events.
- *
- * POST /v1/telemetry/lifecycle — record a lifecycle event (app_open, hatch).
- * POST /v1/telemetry/ingest — record any outbox-backed telemetry event by its
- * wire `type` + `fields`.
- */
-
-import { z } from "zod";
-
-import { recordLifecycleEvent } from "../../persistence/lifecycle-events-store.js";
-import { recordTelemetryOutboxEvent } from "../../telemetry/telemetry-events-outbox.js";
-import {
-  getWireFieldsSchema,
-  getWireSchemaForType,
-} from "../../telemetry/telemetry-wire-validation.js";
-import type {
-  OutboxTelemetryEventName,
-  TelemetryEvent,
-} from "../../telemetry/types.js";
-import { OUTBOX_TELEMETRY_EVENT_NAMES } from "../../telemetry/types.js";
-import { getUsageTelemetryReporter } from "../../telemetry/usage-telemetry-reporter.js";
-import { getLogger } from "../../util/logger.js";
-import { APP_VERSION } from "../../version.js";
-import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
-import { BadRequestError } from "./errors.js";
-import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
-
-const log = getLogger("telemetry-routes");
-
-const VALID_EVENT_NAMES = new Set(["app_open", "hatch"]);
-
-const ingestDaemonEventIdSchema = z
-  .string()
-  .min(1)
-  .max(128)
-  .optional()
-  .describe(
-    "Optional collapse key: rows sharing an id collapse downstream " +
-      "(e.g. a retried report). Defaults to a fresh per-row id.",
-  );
-
-/**
- * One request variant per outbox-backed type: `{ type, fields, daemon_event_id? }`
- * where `fields` is the wire schema for that type minus the daemon-stamped base
- * fields. Throws at module load if an outbox name has no wire schema (an
- * impossible drift between the outbox name list and the wire contract).
- */
-function buildIngestVariant(name: OutboxTelemetryEventName) {
-  const fields = getWireFieldsSchema(name);
-  if (!fields) {
-    throw new Error(`No wire schema for outbox telemetry type "${name}".`);
-  }
-  return z.object({
-    type: z.literal(name),
-    fields: fields.describe(
-      "Wire event fields, excluding the daemon-stamped base fields " +
-        "(type, daemon_event_id, recorded_at, assistant_version).",
-    ),
-    daemon_event_id: ingestDaemonEventIdSchema,
-  });
-}
-
-/**
- * Request shape for `POST /v1/telemetry/ingest`: a discriminated union over
- * every outbox-backed event type, each carrying that type's wire `fields`.
- * Derived from the wire contract, so the generated SDK body is strongly typed
- * and stays in sync as the wire schemas evolve.
- */
-const telemetryIngestRequestSchema = z.discriminatedUnion(
-  "type",
-  // `.map` widens to `ZodObject[]`, but `discriminatedUnion` wants a non-empty
-  // tuple. The outbox name list is non-empty, and the RUNTIME schema (not this
-  // static type) is what codegen introspects, so the cast doesn't affect the
-  // emitted OpenAPI/SDK types.
-  OUTBOX_TELEMETRY_EVENT_NAMES.map(buildIngestVariant) as [
-    ReturnType<typeof buildIngestVariant>,
-    ...ReturnType<typeof buildIngestVariant>[],
-  ],
-);
-
-/** Placeholder id satisfying the wire schema's `daemon_event_id` bound during
- * the up-front validation pass; the real id is stamped at record time. */
-const VALIDATION_PROBE_DAEMON_EVENT_ID = "validation-probe";
-
-function handleRecordLifecycleEvent({ body }: RouteHandlerArgs) {
-  const eventName = body?.event_name as string | undefined;
-  if (!eventName || !VALID_EVENT_NAMES.has(eventName)) {
-    throw new BadRequestError(
-      `event_name must be one of: ${[...VALID_EVENT_NAMES].join(", ")}`,
-    );
-  }
-
-  const event = recordLifecycleEvent(eventName);
-  if (!event) {
-    return { skipped: true };
-  }
-  log.info({ eventName, eventId: event.id }, "Recorded lifecycle event");
-
-  return { id: event.id, event_name: event.eventName };
-}
-
-async function handleTelemetryFlush() {
-  const reporter = getUsageTelemetryReporter();
-  if (!reporter) {
-    return { flushed: false, reason: "disabled" };
-  }
-  return reporter.flush();
-}
-
-/**
- * Record any outbox-backed telemetry event reported by a client. This is the
- * generic bridge that exposes the daemon's in-process `recordTelemetryEvent`
- * recorder to clients over HTTP/IPC — for events the client observes and the
- * daemon can't detect on its own (e.g. `onboarding_research`).
- *
- * Three guarantees before a row lands:
- *   1. `type` must be an outbox-backed event and `fields` must match that
- *      type's wire shape — both enforced by the discriminated-union parse. The
- *      watermark types (`turn`, `llm_usage`, `tool_executed`) are excluded
- *      structurally: they aren't outbox-backed, so they have no variant.
- *   2. The assembled event must additionally pass the full wire schema for the
- *      byte-bound superRefines the request `fields` schema drops (oversize
- *      claims/suggestions).
- *   3. Consent is enforced by {@link recordTelemetryOutboxEvent} (the
- *      `share_analytics` gate), same as every daemon-internal emitter.
- *
- * An optional `daemon_event_id` lets the client supply a collapse key (e.g. a
- * refresh-retried report reusing a conversation-scoped id); it defaults to the
- * fresh row id. A `conversation_id` field on the event is threaded into the
- * outbox row's dedicated column so pending rows redact on conversation deletion
- * via the indexed delete.
- */
-function handleTelemetryIngest({ body }: RouteHandlerArgs) {
-  const parsed = telemetryIngestRequestSchema.safeParse(body);
-  if (!parsed.success) {
-    throw new BadRequestError(parsed.error.message);
-  }
-  const { type, fields, daemon_event_id: daemonEventId } = parsed.data;
-
-  // `type` matched a union variant (an outbox-backed event), so a wire schema
-  // is guaranteed — its absence is an invariant breach, not a client error.
-  const wireSchema = getWireSchemaForType(type);
-  if (!wireSchema) {
-    throw new Error(`No wire schema registered for outbox type "${type}".`);
-  }
-
-  // Re-validate the assembled event against the full wire schema for the
-  // byte-bound superRefines the request `fields` schema drops. Up front (with
-  // placeholder base values) so an oversize payload 400s regardless of consent.
-  // The `.trim()`-transformed parse output is discarded: `fields` are recorded
-  // verbatim, matching pre-flush validation's non-mutating contract.
-  const validation = wireSchema.safeParse({
-    ...fields,
-    type,
-    daemon_event_id: daemonEventId ?? VALIDATION_PROBE_DAEMON_EVENT_ID,
-    recorded_at: 0,
-    assistant_version: APP_VERSION,
-  });
-  if (!validation.success) {
-    throw new BadRequestError(validation.error.message);
-  }
-
-  const conversationId =
-    "conversation_id" in fields && typeof fields.conversation_id === "string"
-      ? fields.conversation_id
-      : null;
-
-  const event = recordTelemetryOutboxEvent(
-    type,
-    (id, createdAt): TelemetryEvent =>
-      // Base fields stamped after the spread so a `fields` payload carrying a
-      // base key can never override the daemon's stamp.
-      ({
-        ...fields,
-        type,
-        daemon_event_id: daemonEventId ?? id,
-        recorded_at: createdAt,
-        assistant_version: APP_VERSION,
-      }) as TelemetryEvent,
-    { conversationId },
-  );
-  if (!event) {
-    return { skipped: true };
-  }
-  log.info({ type, eventId: event.id }, "Recorded client telemetry event");
-
-  return { id: event.id };
-}
-
-export const ROUTES: RouteDefinition[] = [
-  {
-    operationId: "telemetry_lifecycle",
-    endpoint: "telemetry/lifecycle",
-    method: "POST",
-    policy: {
-      requiredScopes: ["settings.write"],
-      allowedPrincipalTypes: ACTOR_PRINCIPALS,
-    },
-    summary: "Record lifecycle event",
-    description: "Record a telemetry lifecycle event (app_open, hatch).",
-    tags: ["telemetry"],
-    requestBody: z.object({
-      event_name: z.string().describe("Event name: app_open or hatch"),
-    }),
-    responseBody: z.union([
-      z.object({
-        id: z.string().describe("Event ID"),
-        event_name: z.string(),
-      }),
-      z.object({
-        skipped: z
-          .literal(true)
-          .describe(
-            "Event skipped due to usage data collection being disabled",
-          ),
-      }),
-    ]),
-    handler: handleRecordLifecycleEvent,
-  },
-  {
-    operationId: "telemetry_flush",
-    endpoint: "telemetry/flush",
-    method: "POST",
-    policy: {
-      requiredScopes: ["settings.write"],
-      allowedPrincipalTypes: ACTOR_PRINCIPALS,
-    },
-    summary: "Flush pending telemetry events",
-    description:
-      "Force-flush the telemetry events owned by the assistant process (turn events) to the cloud. Other event types are flushed on their own cycle by the resource monitor process.",
-    tags: ["telemetry"],
-    responseBody: z.union([
-      z.object({
-        flushed: z.literal(true),
-        sent: z.number().describe("Events POSTed to the cloud"),
-        persisted: z.number().describe("Events the cloud confirmed written"),
-        dropped: z
-          .number()
-          .describe("Events that did not land (sent - persisted)"),
-      }),
-      z.object({
-        flushed: z.literal(false),
-        reason: z.string(),
-      }),
-    ]),
-    handler: handleTelemetryFlush,
-  },
-  {
-    operationId: "telemetry_ingest",
-    endpoint: "telemetry/ingest",
-    method: "POST",
-    policy: {
-      requiredScopes: ["settings.write"],
-      allowedPrincipalTypes: ACTOR_PRINCIPALS,
-    },
-    summary: "Record an outbox-backed telemetry event",
-    description:
-      "Record any outbox-backed telemetry event by its wire `type` + `fields`. For events a client observes and the daemon can't detect on its own (e.g. onboarding_research). The type must be an outbox-backed event — the watermark types (turn, llm_usage, tool_executed) have no variant — and the payload must pass the cloud wire schema. Gated on share_analytics consent like every other outbox-backed event; the cloud re-checks the owner's consent server-side at ingest.",
-    tags: ["telemetry"],
-    requestBody: telemetryIngestRequestSchema,
-    responseBody: z.union([
-      z.object({ id: z.string().describe("Event ID") }),
-      z.object({
-        skipped: z
-          .literal(true)
-          .describe(
-            "Event skipped: usage data collection is disabled or the telemetry database is unavailable",
-          ),
-      }),
-    ]),
-    handler: handleTelemetryIngest,
-  },
-];

package/src/security/auth-fallback-events-store.ts

@@ -1,57 +0,0 @@
-import { v4 as uuid } from "uuid";
-
-import { getRawShareAnalytics } from "../cloud/consent-cache.js";
-import { insertTelemetryOutboxEvents } from "../telemetry/telemetry-events-outbox.js";
-import type { AuthFallbackTelemetryEvent } from "../telemetry/types.js";
-import { APP_VERSION } from "../version.js";
-
-/** A single aggregated auth-fallback count for one (guard, path, failure_kind). */
-export interface AuthFallbackCount {
-  guard: string;
-  path: string;
-  failureKind: string;
-  count: number;
-}
-
-/**
- * Record a batch of aggregated auth-fallback counts forwarded by the gateway —
- * one `telemetry_events` outbox row per count entry, all sharing the same
- * flush window, each carrying its full wire event built at record time. The
- * whole batch inserts atomically, so a failure never leaves a partial batch
- * committed (the gateway retries the full batch on `recorded === 0`). Returns
- * the number of rows recorded, or 0 when `share_analytics` is a confirmed
- * opt-out (the counts are dropped to honor it, matching the rest of
- * telemetry — an unknown consent state records) or the telemetry database is
- * unavailable (degraded mode). Callers that must tell those apart check
- * `getRawShareAnalytics()` themselves.
- */
-export function recordAuthFallbackCounts(
-  windowStart: number,
-  windowEnd: number,
-  counts: AuthFallbackCount[],
-): number {
-  if (getRawShareAnalytics() === false) {
-    return 0;
-  }
-  if (counts.length === 0) {
-    return 0;
-  }
-  const createdAt = Date.now();
-  const rows = counts.map((c) => {
-    const id = uuid();
-    const event: AuthFallbackTelemetryEvent = {
-      type: "auth_fallback",
-      daemon_event_id: id,
-      recorded_at: createdAt,
-      guard: c.guard,
-      path: c.path,
-      failure_kind: c.failureKind,
-      count: c.count,
-      window_start: windowStart,
-      window_end: windowEnd,
-      assistant_version: APP_VERSION,
-    };
-    return { id, name: "auth_fallback", createdAt, event };
-  });
-  return insertTelemetryOutboxEvents(rows) ? rows.length : 0;
-}

package/src/telemetry/__tests__/activation-funnel.test.ts

@@ -1,95 +0,0 @@
-import { describe, expect, test } from "bun:test";
-
-import {
-  ACTIVATION_MOMENT_PARAMS,
-  ACTIVATION_STEPS,
-  activationStepIndex,
-  activationStepNameForMomentParam,
-  buildActivationDaemonEventId,
-  isActivationMomentParam,
-  isActivationStepName,
-} from "../activation-funnel.js";
-
-const ALL_STEP_NAMES = Object.values(ACTIVATION_STEPS).map((s) => s.stepName);
-
-describe("activation funnel vocabulary", () => {
-  test("step indices are 1-5 and unique", () => {
-    const indices = Object.values(ACTIVATION_STEPS).map((s) => s.stepIndex);
-    expect([...indices].sort((a, b) => a - b)).toEqual([1, 2, 3, 4, 5]);
-    expect(new Set(indices).size).toBe(indices.length);
-  });
-
-  test("activationStepIndex resolves index from name", () => {
-    for (const { stepName, stepIndex } of Object.values(ACTIVATION_STEPS)) {
-      expect(activationStepIndex(stepName)).toBe(stepIndex);
-    }
-  });
-
-  test("isActivationStepName accepts all five step names", () => {
-    expect(ALL_STEP_NAMES).toHaveLength(5);
-    for (const stepName of ALL_STEP_NAMES) {
-      expect(isActivationStepName(stepName)).toBe(true);
-    }
-  });
-
-  test("isActivationStepName rejects unknown names", () => {
-    expect(isActivationStepName("bogus")).toBe(false);
-  });
-
-  test("buildActivationDaemonEventId is deterministic", () => {
-    expect(
-      buildActivationDaemonEventId("conv-abc", "activation_moment_1_complete"),
-    ).toBe("activation_v1_2026_06:conv-abc:activation_moment_1_complete");
-  });
-});
-
-describe("activation moment param (model-facing tag)", () => {
-  test("ACTIVATION_MOMENT_PARAMS lists the five tokens in step order", () => {
-    expect(ACTIVATION_MOMENT_PARAMS).toEqual([
-      "moment_1",
-      "moment_2",
-      "moment_3",
-      "first_wow_executed",
-      "first_wow_interacted",
-    ]);
-  });
-
-  test("isActivationMomentParam accepts all five tokens", () => {
-    for (const param of ACTIVATION_MOMENT_PARAMS) {
-      expect(isActivationMomentParam(param)).toBe(true);
-    }
-  });
-
-  test("isActivationMomentParam rejects unknown tokens (incl. wire step names)", () => {
-    expect(isActivationMomentParam("bogus")).toBe(false);
-    // The wire step name is NOT a valid model-facing token.
-    expect(isActivationMomentParam("activation_moment_1_complete")).toBe(false);
-    expect(isActivationMomentParam("moment_4")).toBe(false);
-  });
-
-  test("activationStepNameForMomentParam maps each token to its step name", () => {
-    expect(activationStepNameForMomentParam("moment_1")).toBe(
-      ACTIVATION_STEPS.moment1.stepName,
-    );
-    expect(activationStepNameForMomentParam("moment_2")).toBe(
-      ACTIVATION_STEPS.moment2.stepName,
-    );
-    expect(activationStepNameForMomentParam("moment_3")).toBe(
-      ACTIVATION_STEPS.moment3.stepName,
-    );
-    expect(activationStepNameForMomentParam("first_wow_executed")).toBe(
-      ACTIVATION_STEPS.firstWowExecuted.stepName,
-    );
-    expect(activationStepNameForMomentParam("first_wow_interacted")).toBe(
-      ACTIVATION_STEPS.firstWowInteracted.stepName,
-    );
-  });
-
-  test("every moment param maps to a valid wire step name", () => {
-    for (const param of ACTIVATION_MOMENT_PARAMS) {
-      expect(
-        isActivationStepName(activationStepNameForMomentParam(param)),
-      ).toBe(true);
-    }
-  });
-});

package/src/telemetry/__tests__/config-setting-events-store.test.ts

@@ -1,63 +0,0 @@
-import { beforeEach, describe, expect, test } from "bun:test";
-
-import { APP_VERSION } from "../../version.js";
-import { recordConfigSettingEvent } from "../config-setting-events-store.js";
-import {
-  pendingOutboxPayloads,
-  pendingOutboxRows,
-  resetOutboxTable,
-  setShareAnalytics,
-} from "./outbox-test-harness.js";
-
-describe("config-setting-events-store", () => {
-  beforeEach(() => {
-    setShareAnalytics(true);
-    resetOutboxTable();
-  });
-
-  test("honors the share_analytics opt-out (records nothing, returns false)", () => {
-    setShareAnalytics(false);
-    expect(
-      recordConfigSettingEvent({
-        configKey: "memory.enabled",
-        configValue: "true",
-      }),
-    ).toBe(false);
-    expect(pendingOutboxRows("config_setting", 10)).toHaveLength(0);
-  });
-
-  test("records the full wire event and returns true", () => {
-    expect(
-      recordConfigSettingEvent({
-        configKey: "memory.v2.enabled",
-        configValue: "false",
-      }),
-    ).toBe(true);
-
-    const rows = pendingOutboxRows("config_setting", 10);
-    expect(rows).toHaveLength(1);
-    const row = rows[0]!;
-    expect(row.id).toBeString();
-    expect(row.createdAt).toBeGreaterThan(0);
-    expect(JSON.parse(row.payload)).toEqual({
-      type: "config_setting",
-      daemon_event_id: row.id,
-      recorded_at: row.createdAt,
-      config_key: "memory.v2.enabled",
-      config_value: "false",
-      assistant_version: APP_VERSION,
-    });
-  });
-
-  test("clamps oversize key and value to the cloud bounds", () => {
-    recordConfigSettingEvent({
-      configKey: "k".repeat(200),
-      configValue: "v".repeat(300),
-    });
-
-    const payloads = pendingOutboxPayloads("config_setting");
-    expect(payloads).toHaveLength(1);
-    expect(payloads[0]!.config_key).toBe("k".repeat(128));
-    expect(payloads[0]!.config_value).toBe("v".repeat(256));
-  });
-});