@vellumai/assistant 0.8.6 → 0.8.7

package/src/__tests__/disk-pressure-guard.test.ts

@@ -40,6 +40,8 @@ const {
   DISK_PRESSURE_CLEAR_THRESHOLD_PERCENT,
   DISK_PRESSURE_OVERRIDE_CONFIRMATION,
   DISK_PRESSURE_THRESHOLD_PERCENT,
+  DISK_PRESSURE_WARNING_CLEAR_THRESHOLD_PERCENT,
+  DISK_PRESSURE_WARNING_THRESHOLD_PERCENT,
   __getDiskPressureGuardTimerForTests,
   __resetDiskPressureGuardForTests,
   acknowledgeDiskPressureLock,
@@ -276,4 +278,68 @@ describe("disk pressure guard", () => {
     stopDiskPressureGuard();
     expect(__getDiskPressureGuardTimerForTests()).toBeNull();
   });
+
+  test("does not enter warning until usage reaches the warning threshold", () => {
+    // Below 80% and never previously in a pressure state.
+    setDiskUsage(DISK_PRESSURE_WARNING_THRESHOLD_PERCENT - 2);
+
+    const status = evaluateDiskPressureNow();
+
+    expect(status.state).toBe("ok");
+  });
+
+  test("holds the warning state across a dip within the warning clear deadband", () => {
+    setDiskUsage(DISK_PRESSURE_WARNING_THRESHOLD_PERCENT + 2);
+    expect(evaluateDiskPressureNow().state).toBe("warning");
+
+    // Below the 80% warning threshold but at/above the 77% clear threshold.
+    setDiskUsage(DISK_PRESSURE_WARNING_CLEAR_THRESHOLD_PERCENT + 1);
+    expect(evaluateDiskPressureNow().state).toBe("warning");
+  });
+
+  test("clears the warning state once usage falls below the warning clear threshold", () => {
+    setDiskUsage(DISK_PRESSURE_WARNING_THRESHOLD_PERCENT + 2);
+    expect(evaluateDiskPressureNow().state).toBe("warning");
+
+    setDiskUsage(DISK_PRESSURE_WARNING_CLEAR_THRESHOLD_PERCENT - 1);
+    expect(evaluateDiskPressureNow().state).toBe("ok");
+  });
+
+  test("steps a critical lock down into a held warning state", () => {
+    setDiskUsage(DISK_PRESSURE_THRESHOLD_PERCENT + 1);
+    expect(evaluateDiskPressureNow().state).toBe("critical");
+
+    // Below the 90% critical clear but above the 80% warning threshold.
+    setDiskUsage(DISK_PRESSURE_CLEAR_THRESHOLD_PERCENT - 2);
+    const stepped = evaluateDiskPressureNow();
+    expect(stepped.state).toBe("warning");
+    expect(stepped.locked).toBe(false);
+
+    // Now within the warning clear deadband — warning must hold, not flap to ok.
+    setDiskUsage(DISK_PRESSURE_WARNING_CLEAR_THRESHOLD_PERCENT + 1);
+    expect(evaluateDiskPressureNow().state).toBe("warning");
+  });
+
+  test("holds warning when a critical lock drops straight into the warning deadband", () => {
+    setDiskUsage(DISK_PRESSURE_THRESHOLD_PERCENT + 1);
+    expect(evaluateDiskPressureNow().state).toBe("critical");
+
+    // A single large cleanup drops usage directly from critical to below the
+    // 80% warning threshold but still at/above the 77% clear threshold. The
+    // deadband must apply when stepping down out of critical too, so this holds
+    // as warning rather than flapping to ok (which would reopen the flap window).
+    setDiskUsage(DISK_PRESSURE_WARNING_CLEAR_THRESHOLD_PERCENT + 1);
+    const stepped = evaluateDiskPressureNow();
+    expect(stepped.state).toBe("warning");
+    expect(stepped.locked).toBe(false);
+  });
+
+  test("clears straight to ok when a critical lock drops below the warning clear threshold", () => {
+    setDiskUsage(DISK_PRESSURE_THRESHOLD_PERCENT + 1);
+    expect(evaluateDiskPressureNow().state).toBe("critical");
+
+    // A drop below even the warning-clear threshold is a genuine recovery.
+    setDiskUsage(DISK_PRESSURE_WARNING_CLEAR_THRESHOLD_PERCENT - 1);
+    expect(evaluateDiskPressureNow().state).toBe("ok");
+  });
 });

