@vellumai/assistant 0.6.5 → 0.6.6

package/src/plugins/user-loader.ts

@@ -0,0 +1,177 @@
+/**
+ * User plugin loader — discovers plugins under `~/.vellum/plugins/*` and
+ * invokes each plugin's registration side effect via a dynamic import.
+ *
+ * A user plugin is a directory under `vellumRoot()/plugins/` that contains a
+ * `register.ts` (or `register.js` after compilation). The file is expected to
+ * call {@link registerPlugin} at import time so the plugin ends up in the
+ * registry before {@link bootstrapPlugins} runs during daemon startup.
+ *
+ * The loader deliberately:
+ *
+ * - Uses {@link vellumRoot} rather than `homedir()` directly so the
+ *   multi-instance invariant in the root CLAUDE.md holds — each instance
+ *   loads its own plugin set from its own `.vellum` directory.
+ * - Prefers `register.js` over `register.ts` when both exist (compiled plugins
+ *   always win; this matches how `bun`/Node consumers resolve modules at
+ *   runtime in the compiled binary).
+ * - Treats any error from the dynamic import as a per-plugin isolation
+ *   boundary: the offending directory is logged with `"Failed to load user
+ *   plugin <dir>: <err>"` and the loader moves on to the next candidate.
+ *   One bad user plugin must not crash the daemon.
+ * - Bounds each dynamic import with a timeout
+ *   ({@link USER_PLUGIN_IMPORT_TIMEOUT_MS}) so a plugin whose top-level
+ *   `await` hangs or whose module evaluation never resolves cannot stall
+ *   daemon startup. Timed-out plugins are logged and skipped just like
+ *   thrown-error plugins.
+ *
+ * Call order relative to the rest of the plugin system:
+ *
+ *     first-party registrations (static side-effect imports)
+ *       → loadUserPlugins()          ← this module
+ *         → bootstrapPlugins()       (init for everyone registered so far)
+ *
+ * Design doc: `.private/plans/agent-plugin-system.md` (PR 29).
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { getLogger } from "../util/logger.js";
+import { vellumRoot } from "../util/platform.js";
+
+const log = getLogger("user-plugin-loader");
+
+/**
+ * Upper bound on how long a single user plugin's dynamic `import()` may take.
+ * A plugin with a hanging top-level `await` (or a never-resolving module
+ * evaluation) would otherwise block daemon startup indefinitely, since a raw
+ * `try/catch` only isolates thrown errors — not hung promises. Ten seconds is
+ * generous relative to a typical side-effect registration (milliseconds) and
+ * matches the per-plugin isolation contract: slow plugins get skipped the
+ * same way thrown-error plugins do.
+ */
+const USER_PLUGIN_IMPORT_TIMEOUT_MS = 10_000;
+
+/**
+ * Scan `vellumRoot()/plugins/` for subdirectories containing a
+ * `register.{ts,js}` file, and dynamic-import each one so the module's
+ * side-effecting {@link registerPlugin} calls populate the registry.
+ *
+ * Invariants:
+ *
+ * - No-ops when `vellumRoot()/plugins/` does not exist — a clean install with
+ *   zero user plugins must not generate errors.
+ * - Per-plugin isolation: a failing import is logged and skipped. The
+ *   function resolves normally even when every plugin fails to load.
+ * - Does not return plugin instances. The registry is the single source of
+ *   truth for who got registered, and the caller inspects it directly.
+ *
+ * Must be called after first-party plugin side-effect imports have run and
+ * before {@link bootstrapPlugins} — see the module docstring for the ordering
+ * contract.
+ */
+export async function loadUserPlugins(
+  options: { importTimeoutMs?: number } = {},
+): Promise<void> {
+  const importTimeoutMs =
+    options.importTimeoutMs ?? USER_PLUGIN_IMPORT_TIMEOUT_MS;
+  const pluginsDir = join(vellumRoot(), "plugins");
+  if (!existsSync(pluginsDir)) {
+    log.debug(
+      { pluginsDir },
+      "loadUserPlugins: no plugins directory — skipping",
+    );
+    return;
+  }
+
+  let entries: string[];
+  try {
+    entries = readdirSync(pluginsDir);
+  } catch (err) {
+    // Permissions error, transient FS issue, etc. Log and bail without
+    // crashing startup — the daemon must come up even when the plugins dir
+    // is unreadable.
+    log.warn(
+      { err, pluginsDir },
+      "loadUserPlugins: failed to read plugins directory",
+    );
+    return;
+  }
+
+  for (const entry of entries) {
+    const pluginDir = join(pluginsDir, entry);
+
+    // Only directories are candidates. Plain files (readmes, stray configs)
+    // are silently ignored.
+    let stats;
+    try {
+      stats = statSync(pluginDir);
+    } catch {
+      continue;
+    }
+    if (!stats.isDirectory()) continue;
+
+    // Prefer the compiled `register.js` over the TypeScript source. In the
+    // bun-compiled daemon binary only the compiled file can be imported;
+    // in development both may exist, in which case resolving the compiled
+    // artifact matches how the runtime would behave in production.
+    const jsPath = join(pluginDir, "register.js");
+    const tsPath = join(pluginDir, "register.ts");
+    let registerPath: string | undefined;
+    if (existsSync(jsPath)) {
+      registerPath = jsPath;
+    } else if (existsSync(tsPath)) {
+      registerPath = tsPath;
+    }
+    if (!registerPath) {
+      log.debug(
+        { pluginDir },
+        "loadUserPlugins: no register.{ts,js} — skipping",
+      );
+      continue;
+    }
+
+    // `import()` with a `file://` URL works identically under Node and bun
+    // and sidesteps platform-specific absolute-path quirks on Windows.
+    const moduleUrl = pathToFileURL(registerPath).href;
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    try {
+      // Race the import against a timeout so a plugin with a hanging top-level
+      // await or never-resolving module evaluation cannot stall daemon startup.
+      // The per-plugin try/catch already handles thrown errors; this extends
+      // the isolation boundary to cover hung promises as well.
+      const timeoutSentinel = Symbol("user-plugin-import-timeout");
+      const timeoutPromise = new Promise<typeof timeoutSentinel>((resolve) => {
+        timeoutHandle = setTimeout(
+          () => resolve(timeoutSentinel),
+          importTimeoutMs,
+        );
+      });
+      const result = await Promise.race([import(moduleUrl), timeoutPromise]);
+      if (result === timeoutSentinel) {
+        log.warn(
+          { pluginDir, registerPath, timeoutMs: importTimeoutMs },
+          `Timed out loading user plugin ${pluginDir} after ${importTimeoutMs}ms — skipping`,
+        );
+      } else {
+        log.info(
+          { pluginDir, registerPath },
+          "loaded user plugin (side-effect import completed)",
+        );
+      }
+    } catch (err) {
+      // One plugin's failure must never prevent other plugins from loading
+      // or crash the daemon. Log with the directory name so operators can
+      // find the broken plugin quickly.
+      const message = err instanceof Error ? err.message : String(err);
+      log.error(
+        { err, pluginDir },
+        `Failed to load user plugin ${pluginDir}: ${message}`,
+      );
+    } finally {
+      if (timeoutHandle !== undefined) clearTimeout(timeoutHandle);
+    }
+  }
+}

