@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/__tests__/tool-approval-seed-content-blocks.test.ts

@@ -9,7 +9,7 @@ describe("buildToolApprovalSeedContentBlocks", () => {
     requestKind: "tool_approval",
     toolName: "bash",
     questionText:
-      'Bob wants to use "bash": mkdir -p scratch && assistant credentials reveal --service slack',
+      "Approve tool: bash — mkdir -p scratch && assistant credentials reveal --service slack (requested by Bob)",
     sourceChannel: "slack",
     requesterIdentifier: "Bob",
   };
@@ -19,7 +19,8 @@ describe("buildToolApprovalSeedContentBlocks", () => {
     requestCode: "GHI012",
     requestKind: "tool_grant_request",
     toolName: "web_search",
-    questionText: 'Alice wants to use "web_search": search for latest news',
+    questionText:
+      "Approve tool: web_search — search for latest news (requested by Alice)",
     sourceChannel: "telegram",
     requesterIdentifier: "Alice",
   };
@@ -29,7 +30,7 @@ describe("buildToolApprovalSeedContentBlocks", () => {
     requestCode: "VOICE1",
     requestKind: "pending_question",
     toolName: "bash",
-    questionText: 'Bob wants to use "bash": echo hello',
+    questionText: "Approve tool: bash — echo hello (requested by Bob)",
     sourceChannel: "phone",
     requesterIdentifier: "Bob",
   };
@@ -54,9 +55,9 @@ describe("buildToolApprovalSeedContentBlocks", () => {
     expect(surface.surfaceType).toBe("card");
     expect(surface.surfaceId).toBe("tool-approval-req-voice-101");
     const data = surface.data as Record<string, unknown>;
-    expect(data.subtitle).toBe("Requesting approval to run this tool");
+    expect(data.subtitle).toBe("Requires your approval to run");
     const metadata = data.metadata as Array<{ label: string; value: string }>;
-    expect(metadata).toContainEqual({ label: "Tool", value: "bash" });
+    expect(metadata).toContainEqual({ label: "Requested by", value: "Bob" });
     expect(metadata).toContainEqual({ label: "Source", value: "phone" });
   });
 
@@ -95,26 +96,50 @@ describe("buildToolApprovalSeedContentBlocks", () => {
     expect(surface.title).toBe("Tool Grant Request");
   });
 
-  test("card data uses requesterIdentifier as title", () => {
+  test("card data uses the tool name as title — the decision is about the tool", () => {
+    const blocks = buildToolApprovalSeedContentBlocks(toolApprovalPayload)!;
+    const data = (blocks[0] as Record<string, unknown>).data as Record<
+      string,
+      unknown
+    >;
+    expect(data.title).toBe("bash");
+  });
+
+  test("requester appears only as metadata context, not as the card title", () => {
     const blocks = buildToolApprovalSeedContentBlocks(toolApprovalPayload)!;
     const data = (blocks[0] as Record<string, unknown>).data as Record<
       string,
       unknown
     >;
-    expect(data.title).toBe("Bob");
+    expect(data.title).not.toBe("Bob");
+    const metadata = data.metadata as Array<{ label: string; value: string }>;
+    expect(metadata).toContainEqual({ label: "Requested by", value: "Bob" });
   });
 
-  test("card data falls back to 'Someone' when no requesterIdentifier", () => {
+  test("shows Requested by: Unknown when no requesterIdentifier", () => {
     const payload = { ...toolApprovalPayload, requesterIdentifier: undefined };
     const blocks = buildToolApprovalSeedContentBlocks(payload)!;
     const data = (blocks[0] as Record<string, unknown>).data as Record<
       string,
       unknown
     >;
-    expect(data.title).toBe("Someone");
+    expect(data.title).toBe("bash");
+    const metadata = data.metadata as Array<{ label: string; value: string }>;
+    expect(metadata).toContainEqual({
+      label: "Requested by",
+      value: "Unknown",
+    });
+
+    // The plain-text fallback carries the same placeholder.
+    const noQuestion = { ...payload, questionText: undefined };
+    const fallbackBlocks = buildToolApprovalSeedContentBlocks(noQuestion)!;
+    const textBlock = fallbackBlocks[1] as Record<string, unknown>;
+    expect(textBlock.text).toContain(
+      "Approve tool: bash (requested by Unknown)",
+    );
   });
 
-  test("card subtitle differs for tool_approval vs tool_grant_request", () => {
+  test("card subtitle is tool-framed for both tool_approval and tool_grant_request", () => {
     const approvalBlocks =
       buildToolApprovalSeedContentBlocks(toolApprovalPayload)!;
     const grantBlocks = buildToolApprovalSeedContentBlocks(toolGrantPayload)!;
@@ -122,18 +147,18 @@ describe("buildToolApprovalSeedContentBlocks", () => {
       .data as Record<string, unknown>;
     const grantData = (grantBlocks[0] as Record<string, unknown>)
       .data as Record<string, unknown>;
-    expect(approvalData.subtitle).toBe("Requesting approval to run this tool");
-    expect(grantData.subtitle).toBe("Requesting permission to use this tool");
+    expect(approvalData.subtitle).toBe("Requires your approval to run");
+    expect(grantData.subtitle).toBe("Requires your approval to run");
   });
 
-  test("includes tool name and source channel in metadata", () => {
+  test("includes requester and source channel in metadata", () => {
     const blocks = buildToolApprovalSeedContentBlocks(toolApprovalPayload)!;
     const data = (blocks[0] as Record<string, unknown>).data as Record<
       string,
       unknown
     >;
     const metadata = data.metadata as Array<{ label: string; value: string }>;
-    expect(metadata).toContainEqual({ label: "Tool", value: "bash" });
+    expect(metadata).toContainEqual({ label: "Requested by", value: "Bob" });
     expect(metadata).toContainEqual({ label: "Source", value: "slack" });
   });
 
@@ -143,8 +168,8 @@ describe("buildToolApprovalSeedContentBlocks", () => {
       string,
       unknown
     >;
-    expect(data.body).toContain("Bob wants to use");
-    expect(data.body).toContain("bash");
+    expect(data.body).toContain("Approve tool: bash");
+    expect(data.body).toContain("requested by Bob");
   });
 
   test("body shows fallback when no questionText", () => {
@@ -189,7 +214,7 @@ describe("buildToolApprovalSeedContentBlocks", () => {
     const blocks = buildToolApprovalSeedContentBlocks(toolApprovalPayload)!;
     const textBlock = blocks[1] as Record<string, unknown>;
     expect(textBlock.type).toBe("text");
-    expect(textBlock.text).toContain("Bob wants to use");
+    expect(textBlock.text).toContain("Approve tool: bash");
     expect(textBlock.text).toContain("XYZ789");
     expect(textBlock.text).toContain("approve");
   });
@@ -198,14 +223,14 @@ describe("buildToolApprovalSeedContentBlocks", () => {
     const payload = { ...toolApprovalPayload, requestCode: undefined };
     const blocks = buildToolApprovalSeedContentBlocks(payload)!;
     const textBlock = blocks[1] as Record<string, unknown>;
-    expect(textBlock.text).toContain("Bob wants to use");
+    expect(textBlock.text).toContain("Approve tool: bash");
     expect(textBlock.text).not.toContain("XYZ789");
   });
 
-  test("text fallback block uses generic text when no questionText", () => {
+  test("text fallback block uses tool-framed generic text when no questionText", () => {
     const payload = { ...toolApprovalPayload, questionText: undefined };
     const blocks = buildToolApprovalSeedContentBlocks(payload)!;
     const textBlock = blocks[1] as Record<string, unknown>;
-    expect(textBlock.text).toContain("requesting approval to use bash");
+    expect(textBlock.text).toContain("Approve tool: bash (requested by Bob)");
   });
 });

package/src/__tests__/tool-grant-request-escalation.test.ts

@@ -195,6 +195,45 @@ describe("ToolApprovalHandler / grant-miss escalation", () => {
     deliveredReplies.length = 0;
   });
 
+  test("escalation copy is tool-framed — identity appears only as context", async () => {
+    const context = makeContext({
+      trustClass: "trusted_contact",
+      requesterDisplayName: "Bob",
+    });
+    const result = await handler.checkPreExecutionGates(
+      "bash",
+      { command: "ls -la" },
+      context,
+      "host",
+      "high",
+      Date.now(),
+      emitLifecycleEvent,
+    );
+
+    // Trusted contact with a guardian binding: an escalation request is
+    // created, the short inline wait times out, and the invocation is denied.
+    expect(result.allowed).toBe(false);
+    if (result.allowed) {
+      return;
+    }
+
+    // The guardian-facing question asks about the tool, never about the person.
+    expect(emittedSignals.length).toBe(1);
+    const payload = emittedSignals[0].contextPayload as Record<string, unknown>;
+    const questionText = payload.questionText as string;
+    expect(questionText.startsWith("Approve tool: bash")).toBe(true);
+    // Requester identity is context, not the subject of the question.
+    expect(questionText).toContain("(requested by Bob)");
+    expect(questionText).not.toMatch(/wants to use/i);
+    expect(questionText).not.toMatch(/is requesting/i);
+
+    // Denial copy is about the tool, not about actor identity.
+    expect(result.result.content).toContain(`Permission denied for "bash"`);
+    expect(result.result.content).toContain("guardian approval");
+    expect(result.result.content).not.toMatch(/actor/i);
+    expect(result.result.content).not.toMatch(/not the guardian/i);
+  });
+
   test("unverified_channel does NOT create escalation request", async () => {
     const toolName = "bash";
     const input = { command: "ls" };

package/src/__tests__/trust-context-guards.test.ts

@@ -12,8 +12,9 @@ import { describe, expect, it } from "bun:test";
  *      (optional string), NOT `string | null`.
  *  (b) trustClass in ToolContext must be a required field (no `?`).
  *  (c) The channel retry sweep parser must not reference `actorRole`.
- *  (d) guardianPrincipalId in GuardianBinding must be `string` (non-null,
- *      non-optional).
+ *  (d) guardianPrincipalId in GuardianBinding must be `string | null` —
+ *      a gateway guardian row with no principal surfaces as UNRESOLVED
+ *      (null) and is never coerced to a present-but-empty "" (LUM-2665).
  */
 
 const srcDir = join(import.meta.dir, "..");
@@ -163,10 +164,11 @@ describe("trust-context guards", () => {
   });
 
   // -----------------------------------------------------------------------
-  // (e) guardianPrincipalId is non-null in GuardianBinding
+  // (d) guardianPrincipalId is nullable (unresolved-capable) in
+  //     GuardianBinding
   // -----------------------------------------------------------------------
 
-  it("guardianPrincipalId is typed as string (non-null) in GuardianBinding", () => {
+  it("guardianPrincipalId is typed as string | null in GuardianBinding, and reads never coerce null to ''", () => {
     const source = readFileSync(
       join(srcDir, "channels", "channel-verification-sessions.ts"),
       "utf-8",
@@ -197,18 +199,27 @@ describe("trust-context guards", () => {
       "Expected to find guardianPrincipalId in GuardianBinding",
     ).toBeDefined();
 
-    // Must be `guardianPrincipalId: string` — not optional, not nullable
+    // Must be `guardianPrincipalId: string | null` — a gateway guardian row
+    // with no principal is UNRESOLVED. Callers repair via the vellum anchor
+    // or fail closed; a plain `string` type invites `?? ""` coercion, which
+    // creates undecidable canonical requests (LUM-2665).
     expect(
       principalLine!.includes("string | null") ||
         principalLine!.includes("null | string"),
-      "guardianPrincipalId must not be typed as nullable in GuardianBinding. " +
+      "guardianPrincipalId must be typed `string | null` in GuardianBinding " +
+        "so a missing gateway principal surfaces as unresolved. " +
         `Found: "${principalLine!.trim()}"`,
-    ).toBe(false);
+    ).toBe(true);
 
+    // The synthesizing read must never mask a missing principal as "".
+    const serviceSource = readFileSync(
+      join(srcDir, "runtime", "channel-verification-service.ts"),
+      "utf-8",
+    );
     expect(
-      /guardianPrincipalId\s*\?/.test(principalLine!),
-      "guardianPrincipalId must not be optional in GuardianBinding. " +
-        `Found: "${principalLine!.trim()}"`,
+      serviceSource.includes('principalId ?? ""'),
+      "getGuardianBinding must not coerce a missing gateway principal to " +
+        '"" — surface null and let callers repair or fail closed.',
     ).toBe(false);
   });
 });

package/src/__tests__/trusted-contact-multichannel.test.ts

@@ -52,6 +52,10 @@ mock.module("../runtime/access-request-helper.js", () => ({
       requestId: `mock-req-${Date.now()}`,
     };
   },
+  // acl-enforcement imports this alongside notifyGuardianOfAccessRequest; stub
+  // it so the terminal-deny check never falls through to the real DB-backed
+  // helper in this mocked suite.
+  isAccessRequestDenied: () => false,
 }));
 
 const deliverReplyCalls: Array<{

package/src/__tests__/twilio-provider.test.ts

@@ -1,5 +1,5 @@
 /**
- * Tests for TwilioConversationRelayProvider — signature validation,
+ * Tests for TwilioVoiceProvider — signature validation,
  * fail-closed auth token behavior, and caller ID eligibility checks.
  */
 import { createHmac } from "node:crypto";
@@ -32,7 +32,7 @@ mock.module("../security/secure-keys.js", () => ({
   },
 }));
 
-import { TwilioConversationRelayProvider } from "../calls/twilio-provider.js";
+import { TwilioVoiceProvider } from "../calls/twilio-provider.js";
 
 // ── Helpers ────────────────────────────────────────────────────────────
 
@@ -51,7 +51,7 @@ function computeValidSignature(
 
 // ── Tests ──────────────────────────────────────────────────────────────
 
-describe("TwilioConversationRelayProvider", () => {
+describe("TwilioVoiceProvider", () => {
   beforeEach(() => {
     mockAuthToken = "test-auth-token-secret";
     mockAccountSid = "AC_test_account";
@@ -64,7 +64,7 @@ describe("TwilioConversationRelayProvider", () => {
     test("returns true for a valid signature", () => {
       const authToken = "test-auth-token-secret";
       const sig = computeValidSignature(testUrl, testParams, authToken);
-      const result = TwilioConversationRelayProvider.verifyWebhookSignature(
+      const result = TwilioVoiceProvider.verifyWebhookSignature(
         testUrl,
         testParams,
         sig,
@@ -75,7 +75,7 @@ describe("TwilioConversationRelayProvider", () => {
 
     test("returns false for an invalid signature", () => {
       const authToken = "test-auth-token-secret";
-      const result = TwilioConversationRelayProvider.verifyWebhookSignature(
+      const result = TwilioVoiceProvider.verifyWebhookSignature(
         testUrl,
         testParams,
         "invalid-signature-base64",
@@ -91,7 +91,7 @@ describe("TwilioConversationRelayProvider", () => {
         testParams,
         "wrong-token",
       );
-      const result = TwilioConversationRelayProvider.verifyWebhookSignature(
+      const result = TwilioVoiceProvider.verifyWebhookSignature(
         testUrl,
         testParams,
         wrongTokenSig,
@@ -103,7 +103,7 @@ describe("TwilioConversationRelayProvider", () => {
     test("handles empty params", () => {
       const authToken = "test-auth-token-secret";
       const sig = computeValidSignature(testUrl, {}, authToken);
-      const result = TwilioConversationRelayProvider.verifyWebhookSignature(
+      const result = TwilioVoiceProvider.verifyWebhookSignature(
         testUrl,
         {},
         sig,
@@ -116,7 +116,7 @@ describe("TwilioConversationRelayProvider", () => {
       const authToken = "test-auth-token-secret";
       const params = { Zebra: "1", Alpha: "2", Middle: "3" };
       const sig = computeValidSignature(testUrl, params, authToken);
-      const result = TwilioConversationRelayProvider.verifyWebhookSignature(
+      const result = TwilioVoiceProvider.verifyWebhookSignature(
         testUrl,
         params,
         sig,
@@ -129,20 +129,20 @@ describe("TwilioConversationRelayProvider", () => {
   describe("getAuthToken", () => {
     test("returns the auth token when configured", async () => {
       mockAuthToken = "my-secret-token";
-      const token = await TwilioConversationRelayProvider.getAuthToken();
+      const token = await TwilioVoiceProvider.getAuthToken();
       expect(token).toBe("my-secret-token");
     });
 
     test("returns null when auth token is not configured", async () => {
       mockAuthToken = undefined;
-      const token = await TwilioConversationRelayProvider.getAuthToken();
+      const token = await TwilioVoiceProvider.getAuthToken();
       expect(token).toBeNull();
     });
   });
 
   describe("initiateCall", () => {
     test("sends repeated StatusCallbackEvent parameters", async () => {
-      const provider = new TwilioConversationRelayProvider();
+      const provider = new TwilioVoiceProvider();
       const originalFetch = globalThis.fetch;
       let capturedBody = "";
 
@@ -191,7 +191,7 @@ describe("TwilioConversationRelayProvider", () => {
     });
 
     test("returns eligible when number is found in IncomingPhoneNumbers", async () => {
-      const provider = new TwilioConversationRelayProvider();
+      const provider = new TwilioVoiceProvider();
 
       globalThis.fetch = (async (url: RequestInfo | URL): Promise<Response> => {
         const urlStr = String(url);
@@ -217,7 +217,7 @@ describe("TwilioConversationRelayProvider", () => {
     });
 
     test("returns eligible when number is found in OutgoingCallerIds", async () => {
-      const provider = new TwilioConversationRelayProvider();
+      const provider = new TwilioVoiceProvider();
 
       globalThis.fetch = (async (url: RequestInfo | URL): Promise<Response> => {
         const urlStr = String(url);
@@ -245,7 +245,7 @@ describe("TwilioConversationRelayProvider", () => {
     });
 
     test("returns ineligible when number is not found in either endpoint", async () => {
-      const provider = new TwilioConversationRelayProvider();
+      const provider = new TwilioVoiceProvider();
 
       globalThis.fetch = (async (url: RequestInfo | URL): Promise<Response> => {
         const urlStr = String(url);
@@ -269,7 +269,7 @@ describe("TwilioConversationRelayProvider", () => {
     });
 
     test("throws when both API calls return non-ok responses", async () => {
-      const provider = new TwilioConversationRelayProvider();
+      const provider = new TwilioVoiceProvider();
 
       globalThis.fetch = (async (url: RequestInfo | URL): Promise<Response> => {
         const urlStr = String(url);
@@ -288,7 +288,7 @@ describe("TwilioConversationRelayProvider", () => {
     });
 
     test("throws when only one API call fails but the other succeeds with no match", async () => {
-      const provider = new TwilioConversationRelayProvider();
+      const provider = new TwilioVoiceProvider();
 
       globalThis.fetch = (async (url: RequestInfo | URL): Promise<Response> => {
         const urlStr = String(url);
@@ -309,7 +309,7 @@ describe("TwilioConversationRelayProvider", () => {
     });
 
     test("passes correct phone number as query parameter", async () => {
-      const provider = new TwilioConversationRelayProvider();
+      const provider = new TwilioVoiceProvider();
       const capturedUrls: string[] = [];
 
       globalThis.fetch = (async (url: RequestInfo | URL): Promise<Response> => {