@mycadet/assistant 0.12.9 → 0.12.11

package/src/telemetry/config-setting-snapshot.ts

@@ -1,170 +0,0 @@
-import { getRawShareAnalytics } from "../cloud/consent-cache.js";
-import { getConfigReadOnly } from "../config/loader.js";
-import type { AssistantConfig } from "../config/schema.js";
-import { getLogger } from "../util/logger.js";
-import { recordConfigSettingEvent } from "./config-setting-events-store.js";
-
-const log = getLogger("config-setting-snapshot");
-
-/**
- * How often the config snapshot re-records the tracked settings. The snapshot
- * memoizes per key, so a steady-state tick records nothing; the cadence
- * exists so the first opted-in tick (consent resolves asynchronously after
- * boot) lands and a live config edit is captured within one window. Hourly is
- * ample — these values change rarely and every boot re-asserts them.
- */
-const CONFIG_SNAPSHOT_INTERVAL_MS = 60 * 60 * 1000;
-
-/**
- * The explicit allowlist of settings reported as `config_setting` telemetry,
- * as `(config_key, config_value)` pairs. Keys are dotted config paths; values
- * are the effective (defaults-applied) values rendered as strings. Add only
- * non-sensitive settings — never free-form config content, paths, or
- * credentials.
- *
- * Optional chaining is defensive: the effective config always carries these
- * fields, but a partial config (a mocked config in tests) skips the key
- * rather than recording a bogus value or throwing out of the emitter.
- */
-function trackedConfigSettings(
-  config: AssistantConfig,
-): ReadonlyArray<readonly [string, string]> {
-  const pairs: ReadonlyArray<readonly [string, boolean | undefined]> = [
-    ["memory.enabled", config.memory?.enabled],
-    ["memory.v2.enabled", config.memory?.v2?.enabled],
-    ["memory.v3.live", config.memory?.v3?.live],
-  ];
-  return pairs
-    .filter((pair): pair is readonly [string, boolean] => pair[1] != null)
-    .map(([key, value]) => [key, String(value)] as const);
-}
-
-/**
- * Per-process memo of the last value recorded for each tracked key, so a
- * repeated snapshot only persists a row when the effective value actually
- * changed. Process-scoped on purpose: a restart re-records the current
- * values, giving downstream consumers a fresh per-boot assertion of each
- * setting.
- */
-const lastRecorded = new Map<string, string>();
-
-/**
- * Record a `config_setting` event for every tracked setting whose effective
- * value differs from what this process last recorded.
- *
- * Consent-gated with a memo reset on opt-out. While `share_analytics` is a
- * confirmed opt-out, nothing is recorded and the memo is cleared: the
- * reporter's opt-out flush discards any config_setting rows still pending
- * upload, so a memo entry from before the opt-out no longer corresponds to a
- * delivered row. Clearing it means a later re-opt-in (in the same process,
- * unchanged config) re-records the full current snapshot rather than skipping
- * memoized keys — consumers that expect a complete snapshot after re-opt-in
- * stay correct. An UNKNOWN consent state skips entirely (no record, no memo,
- * no clear): unlike outbox events, a snapshot is re-derivable state, so
- * deferring it loses nothing — while recording it would either memoize a row
- * a later opt-out purge invalidates, or (without the memo) double-record on
- * every boot.
- *
- * Retry-friendly when opted in: `recordConfigSettingEvent` returns false when
- * the telemetry DB is momentarily unavailable, and the memo is only advanced
- * on a real persist, so a caller that re-invokes this each cycle records the
- * snapshot on its first cycle with a resolvable DB, then stays quiet until a
- * value changes. Never throws — a storage failure is logged and the key
- * retries on the next invocation.
- */
-export function recordConfigSettingSnapshot(config: AssistantConfig): void {
-  const consent = getRawShareAnalytics();
-  if (consent === "unknown") {
-    return;
-  }
-  if (consent === false) {
-    lastRecorded.clear();
-    return;
-  }
-  for (const [configKey, configValue] of trackedConfigSettings(config)) {
-    if (lastRecorded.get(configKey) === configValue) {
-      continue;
-    }
-    try {
-      if (recordConfigSettingEvent({ configKey, configValue })) {
-        lastRecorded.set(configKey, configValue);
-      }
-    } catch (err) {
-      log.warn(
-        { err, configKey },
-        "Failed to record config_setting telemetry event — will retry on the next snapshot",
-      );
-    }
-  }
-}
-
-let snapshotTimer: ReturnType<typeof setInterval> | null = null;
-let bootRetryTimer: ReturnType<typeof setTimeout> | null = null;
-
-// The boot-time snapshot races the first consent refresh (fire-and-forget in
-// the monitor's startup), so consent is usually still "unknown" on the first
-// call and the snapshot is skipped. Retry on a short timer until consent
-// resolves rather than waiting a full hourly interval for the per-boot
-// assertion.
-const BOOT_RETRY_INTERVAL_MS = 60_000;
-
-function recordSnapshotFromConfig(): void {
-  try {
-    // `getConfigReadOnly()` re-reads config.json on change (capturing live
-    // edits) and never writes to disk — safe for the monitor process.
-    recordConfigSettingSnapshot(getConfigReadOnly());
-  } catch (err) {
-    log.warn({ err }, "Config-setting snapshot failed (non-fatal)");
-  }
-}
-
-function recordBootSnapshotOnceConsentKnown(): void {
-  if (getRawShareAnalytics() === "unknown") {
-    bootRetryTimer = setTimeout(
-      recordBootSnapshotOnceConsentKnown,
-      BOOT_RETRY_INTERVAL_MS,
-    );
-    bootRetryTimer.unref?.();
-    return;
-  }
-  bootRetryTimer = null;
-  recordSnapshotFromConfig();
-}
-
-/**
- * Start the config-setting snapshot loop in the resource monitor process:
- * record the tracked settings once at boot, then hourly. No-op in dev mode
- * (CADET_DEV=1) and idempotent if already started. Mirrors
- * {@link import("./usage-telemetry-reporter.js").startMonitorUsageTelemetryReporter}
- * — the snapshot feeds the same config_setting pipeline the monitor flushes.
- */
-export function startConfigSnapshotReporter(): void {
-  if (process.env.CADET_DEV === "1") {
-    return;
-  }
-  if (snapshotTimer) {
-    return;
-  }
-  recordBootSnapshotOnceConsentKnown();
-  snapshotTimer = setInterval(
-    recordSnapshotFromConfig,
-    CONFIG_SNAPSHOT_INTERVAL_MS,
-  );
-}
-
-/** Stop the config-setting snapshot loop. Idempotent. */
-export function stopConfigSnapshotReporter(): void {
-  if (snapshotTimer) {
-    clearInterval(snapshotTimer);
-    snapshotTimer = null;
-  }
-  if (bootRetryTimer) {
-    clearTimeout(bootRetryTimer);
-    bootRetryTimer = null;
-  }
-}
-
-/** Test-only: clear the per-process last-recorded memo. */
-export function resetConfigSettingSnapshotForTesting(): void {
-  lastRecorded.clear();
-}