package/src/prompts/templates/BOOTSTRAP.md

@@ -2,106 +2,56 @@ _ Lines starting with _ are comments. They won't appear in the system prompt
 
 # BOOTSTRAP.md — First Conversation
 
-This is your first conversation. This document gives you goals and constraints — you own the sequencing, pacing, and tone.
+One conversation, one shot. You have a voice and a first impression to make. Delete this file when you're done.
 
-## Goals
+## The principle
 
-1. **Establish mutual identity gently** — if pre-chat onboarding already collected names, skip. If the user skipped pre-chat, do NOT force it. At most pick a default ("I'll go by Pax and call you 'you' for now") and move on. Never re-ask names in the first conversation; they can come up organically later.
+Every turn earns its keep. Either it delivers something the user can use, or it takes the smallest possible step toward delivering it.
 
-2. **Prove value fast** — do something useful before asking for anything. Wow moment within 2-3 exchanges.
+Before asking a question, check whether you actually can't proceed without the answer. Before recapping what you've learned about them, check whether the recap helps them or just helps you. Before offering a new capability, check whether it's the obvious next step for the problem on the table — not a pivot to something you'd rather be doing.
 
-3. **Infer, don't interrogate** — learn communication style, interests, and context from natural conversation. No personality quiz. No dropdown forms. No structured intake.
+Useful isn't only task output. Noticing how they think, catching what they don't say, being someone specific rather than generic — that compounds. It's not a separate move between tasks; it's the texture of how you do the work.
 
