@vellumai/assistant 0.9.0-dev.202606182057.d0c9925 → 0.9.0-dev.202606182147.d5eebd3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.9.0-dev.202606182057.d0c9925",
+  "version": "0.9.0-dev.202606182147.d5eebd3",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/guardian-card-withdrawal.test.ts

@@ -0,0 +1,278 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+  truncateForLog: (value: string) => value,
+}));
+
+const completeSurfaceAndNotify = mock(() => {});
+mock.module("../daemon/conversation-surfaces.js", () => ({
+  completeSurfaceAndNotify,
+}));
+
+const withdrawSlackApprovalCard = mock(
+  async (_params: Record<string, unknown>) => {},
+);
+mock.module("../messaging/providers/slack/withdraw.js", () => ({
+  withdrawSlackApprovalCard,
+}));
+
+import { withdrawGuardianRequestCards } from "../approvals/guardian-card-withdrawal.js";
+import {
+  type CanonicalGuardianRequest,
+  createCanonicalGuardianDelivery,
+  createCanonicalGuardianRequest,
+  listCanonicalGuardianDeliveries,
+} from "../memory/canonical-guardian-store.js";
+import { getDb } from "../memory/db-connection.js";
+import { initializeDb } from "../memory/db-init.js";
+import { recordCanonicalChannelDelivery } from "../notifications/canonical-delivery-recorder.js";
+import type { NotificationDeliveryResult } from "../notifications/types.js";
+
+initializeDb();
+
+const PRINCIPAL_ID = "withdrawal-test-principal";
+
+function resetTables(): void {
+  const db = getDb();
+  db.run("DELETE FROM canonical_guardian_deliveries");
+  db.run("DELETE FROM canonical_guardian_requests");
+}
+
+function makeRequest(
+  overrides: Partial<Parameters<typeof createCanonicalGuardianRequest>[0]> = {},
+): CanonicalGuardianRequest {
+  return createCanonicalGuardianRequest({
+    kind: "access_request",
+    sourceType: "channel",
+    sourceChannel: "slack",
+    guardianPrincipalId: PRINCIPAL_ID,
+    ...overrides,
+  });
+}
+
+describe("withdrawGuardianRequestCards", () => {
+  beforeEach(() => {
+    resetTables();
+    completeSurfaceAndNotify.mockClear();
+    withdrawSlackApprovalCard.mockClear();
+  });
+
+  test("withdraws + broadcasts the in-app card when the decision came from another surface", async () => {
+    const req = makeRequest();
+    createCanonicalGuardianDelivery({
+      requestId: req.id,
+      destinationChannel: "vellum",
+      destinationConversationId: "conv-1",
+    });
+
+    await withdrawGuardianRequestCards({
+      request: req,
+      status: "approved",
+      originChannel: "slack",
+    });
+
+    expect(completeSurfaceAndNotify).toHaveBeenCalledTimes(1);
+    expect(completeSurfaceAndNotify).toHaveBeenCalledWith(
+      "conv-1",
+      `access-request-${req.id}`,
+      "Approved",
+    );
+  });
+
+  test("skips the in-app card when the decision originated in-app", async () => {
+    const req = makeRequest();
+    createCanonicalGuardianDelivery({
+      requestId: req.id,
+      destinationChannel: "vellum",
+      destinationConversationId: "conv-1",
+    });
+
+    await withdrawGuardianRequestCards({
+      request: req,
+      status: "approved",
+      originChannel: "vellum",
+    });
+
+    // The acting in-app client already completed its own card optimistically.
+    expect(completeSurfaceAndNotify).not.toHaveBeenCalled();
+  });
+
+  test("withdraws the Slack card with decider and decision time", async () => {
+    const req = makeRequest({ decidedByExternalUserId: "U-guardian" });
+    createCanonicalGuardianDelivery({
+      requestId: req.id,
+      destinationChannel: "slack",
+      destinationChatId: "C123",
+      destinationMessageId: "1700000000.0001",
+    });
+
+    await withdrawGuardianRequestCards({
+      request: req,
+      status: "denied",
+      originChannel: "vellum",
+    });
+
+    expect(withdrawSlackApprovalCard).toHaveBeenCalledTimes(1);
+    const [params] = withdrawSlackApprovalCard.mock.calls[0];
+    expect(params).toMatchObject({
+      channel: "C123",
+      messageTs: "1700000000.0001",
+      status: "denied",
+      decidedByExternalUserId: "U-guardian",
+    });
+    expect(typeof (params as { decidedAtMs?: number }).decidedAtMs).toBe(
+      "number",
+    );
+  });
+
+  test("skips the Slack edit when no channel message id was captured", async () => {
+    const req = makeRequest();
+    createCanonicalGuardianDelivery({
+      requestId: req.id,
+      destinationChannel: "slack",
+      destinationChatId: "C123",
+    });
+
+    await withdrawGuardianRequestCards({ request: req, status: "approved" });
+
+    expect(withdrawSlackApprovalCard).not.toHaveBeenCalled();
+  });
+
+  test("withdraws every surface (including in-app broadcast) when no origin channel", async () => {
+    const req = makeRequest();
+    createCanonicalGuardianDelivery({
+      requestId: req.id,
+      destinationChannel: "vellum",
+      destinationConversationId: "conv-1",
+    });
+    createCanonicalGuardianDelivery({
+      requestId: req.id,
+      destinationChannel: "slack",
+      destinationChatId: "C1",
+      destinationMessageId: "1.0",
+    });
+
+    await withdrawGuardianRequestCards({ request: req, status: "expired" });
+
+    expect(completeSurfaceAndNotify).toHaveBeenCalledWith(
+      "conv-1",
+      `access-request-${req.id}`,
+      "Expired",
+    );
+    expect(withdrawSlackApprovalCard).toHaveBeenCalledTimes(1);
+  });
+
+  test("ignores channels without in-place edit support (telegram)", async () => {
+    const req = makeRequest({ sourceChannel: "telegram" });
+    createCanonicalGuardianDelivery({
+      requestId: req.id,
+      destinationChannel: "telegram",
+      destinationChatId: "T1",
+      destinationMessageId: "9",
+    });
+
+    await withdrawGuardianRequestCards({ request: req, status: "approved" });
+
+    expect(withdrawSlackApprovalCard).not.toHaveBeenCalled();
+    expect(completeSurfaceAndNotify).not.toHaveBeenCalled();
+  });
+
+  test("is best-effort: a failing surface never blocks the others or throws", async () => {
+    withdrawSlackApprovalCard.mockImplementationOnce(async () => {
+      throw new Error("slack unavailable");
+    });
+    const req = makeRequest();
+    createCanonicalGuardianDelivery({
+      requestId: req.id,
+      destinationChannel: "slack",
+      destinationChatId: "C1",
+      destinationMessageId: "1.0",
+    });
+    createCanonicalGuardianDelivery({
+      requestId: req.id,
+      destinationChannel: "vellum",
+      destinationConversationId: "conv-1",
+    });
+
+    await expect(
+      withdrawGuardianRequestCards({
+        request: req,
+        status: "approved",
+        originChannel: "telegram",
+      }),
+    ).resolves.toBeUndefined();
+
+    // The in-app card was still withdrawn despite the Slack failure.
+    expect(completeSurfaceAndNotify).toHaveBeenCalledTimes(1);
+  });
+
+  test("tool-approval cards resolve to the tool-approval surface id", async () => {
+    const req = makeRequest({ kind: "tool_approval", toolName: "shell" });
+    createCanonicalGuardianDelivery({
+      requestId: req.id,
+      destinationChannel: "vellum",
+      destinationConversationId: "conv-1",
+    });
+
+    await withdrawGuardianRequestCards({
+      request: req,
+      status: "approved",
+      originChannel: "telegram",
+    });
+
+    expect(completeSurfaceAndNotify).toHaveBeenCalledWith(
+      "conv-1",
+      `tool-approval-${req.id}`,
+      "Approved",
+    );
+  });
+});
+
+describe("recordCanonicalChannelDelivery", () => {
+  beforeEach(() => {
+    resetTables();
+    withdrawSlackApprovalCard.mockClear();
+  });
+
+  test("captures the channel-native message id so the card can be withdrawn", async () => {
+    const req = makeRequest();
+    const result: NotificationDeliveryResult = {
+      channel: "slack",
+      destination: "C999",
+      status: "sent",
+      messageId: "1700000000.1234",
+    };
+
+    const delivery = recordCanonicalChannelDelivery(req.id, result);
+
+    expect(delivery.destinationChannel).toBe("slack");
+    expect(delivery.destinationChatId).toBe("C999");
+    expect(delivery.destinationMessageId).toBe("1700000000.1234");
+
+    // End-to-end: the recorded delivery is now editable by the withdrawal path.
+    await withdrawGuardianRequestCards({
+      request: req,
+      status: "approved",
+      originChannel: "vellum",
+    });
+    const [params] = withdrawSlackApprovalCard.mock.calls[0];
+    expect((params as { messageTs?: string }).messageTs).toBe(
+      "1700000000.1234",
+    );
+  });
+
+  test("omits chat id when the destination is empty", () => {
+    const req = makeRequest();
+    const delivery = recordCanonicalChannelDelivery(req.id, {
+      channel: "slack",
+      destination: "",
+      status: "sent",
+    });
+    expect(delivery.destinationChatId).toBeNull();
+    expect(listCanonicalGuardianDeliveries(req.id)).toHaveLength(1);
+  });
+});

