@vellumai/assistant 0.8.4 → 0.8.5

package/src/__tests__/prechat-onboarding-contract.test.ts

@@ -61,22 +61,43 @@ mock.module("../prompts/user-reference.js", () => ({
   resolveUserPronouns: () => null,
 }));
 
-const { buildSystemPrompt, SYSTEM_PROMPT_CACHE_BOUNDARY } =
-  await import("../prompts/system-prompt.js");
+// Stub persona-resolver so tests can dictate the slug `buildSystemPrompt`
+// sees without writing contact rows to the test DB. User and channel
+// persona content now flows through bundled sections that read files
+// directly, so tests write the persona file under TEST_DIR rather than
+// stubbing the content here.
+const mockPersona: {
+  userSlug: string | null;
+  guardianPersona: string | null;
+} = { userSlug: null, guardianPersona: null };
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const realPersonaResolver = require("../prompts/persona-resolver.js");
+mock.module("../prompts/persona-resolver.js", () => ({
+  ...realPersonaResolver,
+  resolveUserSlug: () => mockPersona.userSlug,
+  resolveGuardianPersona: () => mockPersona.guardianPersona,
+}));
+
+const { buildSystemPrompt } = await import("../prompts/system-prompt.js");
 
 /**
- * Extract the dynamic block (workspace-file content) from the full system prompt.
+ * Slice the assembled system prompt from the `# First-Run Ritual`
+ * marker through the end of the prompt, returning just the
+ * `13-bootstrap` section's rendered payload.  Returns "" when the
+ * section isn't rendered (no BOOTSTRAP.md, `excludeBootstrap: true`,
+ * etc.).
  */