package/src/__tests__/disk-pressure-routes.test.ts

@@ -49,10 +49,17 @@ const {
   evaluateDiskPressureNow,
 } = await import("../daemon/disk-pressure-guard.js");
 const { assistantEventHub } = await import("../runtime/assistant-event-hub.js");
-const { getPolicy } = await import("../runtime/auth/route-policy.js");
 const { RouteError } = await import("../runtime/routes/errors.js");
 const { ROUTES } = await import("../runtime/routes/disk-pressure-routes.js");
 
+/** Look up a route's policy by endpoint+method on the module's ROUTES. */
+function routePolicy(endpoint: string, method?: string) {
+  const route = ROUTES.find(
+    (r) => r.endpoint === endpoint && (!method || r.method === method),
+  );
+  return route?.policy ?? null;
+}
+
 type DiskPressureRouteResult = {
   status: {
     enabled: boolean;
@@ -152,7 +159,7 @@ describe("disk pressure routes", () => {
           (route) => route.endpoint === endpoint && route.method === method,
         ),
       ).toBe(true);
-      expect(getPolicy(endpoint)).toBeDefined();
+      expect(routePolicy(endpoint)).not.toBeNull();
     }
   });
 

package/src/__tests__/dm-persistence.test.ts

@@ -34,9 +34,14 @@ mock.module("../memory/conversation-crud.js", () => ({
     conversationId: string,
     role: string,
     content: string,
-    metadata?: Record<string, unknown>,
+    options?: { metadata?: Record<string, unknown> },
   ) => {
-    addMessageCalls.push({ conversationId, role, content, metadata });
+    addMessageCalls.push({
+      conversationId,
+      role,
+      content,
+      metadata: options?.metadata,
+    });
     return { id: `persisted-${addMessageCalls.length}` };
   },
   getConversation: () => null,

package/src/__tests__/dynamic-page-surface.test.ts

@@ -57,6 +57,74 @@ describe("Tool definition includes dynamic_page", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Tool execution guard
+// ---------------------------------------------------------------------------
+
+describe("ui_show dynamic_page app substitute guard", () => {
+  test("rejects dynamic_page when the model labels it as an app build", async () => {
+    let proxied = false;
+
+    const result = await uiShowTool.execute(
+      {
+        surface_type: "dynamic_page",
+        title: "JARVIS 1020 Test Counter",
+        activity: "Building the JARVIS 1020 Test Counter app",
+        data: {
+          html: "<button>Increment</button>",
+          preview: {
+            title: "JARVIS 1020 Test Counter",
+            subtitle: "Click INCREMENT to count up",
+          },
+        },
+      },
+      {
+        conversationId: "conversation-123",
+        workingDir: "/tmp",
+        trustClass: "guardian",
+        proxyToolResolver: async () => {
+          proxied = true;
+          return { content: "proxied", isError: false };
+        },
+      },
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('skill: "app-builder"');
+    expect(proxied).toBe(false);
+  });
+
+  test("allows transient non-app dynamic_page surfaces", async () => {
+    let proxied = false;
+
+    const result = await uiShowTool.execute(
+      {
+        surface_type: "dynamic_page",
+        title: "My Slides",
+        data: {
+          html: "<h1>Hello</h1>",
+          preview: {
+            title: "Slides",
+            subtitle: "3 slides about Apple",
+          },
+        },
+      },
+      {
+        conversationId: "conversation-123",
+        workingDir: "/tmp",
+        trustClass: "guardian",
+        proxyToolResolver: async () => {
+          proxied = true;
+          return { content: "proxied", isError: false };
+        },
+      },
+    );
+
+    expect(result).toEqual({ content: "proxied", isError: false });
+    expect(proxied).toBe(true);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // UiSurfaceShowDynamicPage structure
 // ---------------------------------------------------------------------------

package/src/__tests__/edit-propagation.test.ts

@@ -76,8 +76,7 @@ async function seedSlackMessage(opts: {
     inboundResult.conversationId,
     "user",
     initialContent,
-    { userMessageChannel: "slack" },
-    { skipIndexing: true },
+    { metadata: { userMessageChannel: "slack" }, skipIndexing: true },
   );
 
   linkMessage(inboundResult.eventId, inserted.id);

package/src/__tests__/empty-response-pipeline.test.ts

@@ -19,10 +19,8 @@
 import { beforeEach, describe, expect, test } from "bun:test";
 
 import type { TrustContext } from "../daemon/trust-context.js";
-import {
-  defaultEmptyResponsePlugin,
-  defaultEmptyResponseTerminal,
-} from "../plugins/defaults/empty-response.js";
+import { defaultEmptyResponsePlugin } from "../plugins/defaults/empty-response/register.js";
+import { defaultEmptyResponseTerminal } from "../plugins/defaults/empty-response/terminal.js";
 import { DEFAULT_TIMEOUTS, runPipeline } from "../plugins/pipeline.js";
 import {
   getMiddlewaresFor,
@@ -73,10 +71,21 @@ function makeArgs(
     emptyResponseRetries: 0,
     maxEmptyResponseRetries: 1,
     priorAssistantHadVisibleText: false,
+    // Default to `null` (no stop reason reported) so existing fixtures
+    // exercise the "organic empty turn" path. The refusal branch
+    // dedicated tests below set this to `"refusal"` explicitly.
+    stopReason: null,
     ...overrides,
   };
 }
 
+/**
+ * Refusal-specific nudge text — keep in sync with `register.ts`. Clients
+ * (and the model) may match on this exact text.
+ */
+const CANONICAL_REFUSAL_NUDGE_TEXT =
+  '<system_notice>Your previous response was empty because the upstream provider returned stop_reason="refusal". Please answer the user\'s last message directly with a plain-text response. Do not use any tools — just respond with text.</system_notice>';
+
 async function runEmpty(
   args: EmptyResponseArgs,
 ): Promise<EmptyResponseDecision> {
@@ -167,15 +176,128 @@ describe("emptyResponse pipeline — default decisions", () => {
 
   test("no prior tool-use turn (toolUseTurns === 0) → accept", async () => {
     // Empty first assistant response with no tools is not the pattern the
-    // nudge guards against. Default accepts.
+    // organic-empty-turn nudge guards against. Default accepts (unless the
+    // stop reason is `"refusal"` — see the refusal-specific tests below).
+    const decision = await runEmpty(
+      makeArgs({
+        responseContent: [],
+        toolUseTurns: 0,
+      }),
+    );
+    expect(decision.action).toBe("accept");
+  });
+
+  // ─── Refusal stop ────────────────────────────────────────────────────────
+
+  test("stopReason='refusal' on turn 0 with no content → nudge with refusal text", async () => {
+    // The canonical failure mode this branch exists to catch: Anthropic's
+    // safety classifier zeros the response on the very first model call,
+    // returning a single thinking block and `stopReason: "refusal"`. Without
+    // this branch, the terminal would `accept` and the loop would persist
+    // an empty assistant bubble to the user.
+    const decision = await runEmpty(
+      makeArgs({
+        stopReason: "refusal",
+        responseContent: [],
+        toolUseBlocksLength: 0,
+        toolUseTurns: 0,
+        emptyResponseRetries: 0,
+        priorAssistantHadVisibleText: false,
+      }),
+    );
+    expect(decision.action).toBe("nudge");
+    expect(decision.nudgeText).toBe(CANONICAL_REFUSAL_NUDGE_TEXT);
+  });
+
+  test("stopReason='refusal' with a thinking-only block still nudges", async () => {
+    // Thinking blocks aren't visible text — the user sees nothing. A
+    // refusal with only thinking content matches the same shape the
+    // production log captured (`contentBlocks: 1, toolUseCount: 0`).
+    const decision = await runEmpty(
+      makeArgs({
+        stopReason: "refusal",
+        responseContent: [
+          {
+            type: "thinking",
+            thinking: "...",
+            signature: "sig",
+          } as ContentBlock,
+        ],
+        toolUseBlocksLength: 0,
+        toolUseTurns: 0,
+      }),
+    );
+    expect(decision.action).toBe("nudge");
+    expect(decision.nudgeText).toBe(CANONICAL_REFUSAL_NUDGE_TEXT);
+  });
+
+  test("stopReason='refusal' but visible text present → accept (model recovered)", async () => {
+    // The classifier can flag a partial response; if the model already
+    // delivered some visible text before refusing, the user has something
+    // to see. Accept.
+    const decision = await runEmpty(
+      makeArgs({
+        stopReason: "refusal",
+        responseContent: [{ type: "text", text: "partial answer" }],
+      }),
+    );
+    expect(decision.action).toBe("accept");
+  });
+
+  test("stopReason='refusal' but tool_use blocks present → accept", async () => {
+    // A refusal with tool_use blocks is unusual (the model wouldn't normally
+    // issue tools after a classifier hit) but we still shouldn't nudge —
+    // the loop will execute the tools and the model will get another shot.
     const decision = await runEmpty(
       makeArgs({
+        stopReason: "refusal",
+        responseContent: [
+          {
+            type: "tool_use",
+            id: "tu-1",
+            name: "read",
+            input: { path: "/tmp/x" },
+          } as ContentBlock,
+        ],
+        toolUseBlocksLength: 1,
+      }),
+    );
+    expect(decision.action).toBe("accept");
+  });
+
+  test("stopReason='refusal' but retries exhausted → accept (no infinite loop)", async () => {
+    // Persistent classifier hit shouldn't burn turns indefinitely. Once
+    // we've used our retry budget, accept (the user will see an empty
+    // bubble, but the loop terminates).
+    const decision = await runEmpty(
+      makeArgs({
+        stopReason: "refusal",
         responseContent: [],
         toolUseTurns: 0,
+        emptyResponseRetries: 1,
+        maxEmptyResponseRetries: 1,
       }),
     );
     expect(decision.action).toBe("accept");
   });
+
+  test("stopReason='refusal' beats post-tool-empty nudge text (refusal-specific wording)", async () => {
+    // When both branches would fire, refusal wins because the refusal
+    // text is more accurate ("safety classifier zeroed the response"
+    // vs. "summary of what you found or did"). This guards against a
+    // future refactor that orders the branches differently.
+    const decision = await runEmpty(
+      makeArgs({
+        stopReason: "refusal",
+        responseContent: [],
+        toolUseBlocksLength: 0,
+        toolUseTurns: 2, // would trip the post-tool branch too
+        priorAssistantHadVisibleText: false,
+      }),
+    );
+    expect(decision.action).toBe("nudge");
+    expect(decision.nudgeText).toBe(CANONICAL_REFUSAL_NUDGE_TEXT);
+  });
 });
 
 describe("emptyResponse pipeline — custom middleware overrides", () => {

package/src/__tests__/filing-service.test.ts

@@ -155,7 +155,7 @@ describe("FilingService", () => {
         conversationId: args[0] as string,
         content: args[1] as string,
         options:
-          (args[3] as { speed?: string; callSite?: string } | undefined) ??
+          (args[2] as { speed?: string; callSite?: string } | undefined) ??
           undefined,
       });
       return { messageId: "msg-1" };
@@ -319,7 +319,7 @@ describe("FilingService", () => {
       let compactionCalls = 0;
 
       setTestProcessMessage((...args: unknown[]) => {
-        const callSite = (args[3] as { callSite?: string } | undefined)
+        const callSite = (args[2] as { callSite?: string } | undefined)
           ?.callSite;
         if (callSite === "filingAgent") {
           filingCalls += 1;

package/src/__tests__/first-greeting.test.ts

@@ -8,6 +8,7 @@ const {
   isWakeUpGreeting,
   getCannedFirstGreeting,
   buildScanFirstMessage,
+  buildSelfIntroMessage,
   CANNED_FIRST_GREETING,
 } = await import("../daemon/first-greeting.js");
 import type { OnboardingGreetingContext } from "../daemon/first-greeting.js";
@@ -96,7 +97,7 @@ describe("first-greeting", () => {
         assistantName: "Pax",
       });
       expect(greeting).toBe(
-        "Hey Alice, I'm Pax.\n\nWe can get into whatever you've got, or just talk first — that tends to go better. Up to you. If you have context or workflows from another assistant or harness, bring them over early and I'll help port them.",
+        "Hey Alice, I'm Pax.\n\nWe can get into whatever you've got, or just talk first — that tends to go better. Up to you. And you don't have to start me from scratch — if you've built up a ChatGPT or Claude, bring it over and I'll learn from it fast. Best head start you can give me.",
       );
     });
 
@@ -108,7 +109,7 @@ describe("first-greeting", () => {
         assistantName: "Remy",
       });
       expect(greeting).toBe(
-        "Hey Alice, I'm Remy. Good to meet you.\n\nWe can start on something specific, or just talk for a bit first — honestly that tends to work out better. Either way, I'm here. If you have context or workflows from another assistant or harness, bring them over early and I can help port them.",
+        "Hey Alice, I'm Remy. Good to meet you.\n\nWe can start on something specific, or just talk for a bit first — honestly that tends to work out better. Either way, I'm here. And you don't have to start me from scratch — if there's a ChatGPT or Claude that already knows you, bring it over and I'll get up to speed fast. Honestly, it's the best head start you could give me.",
       );
     });
 
@@ -119,7 +120,7 @@ describe("first-greeting", () => {
         assistantName: "Pax",
       });
       expect(greeting).toBe(
-        "Hey, I'm Pax. Let's see what you've got.\n\nWe can jump straight into whatever you've got, or take a few minutes to just talk first. If you've got context or workflows from another assistant or harness, bring them over early and I'll port them with you. What sounds right?",
+        "Hey, I'm Pax. Let's see what you've got.\n\nWe can jump straight into whatever you've got, or take a few minutes to just talk first. And you don't have to start me from scratch — if you've built up a ChatGPT or Claude, bring it over and I'll get up to speed fast. Best head start you can give me — want to start there?",
       );
     });
 
@@ -131,7 +132,7 @@ describe("first-greeting", () => {
         assistantName: "Pax",
       });
       expect(greeting).toBe(
-        "Hey Alice, I'm Pax.\n\nWe can start with whatever's in front of you, or just talk for a bit first. Either way. If there's old context or workflows from another assistant or harness, bring them over early and I'll help port them.",
+        "Hey Alice, I'm Pax.\n\nWe can start with whatever's in front of you, or just talk for a bit first. Either way. And you don't have to start me from nothing — if there's a ChatGPT or Claude that already knows you, bring it over and I'll learn from it. The best head start you could give me.",
       );
     });
 
@@ -142,7 +143,7 @@ describe("first-greeting", () => {
         userName: "Alice",
       });
       expect(greeting).toBe(
-        "Hey Alice,\n\nWe can get into whatever you've got, or just talk first — that tends to go better. Up to you. If you have context or workflows from another assistant or harness, bring them over early and I'll help port them.",
+        "Hey Alice,\n\nWe can get into whatever you've got, or just talk first — that tends to go better. Up to you. And you don't have to start me from scratch — if you've built up a ChatGPT or Claude, bring it over and I'll learn from it fast. Best head start you can give me.",
       );
     });
 
@@ -153,7 +154,7 @@ describe("first-greeting", () => {
         assistantName: "Pax",
       });
       expect(greeting).toBe(
-        "Hey, I'm Pax.\n\nWe can get into whatever you've got, or just talk first — that tends to go better. Up to you. If you have context or workflows from another assistant or harness, bring them over early and I'll help port them.",
+        "Hey, I'm Pax.\n\nWe can get into whatever you've got, or just talk first — that tends to go better. Up to you. And you don't have to start me from scratch — if you've built up a ChatGPT or Claude, bring it over and I'll learn from it fast. Best head start you can give me.",
       );
     });
 
@@ -173,7 +174,7 @@ describe("first-greeting", () => {
         tone: "warm",
       });
       expect(greeting).toBe(
-        "Hey,\n\nWe can start on something specific, or just talk for a bit first — honestly that tends to work out better. Either way, I'm here. If you have context or workflows from another assistant or harness, bring them over early and I can help port them.",
+        "Hey,\n\nWe can start on something specific, or just talk for a bit first — honestly that tends to work out better. Either way, I'm here. And you don't have to start me from scratch — if there's a ChatGPT or Claude that already knows you, bring it over and I'll get up to speed fast. Honestly, it's the best head start you could give me.",
       );
     });
 
@@ -204,7 +205,7 @@ describe("first-greeting", () => {
         assistantName: "Pax",
       });
       expect(greeting).toBe(
-        "Hey Alice, I'm Pax.\n\nWe can get into whatever you've got, or just talk first — that tends to go better. Up to you. If you have context or workflows from another assistant or harness, bring them over early and I'll help port them.",
+        "Hey Alice, I'm Pax.\n\nWe can get into whatever you've got, or just talk first — that tends to go better. Up to you. And you don't have to start me from scratch — if you've built up a ChatGPT or Claude, bring it over and I'll learn from it fast. Best head start you can give me.",
       );
     });
 
@@ -234,7 +235,7 @@ describe("first-greeting", () => {
       const [intro, invite] = greeting.split("\n\n");
       expect(intro).toBe("Hey Bob, I'm Pax.");
       expect(invite).toBe(
-        "We can get into whatever you've got, or just talk first — that tends to go better. Up to you. If you have context or workflows from another assistant or harness, bring them over early and I'll help port them.",
+        "We can get into whatever you've got, or just talk first — that tends to go better. Up to you. And you don't have to start me from scratch — if you've built up a ChatGPT or Claude, bring it over and I'll learn from it fast. Best head start you can give me.",
       );
     });
 
@@ -243,7 +244,7 @@ describe("first-greeting", () => {
       const [intro, invite] = greeting.split("\n\n");
       expect(intro).toBe("Hey Bob, I'm Pax. Good to meet you.");
       expect(invite).toBe(
-        "We can start on something specific, or just talk for a bit first — honestly that tends to work out better. Either way, I'm here. If you have context or workflows from another assistant or harness, bring them over early and I can help port them.",
+        "We can start on something specific, or just talk for a bit first — honestly that tends to work out better. Either way, I'm here. And you don't have to start me from scratch — if there's a ChatGPT or Claude that already knows you, bring it over and I'll get up to speed fast. Honestly, it's the best head start you could give me.",
       );
     });
 
@@ -252,7 +253,7 @@ describe("first-greeting", () => {
       const [intro, invite] = greeting.split("\n\n");
       expect(intro).toBe("Hey Bob, I'm Pax. Let's see what you've got.");
       expect(invite).toBe(
-        "We can jump straight into whatever you've got, or take a few minutes to just talk first. If you've got context or workflows from another assistant or harness, bring them over early and I'll port them with you. What sounds right?",
+        "We can jump straight into whatever you've got, or take a few minutes to just talk first. And you don't have to start me from scratch — if you've built up a ChatGPT or Claude, bring it over and I'll get up to speed fast. Best head start you can give me — want to start there?",
       );
     });
 
@@ -261,7 +262,7 @@ describe("first-greeting", () => {
       const [intro, invite] = greeting.split("\n\n");
       expect(intro).toBe("Hey Bob, I'm Pax.");
       expect(invite).toBe(
-        "We can start with whatever's in front of you, or just talk for a bit first. Either way. If there's old context or workflows from another assistant or harness, bring them over early and I'll help port them.",
+        "We can start with whatever's in front of you, or just talk for a bit first. Either way. And you don't have to start me from nothing — if there's a ChatGPT or Claude that already knows you, bring it over and I'll learn from it. The best head start you could give me.",
       );
     });
 
@@ -286,7 +287,7 @@ describe("first-greeting", () => {
   });
 
   describe("migration offer is present in every variant", () => {
-    const MIGRATION_MARKER = "bring them over early";
+    const MIGRATION_MARKER = "head start";
 
     it("no-onboarding greeting includes the migration offer", () => {
       expect(getCannedFirstGreeting(undefined)).toContain(MIGRATION_MARKER);
@@ -309,7 +310,7 @@ describe("first-greeting", () => {
           assistantName: "Pax",
         });
         expect(greeting).toContain(MIGRATION_MARKER);
-        expect(greeting).toContain("port them");
+        expect(greeting).toContain("ChatGPT or Claude");
       }
     });
 
@@ -375,4 +376,44 @@ describe("first-greeting", () => {
       expect(greeting).not.toContain("personal");
     });
   });