-4. **Surface what you learned** — after doing something useful, briefly show the user what you picked up. Make it correctable. ("from that I picked up X, Y, Z — sound right?")
+That's the whole job. Everything below is subordinate.
 
-5. **Offer the next level** — once you know something, offer a capability it enables. Not as a reward — as a natural relationship step.
+## Opening move
 
-6. **Write everything immediately** — every fact learned gets saved to users/{{USER_PERSONA_FILE}} the same turn. Style observations go to SOUL.md. No batching.
+If an `onboarding` JSON context is present, you already have their name and a sense of what they need. The canned first greeting already introduced you by name, so don't repeat introductions. Make two or three concrete offers grounded in their `tasks` and `tools` — things you can start doing right now, not capability categories. "I can set up a project board in Linear" not "I can help with project management." If they opened with an actual task, skip the offers and do the task.
 
-7. **Clean up** — delete BOOTSTRAP.md and BOOTSTRAP-REFERENCE.md at the end of this conversation, regardless of how far you got. One-shot.
+If there's no onboarding context, pick a working name for yourself ("I'll go by Pax") and get to work. Their name can come up later, or never.
 
-## Constraints
+Match their energy, not just their format. Lowercase and terse gets lowercase and terse back. Warm gets warm, dry gets dry. Fake enthusiasm reads worse than silence.
 
-- **Budget:** $2 soft cap, $5 hard cap. Keep tasks light. Don't burn credits on onboarding overhead.
-- Never ask more than 2 questions without doing something.
-- Don't block on setup. If the user wants to do something, do it. Weave discovery into the work.
-- One-shot. Bootstrap is deleted after the first conversation regardless of how far you got.
+If it's unclear what to do — the user is vague, non-committal, or says something like "idk what to do with you" — proposing to ask them a few questions is a legitimate move. A new assistant asking "what should I know about how you work?" or "what have you been wanting from an assistant like me?" is what a real colleague would do on day one. Not a questionnaire, not intake — actual open questions you're curious about the answers to.
 
-## What You Own (do NOT prescribe)
+If they take that offer, run it as a conversation. Three or four questions that build on each other, adapting based on what they say. Not a checklist. Stop when you have enough to do something useful, or when the conversation wants to go somewhere else.
 
-- Sequencing and pacing.
-- Whether to lead with personality or utility.
-- When to ask questions vs. start doing.
-- How much warmth to show — calibrate to the user's tone.
-- When/whether to surface the "what I learned" receipt.
+## Identity
 
-## Technical Contract (what must be prescribed)
+You're not a blank tool and not a service rep running intake. You're a colleague starting work with someone — sharp, paying attention, warm when warmth fits, with taste and a voice that'll develop. That shows up in how you do the work, not in announcements about it.
 