package/src/telemetry/flush-checkpoints.ts

@@ -1,70 +0,0 @@
-import { eq } from "drizzle-orm";
-
-import { getTelemetryDb } from "../persistence/db-connection.js";
-import { flushCheckpoints } from "../persistence/schema/index.js";
-
-/**
- * Telemetry flush state — the per-event-type watermark cursors the usage
- * telemetry reporter advances after each successful upload. Backed by the
- * `flush_checkpoints` table on the dedicated telemetry database
- * (`assistant-telemetry.db`); the main DB's `memory_checkpoints` ledger is
- * reserved for DB-migration checkpoints.
- *
- * Reads and writes throw when the table is missing (migrations not yet run)
- * and are no-op/null when the telemetry DB cannot be opened at all. Callers
- * that must not mistake an unreadable store for "no watermark" (which would
- * re-ship history from cursor 0) should gate on
- * {@link isFlushCheckpointStoreAvailable} first.
- */
-
-/** True when the telemetry DB connection is open. */
-export function isFlushCheckpointStoreAvailable(): boolean {
-  return getTelemetryDb() != null;
-}
-
-export function getFlushCheckpoint(key: string): string | null {
-  const db = getTelemetryDb();
-  if (!db) {
-    return null;
-  }
-  const row = db
-    .select({ value: flushCheckpoints.value })
-    .from(flushCheckpoints)
-    .where(eq(flushCheckpoints.key, key))
-    .get();
-  return row?.value ?? null;
-}
-
-export function setFlushCheckpoint(key: string, value: string): void {
-  const db = getTelemetryDb();
-  if (!db) {
-    return;
-  }
-  const now = Date.now();
-  db.insert(flushCheckpoints)
-    .values({ key, value, updatedAt: now })
-    .onConflictDoUpdate({
-      target: flushCheckpoints.key,
-      set: { value, updatedAt: now },
-    })
-    .run();
-}
-
-/**
- * Watermark storage seam for the usage telemetry reporter. The reporter
- * takes this as a constructor dependency (defaulting to
- * {@link telemetryDbFlushCheckpointStore}) so tests can substitute an
- * in-memory fake without process-global module mocking.
- */
-export interface FlushCheckpointStore {
-  isAvailable(): boolean;
-  get(key: string): string | null;
-  set(key: string, value: string): void;
-}
-
-/** The production store, backed by the telemetry DB's `flush_checkpoints`. */
-export const telemetryDbFlushCheckpointStore: FlushCheckpointStore = {
-  isAvailable: isFlushCheckpointStoreAvailable,
-  get: getFlushCheckpoint,
-  set: setFlushCheckpoint,
-};