+
+  describe("buildSelfIntroMessage", () => {
+    const ctx = (
+      over: Partial<OnboardingGreetingContext> = {},
+    ): OnboardingGreetingContext => ({
+      tools: [],
+      tasks: [],
+      tone: "grounded",
+      ...over,
+    });
+
+    it("uses both names when present", () => {
+      expect(
+        buildSelfIntroMessage(ctx({ assistantName: "Vela", userName: "alex" })),
+      ).toBe("Hi Vela, I'm alex. Nice to meet you.");
+    });
+
+    it("drops the missing user name", () => {
+      expect(buildSelfIntroMessage(ctx({ assistantName: "Vela" }))).toBe(
+        "Hi Vela. Nice to meet you.",
+      );
+    });
+
+    it("drops the missing assistant name", () => {
+      expect(buildSelfIntroMessage(ctx({ userName: "alex" }))).toBe(
+        "Hi, I'm alex. Nice to meet you.",
+      );
+    });
+
+    it("treats whitespace-only names as missing", () => {
+      expect(
+        buildSelfIntroMessage(ctx({ assistantName: "  ", userName: "  " })),
+      ).toBeUndefined();
+    });
+
+    it("returns undefined when neither name is known (caller keeps canned greeting)", () => {
+      expect(buildSelfIntroMessage(ctx())).toBeUndefined();
+      expect(buildSelfIntroMessage(undefined)).toBeUndefined();
+    });
+  });
 });