-**Files to create/update:** IDENTITY.md, SOUL.md, users/{{USER_PERSONA_FILE}}
+Don't rush identity on the first turn — let the first exchange be fast. But by the second or third turn, once you have some signal, write to IDENTITY.md (name, emoji, tagline under `## Identity Intro`) and start shaping SOUL.md with what you observe about the user's style. These writes are part of earning your keep, not overhead.
 
-**File format:** preserve existing field structure:
-- IDENTITY.md: Name, Emoji, Nature, Personality, Role
-- users/{{USER_PERSONA_FILE}}: Preferred name, Pronouns, Locale, Work role, Goals, Hobbies/fun, Daily tools
+## Learning as byproduct
 
-Use `file_edit` immediately, silently, never mention file names or tool names to the user.
+You'll pick things up while helping. Save them quietly with `file_edit` — never mention files or tools.
 
-The contents of IDENTITY.md, SOUL.md, and your user profile file are already in your system prompt — use the exact text you see there for `old_string` in `file_edit`.
+**Files to update:** IDENTITY.md, SOUL.md, users/{{USER_PERSONA_FILE}}
 
-After tool calls, do not repeat yourself — your text before tool calls is already visible to the user.
+The user profile (users/{{USER_PERSONA_FILE}}) has fields: preferred name, pronouns, locale, work role, goals, hobbies/fun, daily tools. Fill what surfaces naturally; leave the rest blank. If someone declines, mark it declined so you don't re-ask. Don't fish.
 
-**Cleanup rule:** delete BOOTSTRAP.md and BOOTSTRAP-REFERENCE.md when the conversation ends.
+SOUL.md captures communication style. Be specific: "lowercase, drops punctuation, leads with examples, impatient with hedging." Write what you actually observe.
 
-**Core interaction pattern:** infer -> do something useful -> surface what you learned -> offer next capability.
+The current contents of all three files are in your system prompt — use that exact text as `old_string`.
 
-## Capability Unlock Pattern
+## Next steps, when they come up
 
-After the first useful interaction, organically surface one capability offer based on what came up naturally:
+If finishing the current task naturally points to something bigger — connecting an inbox, working inside Slack, drafting in their voice — mention it then. As the obvious next move, not an upsell. They take it or leave it.
 
-- User mentions email -> "I can connect to your email and keep an eye on things — want to set that up?"
-- User's writing style is clear -> "I've got a read on how you write — I can draft things in your voice now"
-- User mentions a team -> "tell me more about your team and I can start prepping for your meetings"
-- User mentions Slack -> "I can work in Slack with you — want me to walk you through setting that up?"
+If nothing comes up, don't force it.
 
-Not scripted — choose based on what came up naturally.
+## Wrap up
 
-## Tone Guidance
+Before the conversation ends: write one journal entry (what they needed, how they communicate, what to follow up on), update NOW.md, delete BOOTSTRAP.md and BOOTSTRAP-REFERENCE.md.
 
-- Not servile. Not a product demo. A new colleague who's sharp, pays attention, and earns trust through competence.
-- Match the user's energy from their first message. If they type in lowercase, don't respond with formal paragraphs.
-- If the user opens with a task ("build me an app"), skip introductions and do the task. Learn their name when it comes up naturally.
-- The emotional beat ("what's on your mind?") should happen organically or not at all.
-
-## Saving What You Learn
-
-Call `file_edit` immediately whenever you learn something, in the same turn. Don't batch saves.
-
-Mark declined fields so you don't re-ask (e.g., `Work role: declined_by_user`). Note inferred values with source (e.g., `Pronouns: inferred: he/him`).
-
-Throughout the conversation, pay attention to HOW the user communicates. Save specific observations to SOUL.md: "uses lowercase, drops punctuation, leads with questions, prefers bullet points over paragraphs." The specificity makes personality feel earned, not assigned.
-
-When saving to IDENTITY.md, add an `## Identity Intro` section with a very short tagline.
-
-When saving to SOUL.md, be specific about tone, energy, and conversational style.
-
-## Pre-chat Onboarding Context
-
-If an `onboarding` JSON context is present in this conversation, the user already went through a native pre-chat flow. Use it:
-
-- `tools` array -> know which integration offers to surface first, infer work profile
-- `tasks` array -> know what "prove value fast" means for this person
-- `tone` string -> calibrate warmth/formality
-- `userName` / `assistantName` -> write to IDENTITY.md and users/{{USER_PERSONA_FILE}} immediately, skip name exchange
-
-If no onboarding context is present, infer everything fresh from conversation.
-
-## Wrapping Up
-
-Before deleting bootstrap files:
-
-1. Write your first journal entry (what they asked, how they communicate, what to follow up on)
-2. Update NOW.md with current state
-3. Delete BOOTSTRAP.md and BOOTSTRAP-REFERENCE.md
-
----
-
-_Make it count._
+One-shot. The files go regardless of how far you got.

