@mycadet/assistant 0.12.9 → 0.12.10

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

@@ -1,184 +0,0 @@
-import { readdirSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
-
-import { getWorkspaceDir } from "../util/platform.js";
-
-/**
- * Coarse on-disk size of the assistant's memory corpus, in the snake_case
- * shape the `memory_tier` watchdog `detail` bag carries to the cloud.
- *
- * Both corpora are measured on every tier rather than branching on the tier
- * itself: an assistant part-way through a v1 -> v2 -> v3 migration has content
- * in both trees, and a `memory.enabled: false` assistant still has whatever it
- * accumulated before being switched off. Reporting both unconditionally keeps
- * the numbers legible across a migration instead of blinking to zero the
- * moment a tier flips.
- *
- * KNOWN GAP: this measures on-disk Markdown only. It does NOT count
- * `memory_graph_nodes`, which is a real part of a v1 assistant's learned state
- * — `v2/migration.ts` gathers graph nodes alongside PKB Markdown when it
- * migrates v1 — so a v1 assistant rich in graph nodes but holding only the
- * seeded PKB files reads as near-empty here. Counting them means opening the
- * memory SQLite DB from the resource-monitor process, which this probe
- * deliberately does not do. Treat `pkb_files` as a lower bound on v1 corpus
- * size and confirm v1 assistants directly before sizing a migration off it.
- */
-export interface MemoryCorpusSize {
-  /** `.md` files under `memory/concepts/` — the v2/v3 concept-page count. */
-  concept_pages: number;
-  /** Total bytes of those concept pages. */
-  concept_bytes: number;
-  /** `.md` files under `pkb/` — the v1 personal-knowledge-base corpus. */
-  pkb_files: number;
-  /** Total bytes of those PKB files. */
-  pkb_bytes: number;
-  /**
-   * Non-empty lines in `memory/buffer.md` — remembered facts still waiting on
-   * consolidation. Matches `countBufferLines` in the substrate's
-   * consolidation job: for a well-formed buffer, one non-empty line is one
-   * entry.
-   */
-  buffer_lines: number;
-}
-
-/**
- * Ceiling on directory entries examined per tree. The largest corpus observed
- * in the fleet is in the low hundreds of pages, so this never binds in
- * practice; it exists so a pathological workspace cannot turn a telemetry
- * probe into a long walk.
- *
- * It counts every dirent seen — directories and non-Markdown files included —
- * not just the Markdown matches. A cap on matches alone would not bound the
- * walk at all: a tree of a million empty directories contains zero Markdown
- * files and would still be traversed in full by this synchronous probe.
- *
- * A tree that hits the cap returns what it counted so far, making the result
- * a floor rather than an error.
- */
-const MAX_ENTRIES_PER_TREE = 20_000;
-
-interface TreeSize {
-  files: number;
-  bytes: number;
-}
-
-const EMPTY_TREE: TreeSize = { files: 0, bytes: 0 };
-
-/**
- * Recursively total the `.md` files under `dir`.
- *
- * Deliberately synchronous, and deliberately not routed through the memory
- * plugin's `listPages` / `getPageIndex`. This runs in the resource-monitor
- * process, where the plugin's page-index cache is cold — going through it
- * would read and parse every concept page on each six-hour cycle, and would
- * add an import out of `telemetry/` into the plugin tree that the plugin
- * import-boundary guard exists to prevent. A bare readdir + stat is the whole
- * job here.
- *
- * `withFileTypes` dirents carry lstat semantics, so a symlinked directory
- * reports as a symlink rather than a directory and is skipped — the walk
- * cannot follow a link into a cycle, and needs no visited-inode bookkeeping.
- *
- * `maxEntries` is a parameter only so the ceiling is testable without
- * materializing twenty thousand files; production callers take the default.
- */
-export function measureMarkdownTree(
-  dir: string,
-  maxEntries: number = MAX_ENTRIES_PER_TREE,
-): TreeSize {
-  let files = 0;
-  let bytes = 0;
-  let visited = 0;
-  const pending: string[] = [dir];
-
-  while (pending.length > 0) {
-    const current = pending.pop();
-    if (current === undefined) {
-      break;
-    }
-
-    let entries;
-    try {
-      entries = readdirSync(current, { withFileTypes: true });
-    } catch {
-      // A missing or unreadable subtree contributes nothing. The common case
-      // is ENOENT: the tier that owns this tree was never active here.
-      continue;
-    }
-
-    for (const entry of entries) {
-      visited += 1;
-      if (visited > maxEntries) {
-        return { files, bytes };
-      }
-      if (entry.isDirectory()) {
-        pending.push(join(current, entry.name));
-        continue;
-      }
-      if (!entry.isFile() || !entry.name.endsWith(".md")) {
-        continue;
-      }
-      files += 1;
-      try {
-        bytes += statSync(join(current, entry.name)).size;
-      } catch {
-        // Counted in `files` but contributes no bytes — a file that vanished
-        // between the readdir and the stat is a race, not a failure.
-      }
-    }
-  }
-
-  return { files, bytes };
-}
-
-/** Non-empty-line count of the file at `path`; 0 when it is absent or empty. */
-function countNonEmptyLines(path: string): number {
-  let content: string;
-  try {
-    content = readFileSync(path, "utf8");
-  } catch {
-    return 0;
-  }
-  if (content.length === 0) {
-    return 0;
-  }
-  return content.split("\n").filter((line) => line.trim().length > 0).length;
-}
-
-/**
- * Measure the on-disk memory corpus for this assistant.
- *
- * Never throws: every probe degrades to zero independently, so a corpus that
- * is partly unreadable still reports the part that is.
- */
-export function measureMemoryCorpusSize(): MemoryCorpusSize {
-  const workspaceDir = getWorkspaceDir();
-
-  let concepts: TreeSize = EMPTY_TREE;
-  let pkb: TreeSize = EMPTY_TREE;
-  let bufferLines = 0;
-
-  try {
-    concepts = measureMarkdownTree(join(workspaceDir, "memory", "concepts"));
-  } catch {
-    concepts = EMPTY_TREE;
-  }
-  try {
-    pkb = measureMarkdownTree(join(workspaceDir, "pkb"));
-  } catch {
-    pkb = EMPTY_TREE;
-  }
-  try {
-    bufferLines = countNonEmptyLines(join(workspaceDir, "memory", "buffer.md"));
-  } catch {
-    bufferLines = 0;
-  }
-
-  return {
-    concept_pages: concepts.files,
-    concept_bytes: concepts.bytes,
-    pkb_files: pkb.files,
-    pkb_bytes: pkb.bytes,
-    buffer_lines: bufferLines,
-  };
-}

package/src/telemetry/memory-tier-reporter.test.ts

@@ -1,195 +0,0 @@
-import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
-
-import type { ConsentState } from "../cloud/consent-cache.js";
-import { memoryTier } from "../config/memory-tier.js";
-import type { AssistantConfig } from "../config/schema.js";
-import type { MemoryCorpusSize } from "./memory-corpus-size.js";
-import type { WatchdogEventRecord } from "./watchdog-events-store.js";
-
-// Mutable stubs flipped per test. bun's `mock.module` patches retroactively
-// (live bindings), so the reporter's imports resolve to these regardless of
-// import order (mirrors `outbox-test-harness.ts`). Kept off the outbox/DB path
-// on purpose: mocking `recordWatchdogEvent` lets these assert emission without
-// standing up the telemetry DB.
-let consent: ConsentState = true;
-let currentConfig: AssistantConfig = {} as AssistantConfig;
-let recorded: WatchdogEventRecord[] = [];
-
-// Stubbed so the assertions below stay exact-match: the real probe walks the
-// live workspace, whose contents differ per machine. `measureMemoryCorpusSize`
-// has its own tests against a temp tree.
-const ZERO_CORPUS: MemoryCorpusSize = {
-  concept_pages: 0,
-  concept_bytes: 0,
-  pkb_files: 0,
-  pkb_bytes: 0,
-  buffer_lines: 0,
-};
-let corpus: MemoryCorpusSize = ZERO_CORPUS;
-let corpusError: Error | null = null;
-
-mock.module("./memory-corpus-size.js", () => ({
-  measureMemoryCorpusSize: () => {
-    if (corpusError) {
-      throw corpusError;
-    }
-    return corpus;
-  },
-}));
-mock.module("../cloud/consent-cache.js", () => ({
-  getRawShareAnalytics: () => consent,
-}));
-mock.module("../config/loader.js", () => ({
-  getConfigReadOnly: () => currentConfig,
-}));
-mock.module("./watchdog-events-store.js", () => ({
-  recordWatchdogEvent: (record: WatchdogEventRecord) => {
-    recorded.push(record);
-  },
-}));
-
-import {
-  recordMemoryTierOnce,
-  startMemoryTierReporter,
-  stopMemoryTierReporter,
-} from "./memory-tier-reporter.js";
-
-function makeConfig(
-  enabled: boolean,
-  v2Enabled: boolean,
-  v3Live = false,
-): AssistantConfig {
-  return {
-    memory: {
-      enabled,
-      v2: { enabled: v2Enabled },
-      v3: { live: v3Live },
-    },
-  } as AssistantConfig;
-}
-
-describe("memory-tier-reporter", () => {
-  beforeEach(() => {
-    consent = true;
-    currentConfig = {} as AssistantConfig;
-    recorded = [];
-    corpus = ZERO_CORPUS;
-    corpusError = null;
-    // Clear any interval/boot-retry timer a prior test's start left behind.
-    stopMemoryTierReporter();
-  });
-
-  afterEach(() => {
-    stopMemoryTierReporter();
-    delete process.env.CADET_DEV;
-  });
-
-  test("emits a memory_tier watchdog carrying the current tier", () => {
-    const config = makeConfig(true, true); // memory on, v2 enabled → "v2"
-    currentConfig = config;
-
-    recordMemoryTierOnce();
-
-    expect(recorded).toHaveLength(1);
-    expect(recorded[0]).toEqual({
-      checkName: "memory_tier",
-      detail: { tier: memoryTier(config), ...ZERO_CORPUS },
-    });
-    expect(recorded[0]?.detail?.tier).toBe("v2");
-  });
-
-  test("reflects a different tier for a different config (v3 live)", () => {
-    currentConfig = makeConfig(true, true, true); // v3 live wins over v2
-    recordMemoryTierOnce();
-
-    expect(recorded[0]?.detail).toEqual({ tier: "v3", ...ZERO_CORPUS });
-  });
-
-  test("carries the measured corpus size alongside the tier", () => {
-    currentConfig = makeConfig(true, true, true);
-    corpus = {
-      concept_pages: 42,
-      concept_bytes: 133_700,
-      pkb_files: 3,
-      pkb_bytes: 900,
-      buffer_lines: 7,
-    };
-
-    recordMemoryTierOnce();
-
-    expect(recorded[0]?.detail).toEqual({ tier: "v3", ...corpus });
-  });
-
-  test("a failed corpus probe still emits the tier heartbeat", () => {
-    // The fleet-mix dashboards read `detail.tier`; a sizing failure must
-    // degrade the payload, never drop the event and gap the series.
-    currentConfig = makeConfig(true, true, true);
-    corpusError = new Error("workspace unreadable");
-
-    recordMemoryTierOnce();
-
-    expect(recorded).toHaveLength(1);
-    expect(recorded[0]?.detail).toEqual({ tier: "v3" });
-  });
-
-  test("emits every invocation — no memo", () => {
-    currentConfig = makeConfig(true, false); // "v1"
-    recordMemoryTierOnce();
-    recordMemoryTierOnce();
-    recordMemoryTierOnce();
-
-    expect(recorded).toHaveLength(3);
-    for (const event of recorded) {
-      expect(event).toEqual({
-        checkName: "memory_tier",
-        detail: { tier: "v1", ...ZERO_CORPUS },
-      });
-    }
-  });
-
-  test("unknown consent emits nothing", () => {
-    consent = "unknown";
-    currentConfig = makeConfig(true, true);
-
-    recordMemoryTierOnce();
-
-    expect(recorded).toHaveLength(0);
-  });
-
-  test("a confirmed opt-out still calls through (recordWatchdogEvent no-ops)", () => {
-    // The reporter only skips the UNKNOWN state; the `false` opt-out is
-    // honored one layer down in `recordWatchdogEvent`. Here that layer is the
-    // stub, so the call is observed — the drop is the real store's concern.
-    consent = false;
-    currentConfig = makeConfig(true, true);
-
-    recordMemoryTierOnce();
-
-    expect(recorded).toHaveLength(1);
-  });
-
-  test("a confirmed opt-out skips the corpus probe entirely", () => {
-    // The event is dropped one layer down, so walking the workspace for it
-    // would be pure cost on an assistant that asked us not to collect. The
-    // throwing stub asserts the probe is never reached.
-    consent = false;
-    currentConfig = makeConfig(true, true);
-    corpusError = new Error("probe must not run");
-
-    recordMemoryTierOnce();
-
-    expect(recorded).toHaveLength(1);
-    expect(recorded[0]?.detail).toEqual({ tier: "v2" });
-  });
-
-  test("startMemoryTierReporter is a no-op under CADET_DEV=1", () => {
-    process.env.CADET_DEV = "1";
-    consent = true; // consent known → a non-dev start would emit immediately
-    currentConfig = makeConfig(true, true);
-
-    startMemoryTierReporter();
-
-    // No boot emit and no interval scheduled.
-    expect(recorded).toHaveLength(0);
-  });
-});

package/src/telemetry/memory-tier-reporter.ts

@@ -1,130 +0,0 @@
-import { getRawShareAnalytics } from "../cloud/consent-cache.js";
-import { getConfigReadOnly } from "../config/loader.js";
-import { memoryTier } from "../config/memory-tier.js";
-import { getLogger } from "../util/logger.js";
-import { measureMemoryCorpusSize } from "./memory-corpus-size.js";
-import { recordWatchdogEvent } from "./watchdog-events-store.js";
-
-const log = getLogger("memory-tier-reporter");
-
-/**
- * How often each assistant re-asserts its coarse memory tier as a
- * `memory_tier` watchdog event. Unlike the config-setting snapshot this emits
- * UNCONDITIONALLY every cycle (no memo): the cloud-side query wants a
- * periodic per-assistant heartbeat of the current tier, so a gap in the series
- * is meaningful (assistant offline) rather than "value unchanged". Six-hourly
- * keeps the volume trivial while giving a same-day read on the fleet's tier
- * mix, and every boot re-asserts the tier regardless.
- */
-const MEMORY_TIER_INTERVAL_MS = 6 * 60 * 60 * 1000;
-
-/**
- * Watchdog `check_name` carrying the coarse memory tier in `detail.tier`,
- * alongside the on-disk corpus size (see {@link measureMemoryCorpusSize}).
- *
- * The check name and the `detail.tier` bucket strings are frozen — platform
- * dashboards group on them. The rest of `detail` is an open bag, so the
- * corpus-size keys are additive and need no wire, serializer, or dbt change.
- */
-const MEMORY_TIER_CHECK_NAME = "memory_tier";
-
-// The boot-time emit 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 emit is skipped. Retry on a short timer until consent resolves
-// rather than waiting a full six-hour interval for the per-boot assertion.
-const BOOT_RETRY_INTERVAL_MS = 60_000;
-
-/**
- * Emit one `memory_tier` watchdog event for this assistant's current tier.
- *
- * Consent-gated like the config-setting snapshot but with NO memo: every
- * invocation emits, so the cloud sees a periodic heartbeat of the current
- * tier rather than only edges. An UNKNOWN consent state skips entirely
- * (consent resolves asynchronously after boot; the boot-retry loop re-invokes
- * once it lands) — deferring loses nothing since the tier is re-derivable
- * state. A confirmed opt-out is honored inside `recordWatchdogEvent`, which
- * no-ops on a `false` share_analytics, so the call still goes through and the
- * record layer drops it. Never throws: a storage failure is logged and
- * retried on the next cycle.
- *
- * The event also carries the on-disk corpus size. That probe is best-effort
- * and isolated: if it fails the event still goes out with the tier alone,
- * because the tier heartbeat is what the fleet-mix dashboards depend on and a
- * sizing failure must not create a gap in that series. It is also skipped
- * outright on a confirmed opt-out — the event is dropped one layer down, so
- * walking the workspace for it would be pure cost on the assistants that
- * asked us not to collect.
- */
-export function recordMemoryTierOnce(): void {
-  const consent = getRawShareAnalytics();
-  if (consent === "unknown") {
-    return;
-  }
-  try {
-    // `getConfigReadOnly()` re-reads config.json on change (capturing live
-    // edits) and never writes to disk — safe for the monitor process.
-    const tier = memoryTier(getConfigReadOnly());
-
-    let corpus: Record<string, number> = {};
-    if (consent !== false) {
-      try {
-        corpus = { ...measureMemoryCorpusSize() };
-      } catch (err) {
-        log.warn({ err }, "memory corpus sizing failed (emitting tier only)");
-      }
-    }
-
-    recordWatchdogEvent({
-      checkName: MEMORY_TIER_CHECK_NAME,
-      detail: { tier, ...corpus },
-    });
-  } catch (err) {
-    log.warn({ err }, "memory_tier watchdog emit failed (non-fatal)");
-  }
-}
-
-let tierTimer: ReturnType<typeof setInterval> | null = null;
-let bootRetryTimer: ReturnType<typeof setTimeout> | null = null;
-
-function recordBootTierOnceConsentKnown(): void {
-  if (getRawShareAnalytics() === "unknown") {
-    bootRetryTimer = setTimeout(
-      recordBootTierOnceConsentKnown,
-      BOOT_RETRY_INTERVAL_MS,
-    );
-    bootRetryTimer.unref?.();
-    return;
-  }
-  bootRetryTimer = null;
-  recordMemoryTierOnce();
-}
-
-/**
- * Start the memory-tier reporter in the resource monitor process: emit the
- * current tier once at boot (once consent resolves), then every six hours,
- * UNCONDITIONALLY. No-op in dev mode (CADET_DEV=1) and idempotent if already
- * started. Runs alongside {@link import("./config-setting-snapshot.js").startConfigSnapshotReporter}
- * in the monitor worker.
- */
-export function startMemoryTierReporter(): void {
-  if (process.env.CADET_DEV === "1") {
-    return;
-  }
-  if (tierTimer) {
-    return;
-  }
-  recordBootTierOnceConsentKnown();
-  tierTimer = setInterval(recordMemoryTierOnce, MEMORY_TIER_INTERVAL_MS);
-}
-
-/** Stop the memory-tier reporter loop. Idempotent. */
-export function stopMemoryTierReporter(): void {
-  if (tierTimer) {
-    clearInterval(tierTimer);
-    tierTimer = null;
-  }
-  if (bootRetryTimer) {
-    clearTimeout(bootRetryTimer);
-    bootRetryTimer = null;
-  }
-}

package/src/telemetry/phone-call-funnel.ts

@@ -1,144 +0,0 @@
-/**
- * Phone-call telemetry vocabulary: the single source of truth for the step
- * names, funnel version, and dimension values the call store's emitter uses.
- *
- * The phone half of the live-voice funnel, and deliberately its mirror image:
- * same onboarding substrate (`type: "onboarding"`), same open-string
- * `step_name` / `funnel_version`, same reason for both. See
- * `live-voice-funnel.ts` for the full argument; the short version is that the
- * backend stores those two as open strings, so a new funnel needs no platform
- * serializer and no wire-contract change.
- *
- * **Duration is not a field**, for the same reason it is not one on live
- * voice: the onboarding event shape has no numeric slot. The two events below
- * are keyed by the call session id in `session_id` and the warehouse subtracts
- * their `recorded_at` stamps.
- *
- * **Turn count is not a field either.** Phone turns already carry the call
- * session id in their `client` bag (`voiceTelemetry` at the bridge call site),
- * so a turn count is a count of those rows.
- *
- * A call that starts and never ends is **censored, not infinite**: a daemon
- * crash between the two writes emits no end event, so duration math must drop
- * unmatched `started` rows rather than treat the call as still running.
- */
-
-import type { CallMode, CallStatus } from "../calls/types.js";
-
-/** Funnel version stamped on every phone-call event. */
-export const PHONE_CALL_FUNNEL_VERSION = "phone_call_v1_2026_09";
-
-/**
- * Phone-call funnel steps. `stepName` is the wire value; `stepIndex` is the
- * ordinal position.
- *
- * `callStarted` fires when the call session row is created, before the
- * provider has dialled: a call that never connects is exactly the one worth
- * counting, so the start event precedes no-answer, busy, provider failure and
- * the inbound credential preflight (an inbound session exists before that
- * preflight runs and records against it).
- *
- * It does **not** cover an outbound attempt rejected before a session exists:
- * `startCall`, `startVerificationCall` and `startInviteCall` all return on a
- * failed `preflightVoiceIngress()` without creating a row, and this funnel is
- * keyed by the session id it would have had. Counting those needs a key that
- * does not depend on a session row, which is its own piece of work.
- */
-export const PHONE_CALL_STEPS = {
-  callStarted: { stepName: "phone_call_started", stepIndex: 0 },
-  callEnded: { stepName: "phone_call_ended", stepIndex: 1 },
-} as const;
-
-export type PhoneCallStepName =
-  (typeof PHONE_CALL_STEPS)[keyof typeof PHONE_CALL_STEPS]["stepName"];
-
-/**
- * Which way the call was placed. Inbound is someone dialling the assistant's
- * number; outbound is the assistant dialling out on a task.
- */
-export type PhoneCallDirection = "inbound" | "outbound";
-
-/**
- * How a call ended, stamped as `outcome`.
- *
- * `failed` means the call died on an error: no answer, a provider or
- * credential failure, a dropped media stream. A call the caller or the
- * assistant hung up, including one cancelled before it connected, is
- * `completed`: it ran its course and the close reason on `screen` says how.
- */
-export type PhoneCallOutcome = "completed" | "failed";
-
-/**
- * How far a call that produced NO caller turn actually got.
- *
- * The phone analogue of the live-voice silence taxonomy, and the closest thing
- * call telemetry has to a "the phone path didn't work" rate. A bare
- * started/ended pair cannot separate a call that never connected from one that
- * connected to silence, and those have completely different fixes.
- *
- * - `no_connect` the call never reached `in_progress`: it failed, was
- *                cancelled, or was never answered, so nobody could have
- *                spoken.
- * - `no_turn`    the call connected and then no caller utterance was ever
- *                transcribed: a silent line, a failed STT leg, or a caller who
- *                hung up on the disclosure.
- */
-export type PhoneCallSilenceReason = "no_connect" | "no_turn";
-
-/**
- * Classify a call that produced no caller turn. Call only when the call really
- * produced none: the second branch asserts silence, so a call that did take a
- * turn would be mislabelled by it.
- */
-export function phoneCallSilenceReason(signals: {
-  connected: boolean;
-}): PhoneCallSilenceReason {
-  return signals.connected ? "no_turn" : "no_connect";
-}
-
-/**
- * The mode an ordinary call carries. Only the verification and invite flows
- * write a mode on the session row, so a null there is not a missing dimension
- * but the ordinary conversation every other path creates.
- */
-const PHONE_CALL_DEFAULT_MODE: CallMode = "normal";
-
-/**
- * The `screen` dimension for a started call: which way it was placed and what
- * kind of call it is, as `started_<direction>:<mode>`.
- *
- * The mode separates the three things a phone call can be (a normal
- * conversation, a callee verification, an invite redemption) because they have
- * completely different shapes and success criteria, and a funnel that mixed
- * them would report the verification flow's brevity as a conversation problem.
- */
-export function phoneCallStartScreen(
-  direction: PhoneCallDirection,
-  mode?: CallMode | null,
-): string {
-  return `started_${direction}:${mode ?? PHONE_CALL_DEFAULT_MODE}`;
-}
-
-/**
- * The `screen` dimension for an ended call: the terminal status it reached,
- * plus a detail half carrying the silence classification when the call took no
- * caller turn at all.
- *
- * The status is the daemon's own `CallStatus` verbatim rather than a mapping,
- * so a rename surfaces here as a compile error instead of a silently-empty
- * dashboard facet.
- *
- * The silence value carries a `silent_` prefix to match the live-voice stamp,
- * which shares its detail slot with failure codes and renders in an admin
- * column labelled "failure code". Reading the two funnels side by side is
- * worth more than a shorter string here.
- */
-export function phoneCallEndScreen(
-  status: CallStatus,
-  silenceReason?: PhoneCallSilenceReason | null,
-): string {
-  if (silenceReason) {
-    return `ended_${status}:silent_${silenceReason}`;
-  }
-  return `ended_${status}`;
-}