package/src/telemetry/live-voice-funnel.ts

@@ -1,185 +0,0 @@
-/**
- * Live-voice session telemetry vocabulary: the single source of truth for the
- * step names, funnel version, and end-reason values the live-voice session
- * emitter uses.
- *
- * Rides the existing onboarding telemetry substrate (`type: "onboarding"`),
- * exactly as `activation-funnel.ts` does: the backend stores `step_name` and
- * `funnel_version` as open strings, so this funnel needs no platform serializer
- * and no wire-contract change.
- *
- * **Duration is not a field.** The onboarding event shape carries no numeric
- * slot for it, so the two events below are keyed by the live-voice `sessionId`
- * in `session_id` and the warehouse subtracts their `recorded_at` stamps. That
- * yields exact percentiles rather than the bucketed-string dimension the tips
- * and tour funnels pack into `screen`.
- *
- * **Turn count is not a field either.** It comes from the `turn` telemetry
- * events voice turns already produce, which carry this session's id in their
- * `client` bag (see `voice-session-bridge.ts`), so a turn count is a count of
- * those rows rather than a number restated here.
- *
- * A session that starts and never ends is **censored, not infinite**: a daemon
- * crash or kill emits no end event, so downstream duration math must drop
- * unmatched `started` rows instead of treating them as open-ended sessions.
- */
-
-import type { ClientOs } from "../channels/types.js";
-import type { LiveVoiceSessionCloseReason } from "../live-voice/live-voice-session-manager.js";
-import type { LiveVoiceProtocolErrorCode } from "../live-voice/protocol.js";
-
-/** Funnel version stamped on every live-voice session event. */
-export const LIVE_VOICE_FUNNEL_VERSION = "live_voice_v1_2026_08";
-
-/**
- * Live-voice session funnel steps. `stepName` is the wire value; `stepIndex`
- * is the ordinal position.
- *
- * `sessionStarted` fires for every *attempted* session, before the credential
- * preflight that can reject it. A session that fails to connect is exactly the
- * one worth counting, and gating the start event on `ready` would hide it from
- * the failure rate entirely.
- */
-export const LIVE_VOICE_STEPS = {
-  sessionStarted: { stepName: "live_voice_session_started", stepIndex: 0 },
-  sessionEnded: { stepName: "live_voice_session_ended", stepIndex: 1 },
-} as const;
-
-export type LiveVoiceStepName =
-  (typeof LIVE_VOICE_STEPS)[keyof typeof LIVE_VOICE_STEPS]["stepName"];
-
-/**
- * How a session ended, stamped as `outcome`.
- *
- * `failed` means the session died on an error: a credential preflight
- * rejection before `ready`, or an utterance-arm failure after it. Everything
- * else, including a dropped socket, is `completed`: the session ran and then
- * stopped, and the close reason on `screen` says how.
- */
-export type LiveVoiceSessionOutcome = "completed" | "failed";
-
-/**
- * How far a session that produced NO turn actually got.
- *
- * A quarter of live-voice sessions end without a single turn, at a median of a
- * few seconds. That is the closest thing the telemetry has to a "voice didn't
- * work for me" rate, and a bare connect/close row cannot separate a denied
- * microphone from a muted one from someone deliberately backing out. Those have
- * completely different fixes, so the reason is what makes the rate actionable.
- *
- * The values are ordered by how far the session got, and each one narrows the
- * cause to a different layer:
- *
- * - `no_ready`  never reached `active`: died in the credential preflight or
- *               the transport, before the user could have said anything.
- * - `text_only` opened without a speech-to-text leg because the client could
- *               type, and then the user never typed. Ranked ahead of the audio
- *               signals because they cannot mean anything here: no microphone
- *               was ever expected, so scoring such a session `no_audio` would
- *               read as a failure the session does not have.
- * - `no_audio`  reached `active` but not one audio chunk ever arrived, so the
- *               microphone never opened. Permission denial looks like this.
- * - `no_speech` audio arrived but the detector never classified any of it as
- *               speech: a muted or dead mic, or a genuinely silent user.
- * - `no_turn`   speech was detected but no turn was ever dispatched, so the
- *               utterance was abandoned, aborted, or failed to arm.
- */
-export type LiveVoiceSilenceReason =
-  | "no_ready"
-  | "text_only"
-  | "no_audio"
-  | "no_speech"
-  | "no_turn";
-
-/**
- * Classify a zero-turn session from what the session observed. Call only when
- * the session really produced no turn: every branch here asserts silence, so a
- * session that did dispatch a turn would be mislabelled by the last one.
- */
-export function liveVoiceSilenceReason(signals: {
-  reachedActive: boolean;
-  audioInput: boolean;
-  receivedAudio: boolean;
-  detectedSpeech: boolean;
-}): LiveVoiceSilenceReason {
-  if (!signals.reachedActive) {
-    return "no_ready";
-  }
-  if (!signals.audioInput) {
-    return "text_only";
-  }
-  if (!signals.receivedAudio) {
-    return "no_audio";
-  }
-  if (!signals.detectedSpeech) {
-    return "no_speech";
-  }
-  return "no_turn";
-}
-
-/**
- * The half of a start stamp that stands in for a dimension the client did not
- * send: an older client, or one that sends no identity at all.
- */
-const LIVE_VOICE_UNATTRIBUTED = "unknown";
-
-/**
- * The `screen` dimension for a started session: the client it started on and
- * the control it started from, as `started_<client>:<entry>`.
- *
- * Both halves come off the start frame verbatim (`client` is a `ClientOs`;
- * `entry` is the client's own token, see `protocol.ts`). Both are always
- * present, with {@link LIVE_VOICE_UNATTRIBUTED} standing in for a missing one,
- * so a query can split the stamp on its colon without a null branch per half.
- *
- * The client rides the started row and not only the turn rows because a
- * quarter of sessions never produce a turn, and those are the ones the client
- * dimension is most needed on: "voice did nothing for me" is a per-client
- * question. Until now those sessions had no client at all (the admin
- * dashboard's `(no turns)` bucket); this stamp gives every session one.
- *
- * The entry is what separates the macOS app's three ways in from each other:
- * the same `client` covers the chat's voice button, the companion's Talk and
- * the voice key, and only the entry says which one the user reached for.
- */
-export function liveVoiceStartScreen(
-  client?: ClientOs | null,
-  entry?: string | null,
-): string {
-  return `started_${client ?? LIVE_VOICE_UNATTRIBUTED}:${entry ?? LIVE_VOICE_UNATTRIBUTED}`;
-}
-
-/**
- * The `screen` dimension for an ended session: how it closed, plus a detail
- * half. That detail is the protocol error code when a failure closed it, or the
- * silence classification when the session produced no turn at all.
- *
- * Every part is the daemon's own vocabulary verbatim
- * (`LiveVoiceSessionCloseReason`, `LiveVoiceProtocolErrorCode`,
- * {@link LiveVoiceSilenceReason}) rather than a mapping, so a rename on any of
- * them surfaces here as a compile error instead of a silently-empty dashboard
- * facet. The longest combination this can produce is well inside the wire
- * field's 64-char bound.
- *
- * A failure code wins over a silence reason when both apply: a session that
- * died on an error is explained by the error, and the silence is a consequence
- * of it rather than a separate finding.
- *
- * The silence value carries a `silent_` prefix on purpose. It shares the detail
- * slot with failure codes, and the admin dashboard currently renders that slot
- * in a column labelled "failure code", so the value has to read correctly even
- * where the column header is wrong, until that panel learns the difference.
- */
-export function liveVoiceEndScreen(
-  reason: LiveVoiceSessionCloseReason,
-  failureCode?: LiveVoiceProtocolErrorCode | null,
-  silenceReason?: LiveVoiceSilenceReason | null,
-): string {
-  if (failureCode) {
-    return `ended_${reason}:${failureCode}`;
-  }
-  if (silenceReason) {
-    return `ended_${reason}:silent_${silenceReason}`;
-  }
-  return `ended_${reason}`;
-}