package/src/__tests__/trusted-contact-inline-approval-integration.test.ts

@@ -92,7 +92,7 @@ mock.module("../runtime/channel-verification-service.js", () => ({
     return null;
   },
   createOutboundSession: () => ({
-    conversationId: "test-session",
+    sessionId: "test-session",
     secret: "123456",
   }),
   bindSessionIdentity: () => {},
@@ -108,16 +108,23 @@ mock.module("../runtime/channel-verification-service.js", () => ({
   }),
 }));
 
-// Mock gateway client — capture delivery calls
+// Mock gateway client — capture delivery calls. `failDeliveryWhen` lets a test
+// simulate a delivery failure for a specific payload (e.g. a DM that can't be
+// opened) so fallback paths can be exercised.
 const deliveredReplies: Array<{
   url: string;
   payload: Record<string, unknown>;
 }> = [];
+let failDeliveryWhen: ((payload: Record<string, unknown>) => boolean) | null =
+  null;
 mock.module("../runtime/gateway-client.js", () => ({
   deliverChannelReply: async (
     url: string,
     payload: Record<string, unknown>,
   ) => {
+    if (failDeliveryWhen?.(payload)) {
+      throw new Error("simulated delivery failure");
+    }
     deliveredReplies.push({ url, payload });
     return { ok: true };
   },
@@ -150,6 +157,7 @@ mock.module("../config/env.js", () => ({
 import { applyCanonicalGuardianDecision } from "../approvals/guardian-decision-primitive.js";
 import type { ActorContext } from "../approvals/guardian-request-resolvers.js";
 import { getResolver } from "../approvals/guardian-request-resolvers.js";
+import { upsertContactChannel } from "../contacts/contacts-write.js";
 import type { TrustContext } from "../daemon/trust-context.js";
 import {
   createCanonicalGuardianRequest,
@@ -1088,3 +1096,212 @@ describe("cross-milestone integration checks", () => {
   });
 });
 
+// ===========================================================================
+// (g) access_request resolver: requester verification-code delivery
+//
+// On approval the requester must receive the 6-digit code so the guardian
+// never has to relay it by hand. On Slack the code is DM'd straight to the
+// requester (a private path is guaranteed via their user ID); other channels
+// keep the courier message because a private path to the requester is not
+// guaranteed there (e.g. a group chat would leak the secret).
+// ===========================================================================
+
+describe("(g) access_request resolver: requester code delivery", () => {
+  const REQUESTER_UID = "U_REQUESTER";
+  const GUARDIAN_UID = "U_GUARDIAN";
+
+  function createAccessRequest(overrides: Record<string, unknown> = {}) {
+    return createCanonicalGuardianRequest({
+      id: `access-req-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+      kind: "access_request",
+      sourceType: "channel",
+      sourceChannel: "slack",
+      conversationId: "conv-access-slack",
+      requesterExternalUserId: REQUESTER_UID,
+      requesterChatId: "C_SHARED_CHANNEL",
+      guardianExternalUserId: GUARDIAN_UID,
+      guardianPrincipalId: "test-principal-id",
+      toolName: "ingress_access_request",
+      expiresAt: Date.now() + 60_000,
+      ...overrides,
+    });
+  }
+
+  beforeEach(() => {
+    resetTables();
+    deliveredReplies.length = 0;
+    emittedSignals.length = 0;
+    failDeliveryWhen = null;
+  });
+
+  test("on-channel Slack approval DMs the verification code to the requester", async () => {
+    const req = createAccessRequest();
+
+    const result = await applyCanonicalGuardianDecision({
+      requestId: req.id,
+      action: "approve_once",
+      actorContext: guardianActor({
+        channel: "slack",
+        actorExternalUserId: GUARDIAN_UID,
+      }),
+      channelDeliveryContext: {
+        replyCallbackUrl:
+          "http://localhost:3000/deliver/slack?threadTs=111.222",
+        guardianChatId: "C_SHARED_CHANNEL",
+        assistantId: "self",
+      },
+    });
+
+    expect(result.applied).toBe(true);
+
+    // The requester receives the actual code in their DM (chatId = user ID),
+    // not a "ask the guardian" courier message.
+    const requesterCodeReply = deliveredReplies.find(
+      (r) =>
+        r.payload.chatId === REQUESTER_UID &&
+        typeof r.payload.text === "string" &&
+        (r.payload.text as string).includes("123456"),
+    );
+    expect(requesterCodeReply).toBeDefined();
+    expect(requesterCodeReply!.payload.text).toContain(
+      "your access request was approved",
+    );
+    // The code DM is durable, never ephemeral.
+    expect(requesterCodeReply!.payload.ephemeral).toBeUndefined();
+    // threadTs (the guardian's channel thread) is stripped for the DM.
+    expect(requesterCodeReply!.url).not.toContain("threadTs");
+
+    // No courier "receive from the guardian" message goes to the requester.
+    const courier = deliveredReplies.find(
+      (r) =>
+        typeof r.payload.text === "string" &&
+        (r.payload.text as string).includes("receive from the guardian"),
+    );
+    expect(courier).toBeUndefined();
+  });
+
+  test("desktop-decided approval DMs the code to the Slack requester via the deliver path", async () => {
+    const req = createAccessRequest();
+
+    const result = await applyCanonicalGuardianDecision({
+      requestId: req.id,
+      action: "approve_once",
+      // Desktop decision: no channelDeliveryContext, actor on the vellum channel.
+      actorContext: guardianActor({
+        channel: "vellum",
+        actorExternalUserId: undefined,
+      }),
+    });
+
+    expect(result.applied).toBe(true);
+
+    const requesterCodeReply = deliveredReplies.find(
+      (r) =>
+        r.payload.chatId === REQUESTER_UID &&
+        typeof r.payload.text === "string" &&
+        (r.payload.text as string).includes("123456"),
+    );
+    expect(requesterCodeReply).toBeDefined();
+    expect(requesterCodeReply!.url).toContain("/deliver/slack");
+    expect(requesterCodeReply!.payload.text).toContain(
+      "your access request was approved",
+    );
+  });
+
+  test("non-Slack channel keeps the courier message and never delivers the code to the requester chat", async () => {
+    const req = createAccessRequest({
+      sourceChannel: "telegram",
+      requesterChatId: "requester-chat-1",
+      conversationId: "conv-access-telegram",
+    });
+
+    const result = await applyCanonicalGuardianDecision({
+      requestId: req.id,
+      action: "approve_once",
+      actorContext: guardianActor({
+        channel: "telegram",
+        actorExternalUserId: GUARDIAN_UID,
+      }),
+      channelDeliveryContext: {
+        replyCallbackUrl: "http://localhost:3000/deliver/telegram",
+        guardianChatId: "guardian-chat-1",
+        assistantId: "self",
+      },
+    });
+
+    expect(result.applied).toBe(true);
+
+    // The requester is told to expect the code from the guardian; the secret is
+    // never delivered to the requester's (possibly group) chat.
+    const requesterReply = deliveredReplies.find(
+      (r) => r.payload.chatId === "requester-chat-1",
+    );
+    expect(requesterReply).toBeDefined();
+    expect(requesterReply!.payload.text).toContain("receive from the guardian");
+    expect(requesterReply!.payload.text).not.toContain("123456");
+  });
+
+  test("Slack shared-channel fallback posts an ephemeral notice to the channel when the DM fails", async () => {
+    const req = createAccessRequest();
+
+    // Make the direct DM (to the U... user ID) fail so the courier fallback runs.
+    failDeliveryWhen = (payload) => payload.chatId === REQUESTER_UID;
+
+    const result = await applyCanonicalGuardianDecision({
+      requestId: req.id,
+      action: "approve_once",
+      actorContext: guardianActor({
+        channel: "slack",
+        actorExternalUserId: GUARDIAN_UID,
+      }),
+      channelDeliveryContext: {
+        replyCallbackUrl:
+          "http://localhost:3000/deliver/slack?threadTs=111.222",
+        guardianChatId: "C_SHARED_CHANNEL",
+        assistantId: "self",
+      },
+    });
+
+    expect(result.applied).toBe(true);
+
+    // The courier notice falls back to an ephemeral message targeting the
+    // originating channel (C...), since chat.postEphemeral needs a channel ID —
+    // not the requester's user ID.
+    const courier = deliveredReplies.find(
+      (r) =>
+        typeof r.payload.text === "string" &&
+        (r.payload.text as string).includes("receive from the guardian"),
+    );
+    expect(courier).toBeDefined();
+    expect(courier!.payload.chatId).toBe("C_SHARED_CHANNEL");
+    expect(courier!.payload.ephemeral).toBe(true);
+    expect(courier!.payload.user).toBe(REQUESTER_UID);
+  });
+
+  test("guardian-facing reply uses the requester's display name, not the raw ID", async () => {
+    // Seed a contact so the resolver can resolve a display name.
+    upsertContactChannel({
+      sourceChannel: "slack",
+      externalUserId: REQUESTER_UID,
+      displayName: "Alice",
+      status: "unverified",
+    });
+
+    const req = createAccessRequest();
+
+    const result = await applyCanonicalGuardianDecision({
+      requestId: req.id,
+      action: "approve_once",
+      // Desktop decision → resolver returns guardianReplyText for assertion.
+      actorContext: guardianActor({
+        channel: "vellum",
+        actorExternalUserId: undefined,
+      }),
+    });
+
+    expect(result.applied).toBe(true);
+    const replyText = result.applied ? result.resolverReplyText : undefined;
+    expect(replyText).toContain("Alice");
+    expect(replyText).not.toContain(REQUESTER_UID);
+  });
+});

package/src/approvals/guardian-card-withdrawal.ts

@@ -0,0 +1,145 @@
+/**
+ * Cross-surface withdrawal of guardian approval cards.
+ *
+ * A single guardian request is projected onto every surface it was delivered
+ * to — the in-app Vellum card, a Slack message, etc. When the request reaches a
+ * terminal status its cards must stop offering live actions on *all* surfaces,
+ * not just the one the guardian acted on. This is the withdrawal counterpart to
+ * the unified card *rendering* dispatcher (`notifications/approval-card-data.ts`):
+ * rendering projects `pending` onto each surface, withdrawal projects the
+ * terminal status back onto each surface.
+ *
+ * Withdrawal preserves the card's information and removes only the live
+ * affordances (it does not delete the message/card) so each surface keeps an
+ * audit trail of what was decided.
+ *
+ * It is driven off `canonical_guardian_deliveries` — the per-request registry of
+ * where each card was sent — so it stays correct as surfaces are added and is
+ * agnostic to which surface originated the decision.
+ *
+ * Best-effort by contract: the request is already resolved (CAS committed)
+ * before this runs, so a failed edit must never surface as a decision failure.
+ * Every surface is attempted independently; one failure never blocks the rest.
+ */
+
+import { completeSurfaceAndNotify } from "../daemon/conversation-surfaces.js";
+import {
+  type CanonicalGuardianDelivery,
+  type CanonicalGuardianRequest,
+  type CanonicalRequestStatus,
+  listCanonicalGuardianDeliveries,
+} from "../memory/canonical-guardian-store.js";
+import { withdrawSlackApprovalCard } from "../messaging/providers/slack/withdraw.js";
+import { approvalCardSurfaceId } from "../notifications/approval-card-data.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("guardian-card-withdrawal");
+
+/** Completion-summary label shown on an in-app card for a resolved request. */
+const SURFACE_STATUS_LABELS: Partial<Record<CanonicalRequestStatus, string>> = {
+  approved: "Approved",
+  denied: "Denied",
+  expired: "Expired",
+  cancelled: "Cancelled",
+};
+
+export interface WithdrawGuardianCardsParams {
+  /** The request, already transitioned to its terminal status. */
+  request: CanonicalGuardianRequest;
+  /** Terminal status to reflect on each card. */
+  status: CanonicalRequestStatus;
+  /**
+   * Channel the decision originated on, when applicable.
+   *
+   * The acting in-app client completes its own card optimistically, so the
+   * in-app card is skipped when the decision originated in-app; it is withdrawn
+   * here only when the decision came from another surface. Omit (e.g. the expiry
+   * sweep) to withdraw every surface.
+   */
+  originChannel?: string;
+}
+
+/**
+ * Withdraw a resolved request's approval cards across all delivery surfaces.
+ * Never throws.
+ */
+export async function withdrawGuardianRequestCards(
+  params: WithdrawGuardianCardsParams,
+): Promise<void> {
+  const { request, status, originChannel } = params;
+
+  let deliveries: CanonicalGuardianDelivery[];
+  try {
+    deliveries = listCanonicalGuardianDeliveries(request.id);
+  } catch (err) {
+    log.warn(
+      { err, requestId: request.id },
+      "Failed to list deliveries for card withdrawal",
+    );
+    return;
+  }
+
+  for (const delivery of deliveries) {
+    try {
+      if (delivery.destinationChannel === "vellum") {
+        withdrawVellumCard(request, delivery, status, originChannel);
+      } else if (delivery.destinationChannel === "slack") {
+        await withdrawSlackCard(request, delivery, status);
+      }
+      // Telegram/WhatsApp direct delivery can't edit a message in place (it
+      // would post a new one), so their stale clicks are left to the existing
+      // "already resolved" reply until in-place edit support lands.
+    } catch (err) {
+      log.warn(
+        {
+          err,
+          requestId: request.id,
+          channel: delivery.destinationChannel,
+        },
+        "Failed to withdraw guardian card on surface (non-fatal)",
+      );
+    }
+  }
+}
+
+/**
+ * Withdraw the in-app approval card so it stops offering live actions while
+ * keeping its content. Skipped when the decision originated in-app — the acting
+ * client already completed the card itself.
+ */
+function withdrawVellumCard(
+  request: CanonicalGuardianRequest,
+  delivery: CanonicalGuardianDelivery,
+  status: CanonicalRequestStatus,
+  originChannel: string | undefined,
+): void {
+  if (originChannel === "vellum") return;
+  if (!delivery.destinationConversationId) return;
+  const surfaceId = approvalCardSurfaceId(request.kind, request.id);
+  if (!surfaceId) return;
+  completeSurfaceAndNotify(
+    delivery.destinationConversationId,
+    surfaceId,
+    SURFACE_STATUS_LABELS[status] ?? "Resolved",
+  );
+}
+
+/**
+ * Edit the Slack message in place to its resolved state — original card content
+ * preserved, action buttons removed, an outcome/decider/time line appended.
+ * No-ops when the channel-native message id was not captured at delivery time.
+ */
+async function withdrawSlackCard(
+  request: CanonicalGuardianRequest,
+  delivery: CanonicalGuardianDelivery,
+  status: CanonicalRequestStatus,
+): Promise<void> {
+  if (!delivery.destinationChatId || !delivery.destinationMessageId) return;
+  await withdrawSlackApprovalCard({
+    channel: delivery.destinationChatId,
+    messageTs: delivery.destinationMessageId,
+    status,
+    decidedByExternalUserId: request.decidedByExternalUserId ?? undefined,
+    decidedAtMs: request.updatedAt,
+  });
+}