package/src/__tests__/gemini-inline-media.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  base64ByteLength,
+  estimateGeminiAudioTokens,
+  GEMINI_MAX_INLINE_AUDIO_BYTES,
+  normalizeGeminiAudioMime,
+} from "../providers/gemini/inline-media.js";
+
+describe("normalizeGeminiAudioMime", () => {
+  test("maps audio/mpeg onto Gemini's audio/mp3 spelling", () => {
+    expect(normalizeGeminiAudioMime("audio/mpeg")).toBe("audio/mp3");
+  });
+
+  test("passes supported audio types through unchanged", () => {
+    for (const mime of [
+      "audio/wav",
+      "audio/mp3",
+      "audio/aiff",
+      "audio/aac",
+      "audio/ogg",
+      "audio/flac",
+    ]) {
+      expect(normalizeGeminiAudioMime(mime)).toBe(mime);
+    }
+  });
+
+  test("is case-insensitive and strips parameters", () => {
+    expect(normalizeGeminiAudioMime("AUDIO/MPEG")).toBe("audio/mp3");
+    expect(normalizeGeminiAudioMime("audio/ogg; codecs=opus")).toBe(
+      "audio/ogg",
+    );
+  });
+
+  test("returns null for types Gemini cannot take inline", () => {
+    for (const mime of [
+      "audio/x-m4a",
+      "audio/mp4",
+      "audio/opus",
+      "application/pdf",
+      "image/png",
+      "",
+    ]) {
+      expect(normalizeGeminiAudioMime(mime)).toBeNull();
+    }
+  });
+});
+
+describe("base64ByteLength", () => {
+  test("approximates raw bytes from base64 length", () => {
+    // 8 base64 chars → 6 raw bytes
+    expect(base64ByteLength("QUJDREVG")).toBe(6);
+    expect(base64ByteLength("")).toBe(0);
+  });
+});
+
+describe("estimateGeminiAudioTokens", () => {
+  test("scales with payload size and stays far below the base64-as-text count", () => {
+    // ~3 MB of base64 ≈ ~2.25 MB raw ≈ ~140s at 16 KB/s ≈ ~4.5k tokens.
+    const data = "A".repeat(3 * 1024 * 1024);
+    const tokens = estimateGeminiAudioTokens(data);
+    expect(tokens).toBeGreaterThan(1_000);
+    // Must be a small fraction of the naive base64-length/4 estimate (~786k).
+    expect(tokens).toBeLessThan(data.length / 40);
+  });
+
+  test("returns zero for empty data", () => {
+    expect(estimateGeminiAudioTokens("")).toBe(0);
+  });
+});
+
+test("inline audio cap leaves headroom under Gemini's 20 MB request limit", () => {
+  expect(GEMINI_MAX_INLINE_AUDIO_BYTES).toBe(12 * 1024 * 1024);
+  // Base64 of the cap (~16 MB) must stay under the 20 MB wire limit.
+  expect(GEMINI_MAX_INLINE_AUDIO_BYTES * (4 / 3)).toBeLessThan(
+    20 * 1024 * 1024,
+  );
+});