-function dynamicBlock(result: string): string {
-  const boundaryIdx = result.indexOf(SYSTEM_PROMPT_CACHE_BOUNDARY);
-  return boundaryIdx >= 0
-    ? result.slice(boundaryIdx + SYSTEM_PROMPT_CACHE_BOUNDARY.length)
-    : result;
+function bootstrapBlock(result: string): string {
+  const ritualIdx = result.indexOf("# First-Run Ritual");
+  if (ritualIdx < 0) return "";
+  return result.slice(ritualIdx);
 }
 
 describe("pre-chat onboarding contract", () => {
   beforeEach(() => {
     mkdirSync(TEST_DIR, { recursive: true });
+    mockPersona.userSlug = null;
+    mockPersona.guardianPersona = null;
   });
 
   afterEach(() => {
@@ -87,6 +108,8 @@ describe("pre-chat onboarding contract", () => {
       "BOOTSTRAP.md",
       "BOOTSTRAP-REFERENCE.md",
       "UPDATES.md",
+      "users",
+      "channels",
     ]) {
       const p = join(TEST_DIR, name);
       if (existsSync(p)) rmSync(p, { recursive: true, force: true });
@@ -151,20 +174,20 @@ describe("pre-chat onboarding contract", () => {
       };
 
       const result = buildSystemPrompt({ onboardingContext: context });
-      const dynamic = dynamicBlock(result);
+      const bootstrap = bootstrapBlock(result);
 
-      expect(dynamic).toContain("## First-Run User Context");
-      expect(dynamic).toContain(
+      expect(bootstrap).toContain("## First-Run User Context");
+      expect(bootstrap).toContain(
         "The user completed setup before this conversation.",
       );
-      expect(dynamic).toContain("- Daily tools: Slack, Linear");
-      expect(dynamic).toContain("- Common work: builds code, apps, or tools");
-      expect(dynamic).toContain("- Name: Alex");
-      expect(dynamic).toContain("- Chosen assistant name: Nova");
-      expect(dynamic).toContain("Apply this context quietly.");
+      expect(bootstrap).toContain("- Daily tools: Slack, Linear");
+      expect(bootstrap).toContain("- Common work: builds code, apps, or tools");
+      expect(bootstrap).toContain("- Name: Alex");
+      expect(bootstrap).toContain("- Chosen assistant name: Nova");
+      expect(bootstrap).toContain("Apply this context quietly.");
 
       // Raw JSON must NOT be present
-      expect(dynamic).not.toContain("```json");
+      expect(bootstrap).not.toContain("```json");
     });
 
     test("does NOT inject onboarding context when BOOTSTRAP.md does not exist", () => {
@@ -177,11 +200,11 @@ describe("pre-chat onboarding contract", () => {
       };
 
       const result = buildSystemPrompt({ onboardingContext: context });
-      const dynamic = dynamicBlock(result);
+      const bootstrap = bootstrapBlock(result);
 
-      expect(dynamic).not.toContain("## First-Run User Context");
-      expect(dynamic).not.toContain("First-Run User Context");
-      expect(dynamic).not.toContain("- Daily tools:");
+      expect(bootstrap).not.toContain("## First-Run User Context");
+      expect(bootstrap).not.toContain("First-Run User Context");
+      expect(bootstrap).not.toContain("- Daily tools:");
     });
 
     test("does NOT inject onboarding context when excludeBootstrap is true", () => {
@@ -200,10 +223,10 @@ describe("pre-chat onboarding contract", () => {
         onboardingContext: context,
         excludeBootstrap: true,
       });
-      const dynamic = dynamicBlock(result);
+      const bootstrap = bootstrapBlock(result);
 
-      expect(dynamic).not.toContain("## First-Run User Context");
-      expect(dynamic).not.toContain("First-Run Ritual");
+      expect(bootstrap).not.toContain("## First-Run User Context");
+      expect(bootstrap).not.toContain("First-Run Ritual");
     });
 
     test("omits onboarding section when context is undefined", () => {
@@ -213,12 +236,12 @@ describe("pre-chat onboarding contract", () => {
       );
 
       const result = buildSystemPrompt({ onboardingContext: undefined });
-      const dynamic = dynamicBlock(result);
+      const bootstrap = bootstrapBlock(result);
 
       // Bootstrap should still be present
-      expect(dynamic).toContain("First-Run Ritual");
+      expect(bootstrap).toContain("First-Run Ritual");
       // But no onboarding context section
-      expect(dynamic).not.toContain("## First-Run User Context");
+      expect(bootstrap).not.toContain("## First-Run User Context");
     });
 
     test("accepts all four personality tones", () => {
@@ -238,10 +261,10 @@ describe("pre-chat onboarding contract", () => {
         };
 
         const result = buildSystemPrompt({ onboardingContext: context });
-        const dynamic = dynamicBlock(result);
+        const bootstrap = bootstrapBlock(result);
 
-        expect(dynamic).toContain("## First-Run User Context");
-        expect(dynamic).toContain(`- Preferred initial voice: ${tone}`);
+        expect(bootstrap).toContain("## First-Run User Context");
+        expect(bootstrap).toContain(`- Preferred initial voice: ${tone}`);
       }
     });
 
@@ -260,20 +283,20 @@ describe("pre-chat onboarding contract", () => {
       };
 
       const result = buildSystemPrompt({ onboardingContext: context });
-      const dynamic = dynamicBlock(result);
+      const bootstrap = bootstrapBlock(result);
 
       // Should contain compact markdown lines
-      expect(dynamic).toContain("## First-Run User Context");
-      expect(dynamic).toContain("- Name: Jane");
-      expect(dynamic).toContain("- Common work: plans and coordinates work");
-      expect(dynamic).toContain("- Daily tools: Notion");
-      expect(dynamic).toContain("- Chosen assistant name: Kit");
-      expect(dynamic).toContain("- Preferred initial voice: warm");
+      expect(bootstrap).toContain("## First-Run User Context");
+      expect(bootstrap).toContain("- Name: Jane");
+      expect(bootstrap).toContain("- Common work: plans and coordinates work");
+      expect(bootstrap).toContain("- Daily tools: Notion");
+      expect(bootstrap).toContain("- Chosen assistant name: Kit");
+      expect(bootstrap).toContain("- Preferred initial voice: warm");
 
       // Must NOT contain JSON output
-      expect(dynamic).not.toContain("```json");
+      expect(bootstrap).not.toContain("```json");
       const expectedJson = JSON.stringify(context, null, 2);
-      expect(dynamic).not.toContain(expectedJson);
+      expect(bootstrap).not.toContain(expectedJson);
     });
 
     test("empty tools/tasks arrays result in no Daily tools / Common work lines", () => {
@@ -290,12 +313,12 @@ describe("pre-chat onboarding contract", () => {
       };
 
       const result = buildSystemPrompt({ onboardingContext: context });
-      const dynamic = dynamicBlock(result);
+      const bootstrap = bootstrapBlock(result);
 
-      expect(dynamic).toContain("## First-Run User Context");
-      expect(dynamic).toContain("- Name: Alex");
-      expect(dynamic).not.toContain("- Daily tools:");
-      expect(dynamic).not.toContain("- Common work:");
+      expect(bootstrap).toContain("## First-Run User Context");
+      expect(bootstrap).toContain("- Name: Alex");
+      expect(bootstrap).not.toContain("- Daily tools:");
+      expect(bootstrap).not.toContain("- Common work:");
     });
 
     test("absent userName results in no Name line", () => {
@@ -311,16 +334,16 @@ describe("pre-chat onboarding contract", () => {
       };
 
       const result = buildSystemPrompt({ onboardingContext: context });
-      const dynamic = dynamicBlock(result);
+      const bootstrap = bootstrapBlock(result);
 
-      expect(dynamic).toContain("## First-Run User Context");
-      expect(dynamic).not.toContain("- Name:");
+      expect(bootstrap).toContain("## First-Run User Context");
+      expect(bootstrap).not.toContain("- Name:");
       // Other fields should still be present
-      expect(dynamic).toContain("- Daily tools: Slack");
-      expect(dynamic).toContain(
+      expect(bootstrap).toContain("- Daily tools: Slack");
+      expect(bootstrap).toContain(
         "- Common work: writes docs, emails, or content",
       );
-      expect(dynamic).toContain("- Preferred initial voice: warm");
+      expect(bootstrap).toContain("- Preferred initial voice: warm");
     });
   });
 
@@ -356,26 +379,26 @@ describe("pre-chat onboarding contract", () => {
       };
 
       const result = buildSystemPrompt({ onboardingContext: context });
-      const dynamic = dynamicBlock(result);
+      const bootstrap = bootstrapBlock(result);
 
       // Heading is present
-      expect(dynamic).toContain("## First-Run User Context");
+      expect(bootstrap).toContain("## First-Run User Context");
 
       // Normalized labels appear (capitalised tool names, human-readable task descriptions)
-      expect(dynamic).toContain("- Daily tools: Slack, Notion, Linear");
-      expect(dynamic).toContain("- Name: Alice");
-      expect(dynamic).toContain("- Chosen assistant name: Pax");
-      expect(dynamic).toContain("- Preferred initial voice: grounded");
+      expect(bootstrap).toContain("- Daily tools: Slack, Notion, Linear");
+      expect(bootstrap).toContain("- Name: Alice");
+      expect(bootstrap).toContain("- Chosen assistant name: Pax");
+      expect(bootstrap).toContain("- Preferred initial voice: grounded");
       // Common work descriptions are normalised from task IDs
-      expect(dynamic).toContain("- Common work:");
-
-      // No raw JSON anywhere in the dynamic block
-      expect(dynamic).not.toContain("```json");
-      expect(dynamic).not.toContain('"tools"');
-      expect(dynamic).not.toContain('"tasks"');
-      expect(dynamic).not.toContain('"tone"');
-      expect(dynamic).not.toContain('"userName"');
-      expect(dynamic).not.toContain('"assistantName"');
+      expect(bootstrap).toContain("- Common work:");
+
+      // No raw JSON anywhere in the bootstrap block
+      expect(bootstrap).not.toContain("```json");
+      expect(bootstrap).not.toContain('"tools"');
+      expect(bootstrap).not.toContain('"tasks"');
+      expect(bootstrap).not.toContain('"tone"');
+      expect(bootstrap).not.toContain('"userName"');
+      expect(bootstrap).not.toContain('"assistantName"');
     });
 
     test("without BOOTSTRAP.md, onboarding context does NOT appear in system prompt", () => {
@@ -389,15 +412,15 @@ describe("pre-chat onboarding contract", () => {
       };
 
       const result = buildSystemPrompt({ onboardingContext: context });
-      const dynamic = dynamicBlock(result);
+      const bootstrap = bootstrapBlock(result);
 
       // Onboarding section must be absent
-      expect(dynamic).not.toContain("## First-Run User Context");
-      expect(dynamic).not.toContain("First-Run Ritual");
-      expect(dynamic).not.toContain("- Daily tools:");
-      expect(dynamic).not.toContain("- Name: Bob");
-      expect(dynamic).not.toContain("- Chosen assistant name:");
-      expect(dynamic).not.toContain("Apply this context quietly.");
+      expect(bootstrap).not.toContain("## First-Run User Context");
+      expect(bootstrap).not.toContain("First-Run Ritual");
+      expect(bootstrap).not.toContain("- Daily tools:");
+      expect(bootstrap).not.toContain("- Name: Bob");
+      expect(bootstrap).not.toContain("- Chosen assistant name:");
+      expect(bootstrap).not.toContain("Apply this context quietly.");
     });
 
     test("excludeBootstrap suppresses both bootstrap and onboarding sections", () => {
@@ -418,34 +441,38 @@ describe("pre-chat onboarding contract", () => {
         onboardingContext: context,
         excludeBootstrap: true,
       });
-      const dynamic = dynamicBlock(result);
+      const bootstrap = bootstrapBlock(result);
 
       // Both bootstrap and onboarding must be suppressed
-      expect(dynamic).not.toContain("First-Run Ritual");
-      expect(dynamic).not.toContain("## First-Run User Context");
-      expect(dynamic).not.toContain("- Daily tools:");
-      expect(dynamic).not.toContain("- Name: Charlie");
-      expect(dynamic).not.toContain("Apply this context quietly.");
+      expect(bootstrap).not.toContain("First-Run Ritual");
+      expect(bootstrap).not.toContain("## First-Run User Context");
+      expect(bootstrap).not.toContain("- Daily tools:");
+      expect(bootstrap).not.toContain("- Name: Charlie");
+      expect(bootstrap).not.toContain("Apply this context quietly.");
     });
 
     test("userPersona is included independently of onboarding context", () => {
-      // No BOOTSTRAP.md — the durable persona path after bootstrap is deleted
-      const personaContent =
-        "# User Persona\n\nPrefers concise answers. Works in fintech.";
+      // No BOOTSTRAP.md — the durable persona path after bootstrap is deleted.
+      // User persona content now lives in `users/<slug>.md` and renders
+      // via the `10-user-persona` bundled section in the static prefix.
+      mkdirSync(join(TEST_DIR, "users"), { recursive: true });
+      writeFileSync(
+        join(TEST_DIR, "users", "default.md"),
+        "# User Persona\n\nPrefers concise answers. Works in fintech.",
+      );
 
       const result = buildSystemPrompt({
-        userPersona: personaContent,
         // No onboardingContext — simulates post-onboarding conversation
       });
-      const dynamic = dynamicBlock(result);
 
       // Persona content appears in prompt even without bootstrap or onboarding
-      expect(dynamic).toContain("# User Persona");
-      expect(dynamic).toContain("Prefers concise answers. Works in fintech.");
+      expect(result).toContain("# User Persona");
+      expect(result).toContain("Prefers concise answers. Works in fintech.");
 
       // No onboarding section should be present
-      expect(dynamic).not.toContain("## First-Run User Context");
-      expect(dynamic).not.toContain("First-Run Ritual");
+      const bootstrap = bootstrapBlock(result);
+      expect(bootstrap).not.toContain("## First-Run User Context");
+      expect(bootstrap).not.toContain("First-Run Ritual");
     });
 
     test("userPersona appears alongside onboarding context during first run", () => {
@@ -454,8 +481,14 @@ describe("pre-chat onboarding contract", () => {
         "# Bootstrap\n\nOnboarding flow.",
       );
 
-      const personaContent =
-        "# User Persona\n\nEarly-stage startup founder. Likes bullet points.";
+      // User persona file renders via the `10-user-persona` section
+      // and the First-Run Ritual + onboarding context render via the
+      // `13-bootstrap` section — both in the static prefix.
+      mkdirSync(join(TEST_DIR, "users"), { recursive: true });
+      writeFileSync(
+        join(TEST_DIR, "users", "default.md"),
+        "# User Persona\n\nEarly-stage startup founder. Likes bullet points.",
+      );
       const context: OnboardingContext = {
         tools: ["slack"],
         tasks: ["writing"],
@@ -464,17 +497,17 @@ describe("pre-chat onboarding contract", () => {
       };
 
       const result = buildSystemPrompt({
-        userPersona: personaContent,
         onboardingContext: context,
       });
-      const dynamic = dynamicBlock(result);
-
-      // Both persona and onboarding context appear
-      expect(dynamic).toContain("# User Persona");
-      expect(dynamic).toContain("Likes bullet points.");
-      expect(dynamic).toContain("## First-Run User Context");
-      expect(dynamic).toContain("- Name: Dana");
-      expect(dynamic).toContain("- Daily tools: Slack");
+      const bootstrap = bootstrapBlock(result);
+
+      // Both persona and onboarding context appear in the static prefix
+      // (`10-user-persona` and `13-bootstrap` respectively)
+      expect(result).toContain("# User Persona");
+      expect(result).toContain("Likes bullet points.");
+      expect(bootstrap).toContain("## First-Run User Context");
+      expect(bootstrap).toContain("- Name: Dana");
+      expect(bootstrap).toContain("- Daily tools: Slack");
     });
   });
 });

package/src/__tests__/pricing.test.ts

@@ -216,6 +216,17 @@ describe("resolvePricing", () => {
       expect(result.estimatedCostUsd).toBe(0.25 + 1.5);
     });
 
+    test("returns priced for gemini-3.1-flash-lite", () => {
+      const result = resolvePricing(
+        "gemini",
+        "gemini-3.1-flash-lite",
+        1_000_000,
+        1_000_000,
+      );
+      expect(result.pricingStatus).toBe("priced");
+      expect(result.estimatedCostUsd).toBe(0.25 + 1.5);
+    });
+
     test("prices gemini-2.5-pro at the low-context tier through 200k input tokens", () => {
       const result = resolvePricing(
         "gemini",
@@ -489,6 +500,7 @@ describe("resolvePricingForUsage", () => {
     const cases = [
       ["gemini-3-flash-preview", 0.05],
       ["gemini-3.1-flash-lite-preview", 0.025],
+      ["gemini-3.1-flash-lite", 0.025],
       ["gemini-2.5-flash", 0.03],
       ["gemini-2.5-flash-lite", 0.01],
       ["gemini-2.5-pro", 0.625],

package/src/__tests__/prune-jobs-changes-parser.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Unit coverage for the `parseDeletedCount` helper that reads the row
+ * count out of the sqlite3 CLI's stdout after a prune DELETE.
+ *
+ * The shape of the stdout we expect:
+ *
+ *   "<n>\n"
+ *
+ * — where `<n>` is the `SELECT changes()` value the CLI prints in
+ * default output mode after the DELETE statement runs. The helper has
+ * to tolerate empty/missing stdout, blank trailing lines, and any
+ * incidental log line emitted above the count.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { _parseDeletedCount as parseDeletedCount } from "../memory/job-handlers/cleanup.js";
+
+describe("parseDeletedCount", () => {
+  test("bare integer on its own line", () => {
+    expect(parseDeletedCount("100\n")).toBe(100);
+  });
+
+  test("integer with trailing whitespace/blank lines", () => {
+    expect(parseDeletedCount("100\n\n")).toBe(100);
+    expect(parseDeletedCount("  42  \n")).toBe(42);
+  });
+
+  test("zero is a valid count", () => {
+    expect(parseDeletedCount("0\n")).toBe(0);
+  });
+
+  test("PRUNE_LOG_BATCH_LIMIT value", () => {
+    expect(parseDeletedCount("1000\n")).toBe(1000);
+  });
+
+  test("undefined stdout (subprocess never wrote anything)", () => {
+    expect(parseDeletedCount(undefined)).toBe(0);
+  });
+
+  test("empty stdout", () => {
+    expect(parseDeletedCount("")).toBe(0);
+  });
+
+  test("only whitespace", () => {
+    expect(parseDeletedCount("   \n\n  ")).toBe(0);
+  });
+
+  test("non-numeric lines are skipped, last numeric line wins", () => {
+    // Sample shape if the CLI ever logged an incidental warning above the count
+    expect(parseDeletedCount("warning: foo\n250\n")).toBe(250);
+  });
+
+  test("negative values are not accepted (sqlite changes() is unsigned)", () => {
+    expect(parseDeletedCount("-1\n")).toBe(0);
+  });
+
+  test("CRLF line endings", () => {
+    expect(parseDeletedCount("750\r\n")).toBe(750);
+  });
+});

package/src/__tests__/registry.test.ts

@@ -1,7 +1,6 @@
 import { afterAll, beforeEach, describe, expect, test } from "bun:test";
 
 import { RiskLevel } from "../permissions/types.js";
-import type { ToolDefinition } from "../providers/types.js";
 import {
   __clearRegistryForTesting,
   __resetRegistryForTesting,
@@ -30,13 +29,8 @@ function makeFakeTool(name: string): Tool {
     description: `Fake ${name}`,
     category: "test",
     defaultRiskLevel: RiskLevel.Low,
-    getDefinition(): ToolDefinition {
-      return {
-        name,
-        description: `Fake ${name}`,
-        input_schema: { type: "object", properties: {}, required: [] },
-      };
-    },
+    executionTarget: "sandbox",
+    input_schema: { type: "object", properties: {}, required: [] },
     async execute(
       _input: Record<string, unknown>,
       _context: ToolContext,

package/src/__tests__/require-fresh-approval.test.ts

@@ -103,7 +103,7 @@ mock.module("../permissions/checker.js", () => ({
 mock.module("../memory/tool-usage-store.js", () => ({
   recordToolInvocation: () => {},
   getRecentInvocations: () => [],
-  rotateToolInvocations: () => 0,
+  rotateToolInvocations: async () => 0,
 }));
 
 mock.module("../tools/registry.js", () => ({
@@ -116,7 +116,7 @@ mock.module("../tools/registry.js", () => ({
       category: isGmailTool ? "gmail" : "credential-execution",
       defaultRiskLevel: "high",
       executionTarget: isGmailTool ? ("host" as const) : undefined,
-      getDefinition: () => ({}),
+      input_schema: {},
       execute: async () => fakeToolResult,
     };
   },

package/src/__tests__/runtime-events-sse-bilingual.test.ts

@@ -0,0 +1,154 @@
+/**
+ * `GET /v1/events` (`handleSubscribeAssistantEvents`) — bilingual scope
+ * resolution. Two query params are accepted, with distinct semantics:
+ *
+ *   - `?conversationId=<internal-id>` — looks up the conversation row
+ *     directly by its assistant-minted id. 404 if not found. Does NOT
+ *     materialise a new row.
+ *   - `?conversationKey=<external-key>` — resolves via the
+ *     `conversation_keys` table; materialises on first use. Ignored when
+ *     `conversationId` is also supplied.
+ *
+ * Companion to `runtime-events-sse.test.ts`, which exercises the broader
+ * `?conversationKey=` happy/error path.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+mock.module("../config/loader.js", () => ({
+  getConfig: () => ({
+    ui: {},
+    model: "test",
+    provider: "test",
+    memory: { enabled: false },
+    rateLimit: { maxRequestsPerMinute: 0 },
+    secretDetection: { enabled: false },
+  }),
+}));
+
+import { getOrCreateConversation } from "../memory/conversation-key-store.js";
+import { getDb } from "../memory/db-connection.js";
+import { initializeDb } from "../memory/db-init.js";
+import { buildAssistantEvent } from "../runtime/assistant-event.js";
+import { AssistantEventHub } from "../runtime/assistant-event-hub.js";
+import {
+  BadRequestError,
+  NotFoundError,
+} from "../runtime/routes/errors.js";
+import { handleSubscribeAssistantEvents } from "../runtime/routes/events-routes.js";
+
+initializeDb();
+
+describe("GET /v1/events — bilingual scope query params", () => {
+  beforeEach(() => {
+    const db = getDb();
+    db.run("DELETE FROM conversation_keys");
+    db.run("DELETE FROM conversations");
+  });
+
+  test("?conversationId=<existing-id> scopes the stream to that conversation", async () => {
+    // Materialise a conversation via the key path, then subscribe to it
+    // directly by its internal id.
+    const { conversationId } = getOrCreateConversation("sse-id-scope-source");
+
+    const ac = new AbortController();
+    const testHub = new AssistantEventHub();
+
+    const stream = handleSubscribeAssistantEvents(
+      {
+        queryParams: { conversationId },
+        abortSignal: ac.signal,
+      },
+      { hub: testHub },
+    );
+
+    const reader = stream.getReader();
+    // Consume the initial heartbeat.
+    const heartbeat = await reader.read();
+    expect(new TextDecoder().decode(heartbeat.value)).toBe(": heartbeat\n\n");
+
+    // Publish an event scoped to that conversation — should be delivered.
+    await testHub.publish(buildAssistantEvent({ type: "pong" }, conversationId));
+
+    const { value, done } = await reader.read();
+    ac.abort();
+
+    expect(done).toBe(false);
+    const frame = new TextDecoder().decode(value);
+    expect(frame).toContain("event: assistant_event");
+    expect(frame).toContain(`"conversationId":"${conversationId}"`);
+  });
+
+  test("?conversationId=<non-existent-id> throws NotFoundError", () => {
+    expect(() =>
+      handleSubscribeAssistantEvents({
+        queryParams: { conversationId: "does-not-exist" },
+        abortSignal: new AbortController().signal,
+      }),
+    ).toThrow(NotFoundError);
+  });
+
+  test("?conversationId is honored and ?conversationKey is ignored when both are present", async () => {
+    // Materialise two distinct conversations: one we'll subscribe to by id,
+    // one we'll publish to via the ignored key.
+    const { conversationId: idConv } = getOrCreateConversation("sse-id-wins");
+    const { conversationId: keyConv } = getOrCreateConversation(
+      "sse-key-ignored",
+    );
+    expect(idConv).not.toBe(keyConv);
+
+    const ac = new AbortController();
+    const testHub = new AssistantEventHub();
+
+    const stream = handleSubscribeAssistantEvents(
+      {
+        queryParams: {
+          conversationId: idConv,
+          conversationKey: "sse-key-ignored",
+        },
+        abortSignal: ac.signal,
+      },
+      { hub: testHub },
+    );
+    const reader = stream.getReader();
+    await reader.read(); // heartbeat
+
+    // Publish on the "key" conversation — should NOT be delivered (filter
+    // is locked to idConv because conversationId wins).
+    await testHub.publish(buildAssistantEvent({ type: "pong" }, keyConv));
+    // Publish on the "id" conversation — should be delivered.
+    await testHub.publish(buildAssistantEvent({ type: "pong" }, idConv));
+
+    const { value } = await reader.read();
+    ac.abort();
+    const frame = new TextDecoder().decode(value);
+
+    expect(frame).toContain(`"conversationId":"${idConv}"`);
+    expect(frame).not.toContain(`"conversationId":"${keyConv}"`);
+  });
+
+  test("empty conversationId is rejected with BadRequestError", () => {
+    expect(() =>
+      handleSubscribeAssistantEvents({
+        queryParams: { conversationId: "" },
+        abortSignal: new AbortController().signal,
+      }),
+    ).toThrow(BadRequestError);
+  });
+
+  test("empty conversationKey is still rejected (legacy parity)", () => {
+    expect(() =>
+      handleSubscribeAssistantEvents({
+        queryParams: { conversationKey: "" },
+        abortSignal: new AbortController().signal,
+      }),
+    ).toThrow(BadRequestError);
+  });
+});