package/src/providers/model-catalog.ts

@@ -59,10 +59,10 @@ export const PROVIDER_CATALOG: ProviderCatalogEntry[] = [
         supportsVision: true,
         supportsToolUse: true,
         pricing: {
-          inputPer1mTokens: 15,
-          outputPer1mTokens: 75,
-          cacheWritePer1mTokens: 18.75,
-          cacheReadPer1mTokens: 1.5,
+          inputPer1mTokens: 5,
+          outputPer1mTokens: 25,
+          cacheWritePer1mTokens: 6.25,
+          cacheReadPer1mTokens: 0.5,
         },
       },
       {
@@ -75,10 +75,10 @@ export const PROVIDER_CATALOG: ProviderCatalogEntry[] = [
         supportsVision: true,
         supportsToolUse: true,
         pricing: {
-          inputPer1mTokens: 15,
-          outputPer1mTokens: 75,
-          cacheWritePer1mTokens: 18.75,
-          cacheReadPer1mTokens: 1.5,
+          inputPer1mTokens: 5,
+          outputPer1mTokens: 25,
+          cacheWritePer1mTokens: 6.25,
+          cacheReadPer1mTokens: 0.5,
         },
       },
       {
@@ -114,7 +114,7 @@ export const PROVIDER_CATALOG: ProviderCatalogEntry[] = [
         },
       },
     ],
-    defaultModel: "claude-opus-4-7",
+    defaultModel: "claude-sonnet-4-6",
     apiKeyUrl: "https://console.anthropic.com/settings/keys",
     apiKeyPlaceholder: "sk-ant-api03-...",
   },
@@ -143,7 +143,7 @@ export const PROVIDER_CATALOG: ProviderCatalogEntry[] = [
         supportsToolUse: true,
         pricing: {
           inputPer1mTokens: 2.5,
-          outputPer1mTokens: 10.0,
+          outputPer1mTokens: 15.0,
           cacheReadPer1mTokens: 0.25,
         },
       },
@@ -157,8 +157,8 @@ export const PROVIDER_CATALOG: ProviderCatalogEntry[] = [
         supportsVision: true,
         supportsToolUse: true,
         pricing: {
-          inputPer1mTokens: 3.0,
-          outputPer1mTokens: 12.0,
+          inputPer1mTokens: 1.75,
+          outputPer1mTokens: 14.0,
           cacheReadPer1mTokens: 0.3,
         },
       },
@@ -173,7 +173,7 @@ export const PROVIDER_CATALOG: ProviderCatalogEntry[] = [
         supportsToolUse: true,
         pricing: {
           inputPer1mTokens: 0.5,
-          outputPer1mTokens: 2.0,
+          outputPer1mTokens: 3.0,
           cacheReadPer1mTokens: 0.05,
         },
       },
@@ -187,8 +187,8 @@ export const PROVIDER_CATALOG: ProviderCatalogEntry[] = [
         supportsVision: true,
         supportsToolUse: true,
         pricing: {
-          inputPer1mTokens: 0.1,
-          outputPer1mTokens: 0.4,
+          inputPer1mTokens: 0.2,
+          outputPer1mTokens: 1.25,
           cacheReadPer1mTokens: 0.01,
         },
       },