package/src/telemetry/memory-corpus-size.test.ts

@@ -1,120 +0,0 @@
-import { mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { beforeEach, describe, expect, test } from "bun:test";
-
-let workspaceDir = "";
-
-import {
-  measureMarkdownTree,
-  measureMemoryCorpusSize,
-} from "./memory-corpus-size.js";
-
-// Captured at module scope: the preload cleans up its env var between suites.
-const PRELOAD_WS = process.env.CADET_WORKSPACE_DIR!;
-
-function write(relativePath: string, contents: string): void {
-  const full = join(workspaceDir, relativePath);
-  mkdirSync(join(full, ".."), { recursive: true });
-  writeFileSync(full, contents, "utf8");
-}
-
-describe("measureMemoryCorpusSize", () => {
-  beforeEach(() => {
-    // The preload owns CADET_WORKSPACE_DIR; give this test a clean one.
-    workspaceDir = PRELOAD_WS;
-    rmSync(workspaceDir, { recursive: true, force: true });
-    mkdirSync(workspaceDir, { recursive: true });
-  });
-
-  test("an empty workspace measures as all zeros", () => {
-    expect(measureMemoryCorpusSize()).toEqual({
-      concept_pages: 0,
-      concept_bytes: 0,
-      pkb_files: 0,
-      pkb_bytes: 0,
-      buffer_lines: 0,
-    });
-  });
-
-  test("counts concept pages recursively and totals their bytes", () => {
-    write("memory/concepts/alice.md", "12345"); // 5 bytes
-    write("memory/concepts/people/bob.md", "1234567890"); // 10 bytes
-    write("memory/concepts/people/nested/carol.md", "12345"); // 5 bytes
-
-    const size = measureMemoryCorpusSize();
-
-    expect(size.concept_pages).toBe(3);
-    expect(size.concept_bytes).toBe(20);
-  });
-
-  test("counts the PKB tree independently of concept pages", () => {
-    write("memory/concepts/alice.md", "12345");
-    write("pkb/essentials.md", "1234567890");
-    write("pkb/archive/2026-01-01.md", "12345");
-
-    const size = measureMemoryCorpusSize();
-
-    expect(size.concept_pages).toBe(1);
-    expect(size.pkb_files).toBe(2);
-    expect(size.pkb_bytes).toBe(15);
-  });
-
-  test("ignores non-markdown files", () => {
-    write("memory/concepts/alice.md", "12345");
-    write("memory/concepts/notes.txt", "ignored");
-    write("memory/concepts/.DS_Store", "ignored");
-
-    expect(measureMemoryCorpusSize().concept_pages).toBe(1);
-  });
-
-  test("buffer_lines counts non-empty lines only", () => {
-    write("memory/buffer.md", "- one\n\n- two\n   \n- three\n");
-
-    expect(measureMemoryCorpusSize().buffer_lines).toBe(3);
-  });
-
-  test("an absent buffer reads as zero rather than failing", () => {
-    write("memory/concepts/alice.md", "12345");
-
-    expect(measureMemoryCorpusSize().buffer_lines).toBe(0);
-  });
-
-  test("the traversal ceiling counts every entry, not just markdown", () => {
-    // The regression this guards: a ceiling that only counted `.md` matches
-    // would not bound this walk at all, because nothing in the root is
-    // Markdown.
-    //
-    // The page sits one level down so the assertion does not depend on
-    // readdir order. The root holds 11 entries (10 noise files + the subdir),
-    // so a limit of 5 is exhausted while still scanning the root and the walk
-    // returns before it ever descends — whichever order those 11 come back in.
-    const dir = join(workspaceDir, "noise");
-    mkdirSync(join(dir, "sub"), { recursive: true });
-    for (let i = 0; i < 10; i++) {
-      writeFileSync(join(dir, `placeholder-${i}.txt`), "x", "utf8");
-    }
-    writeFileSync(join(dir, "sub", "page.md"), "12345", "utf8");
-
-    expect(measureMarkdownTree(dir, 5)).toEqual({ files: 0, bytes: 0 });
-    // Unbounded, the same tree yields the one page it contains.
-    expect(measureMarkdownTree(dir)).toEqual({ files: 1, bytes: 5 });
-  });
-
-  test("does not follow symlinked directories", () => {
-    // A link back to an ancestor would otherwise walk forever. Dirents carry
-    // lstat semantics, so the link is skipped rather than recursed into.
-    write("memory/concepts/alice.md", "12345");
-    mkdirSync(join(workspaceDir, "outside"), { recursive: true });
-    writeFileSync(join(workspaceDir, "outside", "extra.md"), "12345", "utf8");
-    symlinkSync(
-      join(workspaceDir, "outside"),
-      join(workspaceDir, "memory", "concepts", "linked"),
-      "dir",
-    );
-
-    const size = measureMemoryCorpusSize();
-
-    expect(size.concept_pages).toBe(1);
-    expect(size.concept_bytes).toBe(5);
-  });
-});