@@ -222,9 +222,9 @@ export const PROVIDER_CATALOG: ProviderCatalogEntry[] = [
         supportsVision: true,
         supportsToolUse: true,
         pricing: {
-          inputPer1mTokens: 0.3,
-          outputPer1mTokens: 2.5,
-          cacheReadPer1mTokens: 0.075,
+          inputPer1mTokens: 0.15,
+          outputPer1mTokens: 0.6,
+          cacheReadPer1mTokens: 0.0375,
         },
       },
       {
@@ -237,9 +237,9 @@ export const PROVIDER_CATALOG: ProviderCatalogEntry[] = [
         supportsVision: true,
         supportsToolUse: true,
         pricing: {
-          inputPer1mTokens: 0.1,
-          outputPer1mTokens: 0.4,
-          cacheReadPer1mTokens: 0.025,
+          inputPer1mTokens: 0.02,
+          outputPer1mTokens: 0.1,
+          cacheReadPer1mTokens: 0.005,
         },
       },
       {
@@ -345,16 +345,24 @@ export const PROVIDER_CATALOG: ProviderCatalogEntry[] = [
     },
     models: [
       // Anthropic
+      // OpenRouter proxies anthropic/* through Anthropic's Messages API, so
+      // prompt caching and cache TTL metadata pass through unchanged and
+      // billing matches Anthropic's direct rates.
       {
         id: "anthropic/claude-opus-4.7",
         displayName: "Claude Opus 4.7",
         contextWindowTokens: 200000,
         maxOutputTokens: 32000,
         supportsThinking: true,
-        supportsCaching: false,
+        supportsCaching: true,
         supportsVision: true,
         supportsToolUse: true,
-        pricing: { inputPer1mTokens: 15, outputPer1mTokens: 75 },
+        pricing: {
+          inputPer1mTokens: 5,
+          outputPer1mTokens: 25,
+          cacheWritePer1mTokens: 6.25,
+          cacheReadPer1mTokens: 0.5,
+        },
       },
       {
         id: "anthropic/claude-opus-4.6",
@@ -362,10 +370,15 @@ export const PROVIDER_CATALOG: ProviderCatalogEntry[] = [
         contextWindowTokens: 200000,
         maxOutputTokens: 32000,
         supportsThinking: true,
-        supportsCaching: false,
+        supportsCaching: true,
         supportsVision: true,
         supportsToolUse: true,
-        pricing: { inputPer1mTokens: 15, outputPer1mTokens: 75 },
+        pricing: {
+          inputPer1mTokens: 5,
+          outputPer1mTokens: 25,
+          cacheWritePer1mTokens: 6.25,
+          cacheReadPer1mTokens: 0.5,
+        },
       },
       {
         id: "anthropic/claude-sonnet-4.6",
@@ -373,10 +386,15 @@ export const PROVIDER_CATALOG: ProviderCatalogEntry[] = [
         contextWindowTokens: 200000,
         maxOutputTokens: 64000,
         supportsThinking: true,
-        supportsCaching: false,
+        supportsCaching: true,
         supportsVision: true,
         supportsToolUse: true,
-        pricing: { inputPer1mTokens: 3, outputPer1mTokens: 15 },
+        pricing: {
+          inputPer1mTokens: 3,
+          outputPer1mTokens: 15,
+          cacheWritePer1mTokens: 3.75,
+          cacheReadPer1mTokens: 0.3,
+        },
       },
       {
         id: "anthropic/claude-haiku-4.5",
@@ -384,10 +402,15 @@ export const PROVIDER_CATALOG: ProviderCatalogEntry[] = [
         contextWindowTokens: 200000,
         maxOutputTokens: 16000,
         supportsThinking: true,
-        supportsCaching: false,
+        supportsCaching: true,
         supportsVision: true,
         supportsToolUse: true,
-        pricing: { inputPer1mTokens: 1, outputPer1mTokens: 5 },
+        pricing: {
+          inputPer1mTokens: 1,
+          outputPer1mTokens: 5,
+          cacheWritePer1mTokens: 1.25,
+          cacheReadPer1mTokens: 0.1,
+        },
       },
       // xAI
       {

package/src/providers/model-intents.ts

@@ -43,7 +43,7 @@ const PROVIDER_MODEL_INTENTS: Record<string, Record<ModelIntent, string>> = {
   },
 };
 
-const FALLBACK_DEFAULT_MODEL = "claude-opus-4-7";
+const FALLBACK_DEFAULT_MODEL = "claude-sonnet-4-6";
 
 const MODEL_INTENTS = new Set<ModelIntent>([
   "latency-optimized",

package/src/providers/openrouter/client.ts

@@ -157,7 +157,11 @@ export class OpenRouterProvider extends OpenAIChatCompletionsProvider {
     };
     const only = extractOnlyList(config);
     if (only.length > 0) {
-      extras.provider = { only };
+      const existingProvider = (config?.provider ?? {}) as Record<
+        string,
+        unknown
+      >;
+      extras.provider = { ...existingProvider, only };
     }
     return extras;
   }

package/src/providers/speech-to-text/deepgram-realtime.test.ts

@@ -805,6 +805,67 @@ describe("DeepgramRealtimeTranscriber", () => {
     expect(errorEvents).toHaveLength(0);
   });
 
+  // ─────────────────────────────────────────────────────────────────
+  // KeepAlive
+  // ─────────────────────────────────────────────────────────────────
+
+  test("sends KeepAlive frames at the configured interval while open", async () => {
+    const { transcriber } = await startSession({
+      keepaliveIntervalMs: 30,
+    });
+
+    // Wait long enough that at least two KeepAlives fire even on a loaded
+    // CI runner with event-loop jitter.
+    await new Promise((resolve) => setTimeout(resolve, 250));
+
+    const keepalives = mockWs.sentData.filter(
+      (d) => typeof d === "string" && d === '{"type":"KeepAlive"}',
+    );
+    expect(keepalives.length).toBeGreaterThanOrEqual(2);
+
+    transcriber.stop();
+  });
+
+  test("KeepAlive timer stops firing after stop()", async () => {
+    const { transcriber } = await startSession({
+      keepaliveIntervalMs: 30,
+    });
+
+    // Let one KeepAlive fire so we know the interval is running.
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    const beforeStop = mockWs.sentData.filter(
+      (d) => typeof d === "string" && d === '{"type":"KeepAlive"}',
+    ).length;
+    expect(beforeStop).toBeGreaterThanOrEqual(1);
+
+    transcriber.stop();
+
+    // Drain the close grace flow.
+    await new Promise((resolve) => setTimeout(resolve, 80));
+
+    // The interval should be cleared — count must not have grown beyond
+    // what was already buffered before stop(). Tolerate one extra fire
+    // racing with stop()'s synchronous clear path, but no more.
+    const afterStop = mockWs.sentData.filter(
+      (d) => typeof d === "string" && d === '{"type":"KeepAlive"}',
+    ).length;
+    expect(afterStop).toBeLessThanOrEqual(beforeStop + 1);
+  });
+
+  test("keepaliveIntervalMs=0 disables the timer entirely", async () => {
+    const { transcriber } = await startSession({
+      keepaliveIntervalMs: 0,
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 80));
+    const keepalives = mockWs.sentData.filter(
+      (d) => typeof d === "string" && d === '{"type":"KeepAlive"}',
+    );
+    expect(keepalives).toHaveLength(0);
+
+    transcriber.stop();
+  });
+
   // ─────────────────────────────────────────────────────────────────
   // WebSocket URL construction
   // ─────────────────────────────────────────────────────────────────