@vellumai/assistant 0.11.7 → 0.11.8-staging.1

package/src/notifications/__tests__/guardian-feed-projection.test.ts

@@ -0,0 +1,360 @@
+import * as fs from "node:fs";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
+
+// The feed writer publishes `home_feed_updated` on every write; the hub is
+// stubbed so tests run without an SSE server. Mocked before the writer
+// module is imported so the import picks it up.
+mock.module("../../runtime/assistant-event-hub.js", () => ({
+  assistantEventHub: {
+    publish: async () => {},
+    subscribe: () => () => {},
+  },
+  broadcastMessage: () => {},
+}));
+
+// Gateway reads used by reconciliation. Stubs are swapped per test; the
+// spread keeps every other export real so transitive importers keep
+// working (partial factories break at import time).
+const actualGateway =
+  await import("../../channels/gateway-guardian-requests.js");
+let listGuardianRequestsStub: () => Promise<unknown[]> = async () => [];
+let getGuardianRequestStub: (id: string) => Promise<unknown> = async () => null;
+mock.module("../../channels/gateway-guardian-requests.js", () => ({
+  ...actualGateway,
+  listGuardianRequests: (...args: unknown[]) =>
+    (listGuardianRequestsStub as (...a: unknown[]) => Promise<unknown[]>)(
+      ...args,
+    ),
+  getGuardianRequest: (id: string) => getGuardianRequestStub(id),
+}));
+
+const {
+  buildPendingGuardianProjection,
+  guardianFeedItemId,
+  reconcileGuardianFeedProjections,
+  requestIdFromGuardianFeedItemId,
+  writeGuardianFeedReceipt,
+} = await import("../guardian-feed-projection.js");
+const { appendFeedItem, bulkSetFeedItemStatus, getHomeFeedPath, readHomeFeed } =
+  await import("../../home/feed-writer.js");
+const { isPendingGuardianFeedItem } =
+  await import("../../api/responses/home.js");
+type FeedItem = import("../../api/responses/home.js").FeedItem;
+
+let workspaceDir: string;
+let origWorkspaceDir: string | undefined;
+
+beforeEach(() => {
+  workspaceDir = mkdtempSync(join(tmpdir(), "vellum-gfp-"));
+  origWorkspaceDir = process.env.VELLUM_WORKSPACE_DIR;
+  process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
+  listGuardianRequestsStub = async () => [];
+  getGuardianRequestStub = async () => null;
+});
+
+afterEach(() => {
+  if (origWorkspaceDir === undefined) {
+    delete process.env.VELLUM_WORKSPACE_DIR;
+  } else {
+    process.env.VELLUM_WORKSPACE_DIR = origWorkspaceDir;
+  }
+  rmSync(workspaceDir, { recursive: true, force: true });
+});
+
+const toolApprovalPayload = {
+  requestKind: "tool_approval",
+  requestId: "req-1",
+  requestCode: "ABC123",
+  questionText: "Alice asked the assistant to look up an issue",
+  toolName: "linear_graphql",
+  sourceChannel: "slack",
+  sourceChatId: "C0123456789",
+  requesterIdentifier: "Alice",
+};
+
+function pendingGuardianItem(requestId: string): FeedItem {
+  const projection = buildPendingGuardianProjection({
+    ...toolApprovalPayload,
+    requestId,
+  });
+  if (!projection) {
+    throw new Error("projection should build");
+  }
+  return {
+    id: guardianFeedItemId(requestId),
+    type: "notification",
+    priority: 50,
+    summary: "Alice asked the assistant to look up an issue",
+    timestamp: "2026-08-31T12:00:00.000Z",
+    createdAt: "2026-08-31T12:00:00.000Z",
+    status: "new",
+    urgency: "high",
+    guardianRequest: projection,
+  };
+}
+
+describe("buildPendingGuardianProjection", () => {
+  test("tool approval projects as a pending approval with source facts", () => {
+    const projection = buildPendingGuardianProjection(toolApprovalPayload);
+    expect(projection).toMatchObject({
+      requestId: "req-1",
+      kind: "tool_approval",
+      intent: "approval",
+      status: "pending",
+      requesterLabel: "Alice",
+      toolName: "linear_graphql",
+      sourceChannel: "slack",
+      sourceContextLabel: "Slack #C0123456789",
+    });
+  });
+
+  test("a question without a tool projects as question intent", () => {
+    const projection = buildPendingGuardianProjection({
+      requestKind: "pending_question",
+      requestId: "req-q",
+      requestCode: "Q1",
+      questionText: "Which venue should I book?",
+    });
+    expect(projection?.intent).toBe("question");
+    expect(projection?.status).toBe("pending");
+  });
+
+  test("a sent Slack delivery yields the card deep link", () => {
+    const projection = buildPendingGuardianProjection(toolApprovalPayload, {
+      channel: "slack",
+      destination: "D0AAAAAAAAA",
+      status: "sent",
+      messageId: "1725100000.000100",
+    });
+    expect(projection?.slackCardUrl).toContain("D0AAAAAAAAA");
+  });
+
+  test("a payload without a requestId projects nothing", () => {
+    expect(
+      buildPendingGuardianProjection({ requestKind: "tool_approval" }),
+    ).toBeNull();
+  });
+
+  test("an access-request payload projects with the event's implied kind", () => {
+    const projection = buildPendingGuardianProjection(
+      {
+        requestId: "req-a",
+        requestCode: "AC1234",
+        sourceChannel: "telegram",
+        senderIdentifier: "Alice",
+      },
+      undefined,
+      "access_request",
+    );
+    expect(projection).toMatchObject({
+      requestId: "req-a",
+      kind: "access_request",
+      intent: "approval",
+      status: "pending",
+      requesterLabel: "Alice",
+    });
+  });
+});
+
+describe("guardianFeedItemId", () => {
+  test("round-trips through requestIdFromGuardianFeedItemId", () => {
+    expect(requestIdFromGuardianFeedItemId(guardianFeedItemId("req-9"))).toBe(
+      "req-9",
+    );
+    expect(requestIdFromGuardianFeedItemId("notif:xyz")).toBeNull();
+  });
+});
+
+describe("bulk-dismiss protection", () => {
+  test("clear-all skips the pending item and clears its receipt", async () => {
+    await appendFeedItem(pendingGuardianItem("req-1"));
+    await appendFeedItem({
+      id: "notif:other",
+      type: "notification",
+      priority: 50,
+      summary: "routine",
+      timestamp: "2026-08-31T12:00:00.000Z",
+      createdAt: "2026-08-31T12:00:00.000Z",
+      status: "seen",
+    });
+
+    const first = await bulkSetFeedItemStatus(
+      ["new", "seen", "acted_on"],
+      "dismissed",
+    );
+    let items = readHomeFeed().items;
+    const guardianItem = items.find(
+      (i) => i.id === guardianFeedItemId("req-1"),
+    );
+    // Exactly the routine item flipped; the pending projection is intact
+    // and still actionable.
+    expect(first).toBe(1);
+    expect(guardianItem?.status).toBe("new");
+    expect(items.find((i) => i.id === "notif:other")?.status).toBe("dismissed");
+    expect(guardianItem && isPendingGuardianFeedItem(guardianItem)).toBe(true);
+
+    // Sensitivity: once the request resolves, the same bulk op clears it.
+    await writeGuardianFeedReceipt({ requestId: "req-1", status: "approved" });
+    const second = await bulkSetFeedItemStatus(
+      ["new", "seen", "acted_on"],
+      "dismissed",
+    );
+    items = readHomeFeed().items;
+    expect(second).toBe(1);
+    expect(
+      items.find((i) => i.id === guardianFeedItemId("req-1"))?.status,
+    ).toBe("dismissed");
+  });
+
+  test("bulk read-marking never dismisses but may still touch guardian items", async () => {
+    await appendFeedItem(pendingGuardianItem("req-2"));
+    const updated = await bulkSetFeedItemStatus(["new"], "seen");
+    // Only dismissal is protected; a bulk `seen` transition (not offered
+    // for guardian rows by the web client, which excludes their ids) is
+    // not blocked by the writer.
+    expect(updated).toBe(1);
+  });
+});
+
+describe("writeGuardianFeedReceipt", () => {
+  test("a decision rewrites the item into a clearable receipt", async () => {
+    await appendFeedItem(pendingGuardianItem("req-3"));
+    const ok = await writeGuardianFeedReceipt({
+      requestId: "req-3",
+      status: "approved",
+      decidedAction: "approve_once",
+      decidedAtMs: Date.parse("2026-08-31T13:00:00.000Z"),
+    });
+    expect(ok).toBe(true);
+
+    const item = readHomeFeed().items.find(
+      (i) => i.id === guardianFeedItemId("req-3"),
+    );
+    expect(item?.guardianRequest).toMatchObject({
+      status: "approved",
+      decidedAction: "approve_once",
+      decidedAt: "2026-08-31T13:00:00.000Z",
+    });
+    expect(item?.urgency).toBe("medium");
+    expect(item && isPendingGuardianFeedItem(item)).toBe(false);
+  });
+
+  test("a superseded auto-deny carries its reason and no decider", async () => {
+    await appendFeedItem(pendingGuardianItem("req-4"));
+    await writeGuardianFeedReceipt({
+      requestId: "req-4",
+      status: "denied",
+      decidedAction: "reject",
+      terminalReason: "superseded",
+    });
+    const item = readHomeFeed().items.find(
+      (i) => i.id === guardianFeedItemId("req-4"),
+    );
+    expect(item?.guardianRequest?.terminalReason).toBe("superseded");
+    expect(item?.guardianRequest?.decidedByLabel).toBeUndefined();
+  });
+
+  test("a request with no item resolves true (nothing to retry)", async () => {
+    expect(
+      await writeGuardianFeedReceipt({ requestId: "ghost", status: "expired" }),
+    ).toBe(true);
+  });
+
+  test("a lost write on an existing item resolves false so callers retry", async () => {
+    await appendFeedItem(pendingGuardianItem("req-5"));
+    // Fail the next feed-file write while the item is still present in
+    // the read path, so the missing-item and lost-write cases separate.
+    const feedPath = getHomeFeedPath();
+    const originalWrite = fs.writeFileSync;
+    const spy = spyOn(fs, "writeFileSync").mockImplementation(((
+      path: fs.PathOrFileDescriptor,
+      data: string | NodeJS.ArrayBufferView,
+      options?: fs.WriteFileOptions,
+    ) => {
+      if (typeof path === "string" && path === feedPath) {
+        throw new Error("Simulated write failure");
+      }
+      return originalWrite(path, data, options);
+    }) as typeof fs.writeFileSync);
+    try {
+      expect(
+        await writeGuardianFeedReceipt({
+          requestId: "req-5",
+          status: "expired",
+        }),
+      ).toBe(false);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});
+
+describe("reconcileGuardianFeedProjections", () => {
+  const wireRequest = (overrides: Record<string, unknown>) => ({
+    id: "req-r",
+    kind: "tool_approval",
+    sourceType: "channel",
+    sourceChannel: "slack",
+    sourceConversationId: "conv-1",
+    requesterExternalUserId: "U1",
+    requesterChatId: null,
+    guardianExternalUserId: null,
+    guardianPrincipalId: null,
+    callSessionId: null,
+    pendingQuestionId: null,
+    questionText: "Alice asked the assistant to look up an issue",
+    requestCode: "ABC123",
+    toolName: "linear_graphql",
+    inputDigest: null,
+    commandPreview: null,
+    riskLevel: null,
+    activityText: null,
+    executionTarget: null,
+    requesterSignals: null,
+    requestTrigger: null,
+    status: "pending",
+    answerText: null,
+    decidedByExternalUserId: null,
+    decidedByPrincipalId: null,
+    followupState: null,
+    expiresAt: null,
+    createdAt: Date.parse("2026-08-31T12:00:00.000Z"),
+    updatedAt: Date.parse("2026-08-31T12:00:00.000Z"),
+    ...overrides,
+  });
+
+  test("backfills an item for a pending request that has none", async () => {
+    listGuardianRequestsStub = async () => [wireRequest({ id: "req-r" })];
+    await reconcileGuardianFeedProjections();
+    const item = readHomeFeed().items.find(
+      (i) => i.id === guardianFeedItemId("req-r"),
+    );
+    expect(item?.guardianRequest?.status).toBe("pending");
+    expect(item?.conversationId).toBe("conv-1");
+    expect(item?.detailPanel?.kind).toBe("permissionChat");
+  });
+
+  test("receipts an actionable item whose request went terminal", async () => {
+    await appendFeedItem(pendingGuardianItem("req-t"));
+    listGuardianRequestsStub = async () => [];
+    getGuardianRequestStub = async () =>
+      wireRequest({ id: "req-t", status: "denied" });
+    await reconcileGuardianFeedProjections();
+    const item = readHomeFeed().items.find(
+      (i) => i.id === guardianFeedItemId("req-t"),
+    );
+    expect(item?.guardianRequest?.status).toBe("denied");
+    expect(item && isPendingGuardianFeedItem(item)).toBe(false);
+  });
+});

package/src/notifications/__tests__/home-feed-side-effect.test.ts

@@ -40,7 +40,13 @@ mock.module("../../runtime/sync/resource-sync-events.js", () => ({
   },
 }));
 
+// Both factories spread the actual module: the module under test reaches
+// feed-writer through `guardian-feed-projection` too, and the real
+// feed-writer needs `parseFeedFile` from feed-types, so a partial factory
+// would fail at import time on any export it omitted.
+const actualFeedTypes = await import("../../home/feed-types.js");
 mock.module("../../home/feed-types.js", () => ({
+  ...actualFeedTypes,
   feedItemSchema: {
     parse: (item: unknown) => {
       if (feedItemSchemaShouldReject) {
@@ -51,7 +57,9 @@ mock.module("../../home/feed-types.js", () => ({
   },
 }));
 
+const actualFeedWriter = await import("../../home/feed-writer.js");
 mock.module("../../home/feed-writer.js", () => ({
+  ...actualFeedWriter,
   appendFeedItem: async (item: FeedItem) => {
     appendCalls.push(item);
   },

package/src/notifications/adapters/discord.ts

@@ -8,14 +8,15 @@
  * (cached per user) and a room id on the binding can never become a delivery
  * target. That is Slack's D-prefix DM gate, achieved by construction.
  *
- * Approval notifications carry the typed-command instructions instead of
- * component buttons: nothing ingests INTERACTION_CREATE yet, and a button
- * whose press goes nowhere is a dead control. When interaction ingest lands,
- * buttons arrive here as a rendering upgrade, not a new decision path.
+ * Approval notifications render component buttons whose presses the gateway
+ * ingests as button events on the shared `apr:` callback convention; a
+ * rendering failure falls back to the plain-text card with typed-command
+ * instructions, so a card is always actionable one way or the other.
  */
 
 import { openDiscordDmChannel } from "../../messaging/providers/discord/api.js";
 import {
+  DiscordPartialSendError,
   editDiscordMessage,
   sendDiscordReply,
 } from "../../messaging/providers/discord/send.js";
@@ -53,14 +54,66 @@ export class DiscordAdapter implements ChannelAdapter {
       };
     }
 
-    const text = appendPlainTextFallback(
-      resolveMessageText(payload),
-      payload.approvalContext,
-    );
+    const messageText = resolveMessageText(payload);
+    const approval = payload.approvalContext;
 
     try {
       const channelId = await openDiscordDmChannel(guardianUserId);
-      const sent = await sendDiscordReply({ channelId }, text);
+
+      if (approval) {
+        // Attempt rich delivery with component buttons; on failure, fall
+        // back to the plain-text card below.
+        try {
+          const sent = await sendDiscordReply(
+            { channelId },
+            messageText,
+            approval,
+          );
+          log.info(
+            { sourceEventName: payload.sourceEventName, guardianUserId },
+            "Discord approval notification delivered with buttons",
+          );
+          // The message id lets the delivery row address the card later
+          // (reactions, button presses, in-place withdrawal).
+          return { success: true, messageId: sent.lastMessageId };
+        } catch (richErr) {
+          if (richErr instanceof DiscordPartialSendError) {
+            // The leading chunks are delivered and cannot be unsent, so a
+            // full plain-text fallback would duplicate them. Complete the
+            // card instead: the undelivered remainder plus the typed-command
+            // instructions, whose message becomes the card's address.
+            log.warn(
+              {
+                err: richErr,
+                sourceEventName: payload.sourceEventName,
+                guardianUserId,
+                chunksSent: richErr.chunksSent,
+              },
+              "Rich Discord delivery failed mid-card, completing in plain text",
+            );
+            const completion = await sendDiscordReply(
+              { channelId },
+              appendPlainTextFallback(richErr.remainingText, approval),
+            );
+            return { success: true, messageId: completion.lastMessageId };
+          }
+          log.warn(
+            {
+              err: richErr,
+              sourceEventName: payload.sourceEventName,
+              guardianUserId,
+            },
+            "Rich Discord delivery failed, falling back to plain text",
+          );
+        }
+      }
+
+      // When falling back from rich delivery, append the plain-text
+      // instructions so the guardian still knows how to approve/reject.
+      const sent = await sendDiscordReply(
+        { channelId },
+        appendPlainTextFallback(messageText, approval),
+      );
 
       log.info(
         { sourceEventName: payload.sourceEventName, guardianUserId },

package/src/notifications/conversation-pairing.ts

@@ -1,10 +1,12 @@
 /**
  * Generic notification conversation pairing.
  *
- * Materializes a conversation + message for each notification delivery
- * before the adapter sends it. This ensures every delivery has an
- * auditable conversation trail and enables the macOS/iOS client to
- * deep-link directly into the notification conversation.
+ * Materializes a conversation + message for a notification delivery
+ * before the adapter sends it, so the delivery has an auditable
+ * conversation trail and the macOS/iOS client can deep-link into it.
+ * Guardian-request deliveries to channels are the exception: they are
+ * delivery projections of a canonical request and pair nothing (see the
+ * guard below); only their vellum delivery carries a conversation.
  *
  * Resolution order:
  * 1. Explicit `reuse_existing` conversation action — highest precedence.
@@ -37,6 +39,7 @@ import {
   composeConversationSeed,
   isConversationSeedSane,
 } from "./conversation-seed-composer.js";
+import { isGuardianRequestSignalEvent } from "./guardian-feed-projection.js";
 import type { NotificationSignal } from "./signal.js";
 import type {
   ConversationAction,
@@ -122,6 +125,30 @@ export async function pairDeliveryWithConversation(
       };
     }
 
+    // A channel-delivered guardian-request approval card (tool
+    // approvals, questions, and access requests alike) is a delivery
+    // projection of a canonical guardian request, not conversation
+    // content: its in-app homes are the home-feed "Needs attention"
+    // item and the source conversation's card (the vellum delivery,
+    // which still pairs below). Pairing a channel card here would
+    // either write it into the guardian's bound chat transcript or
+    // mint a fresh conversation for a transient work item, so it gets
+    // neither a row nor a conversation. The gateway delivery row (chat
+    // id + channel-native message id) remains its only persisted
+    // envelope.
+    if (
+      isGuardianRequestSignalEvent(signal.sourceEventName) &&
+      channel !== "vellum"
+    ) {
+      return {
+        conversationId: null,
+        messageId: null,
+        strategy,
+        createdNewConversation: false,
+        conversationFallbackUsed: false,
+      };
+    }
+
     const conversationAction = options?.conversationAction;
     const bindingContext = options?.bindingContext;
 

package/src/notifications/emit-signal.ts

@@ -547,11 +547,14 @@ export async function emitNotificationSignal<TEventName extends string>(
     const vellumDelivery = dispatchResult.deliveryResults.find(
       (r) => r.channel === "vellum",
     );
-    await writeHomeFeedItemForSignal(signal, decision, vellumDelivery).catch(
-      (err) => {
-        log.warn({ err, signalId }, "writeHomeFeedItemForSignal threw");
-      },
-    );
+    await writeHomeFeedItemForSignal(
+      signal,
+      decision,
+      vellumDelivery,
+      dispatchResult.deliveryResults,
+    ).catch((err) => {
+      log.warn({ err, signalId }, "writeHomeFeedItemForSignal threw");
+    });
 
     log.info(
       {

package/src/notifications/guardian-delivery-recorder.ts

@@ -20,8 +20,11 @@
  * read it back.
  */
 
+import { DELIVERY_STATUS } from "@vellumai/gateway-client";
+
 import {
   createGuardianRequestDelivery,
+  getGuardianRequestOrNull,
   type GuardianRequestDeliveryWire,
   updateGuardianRequestDelivery,
 } from "../channels/gateway-guardian-requests.js";
@@ -47,7 +50,7 @@ export interface ApprovalCardDeliveryAddress {
   chatId?: string;
   /** Channel-native message id (e.g. Slack `ts`) — the reaction/withdrawal key. */
   messageId?: string;
-  /** Initial delivery status (defaults to "pending"). */
+  /** Initial delivery status (defaults to `DELIVERY_STATUS.pending`). */
   status?: string;
 }
 
@@ -91,14 +94,17 @@ export async function recordApprovalCardDelivery(
  * that row's id as `vellumDeliveryId` and it is reused (only its status applied)
  * — otherwise the vellum row is created here from the result.
  *
- * Every addressable result records the internal `conversationId` the card is
- * shown in, so a conversation's pending cards can be found uniformly
- * regardless of channel. Platform push results are skipped entirely: a push
+ * The vellum result records the internal `conversationId` its card is shown
+ * in. Channel guardian cards pair no conversation (they are delivery
+ * projections; see `conversation-pairing.ts`), so their rows carry no
+ * `conversationId`. Platform push results are skipped entirely: a push
  * has no channel-native card surface to address back to.
  * Channel results additionally carry the chat (`destination`) and channel-native
  * id (`messageId`) used to match inbound replies/reactions; a blank `destination`
  * is recorded as unknown rather than persisting the literal channel name as a
- * chat id. Status is diagnostic — the read paths key off addressing, not status.
+ * chat id. Status has two readers: the voice guardian-action sweep acts only
+ * on `sent`/`pending` rows, and card withdrawal skips rows already marked
+ * `withdrawn` (its per-surface receipt). Addressing lookups ignore status.
  *
  * Best-effort like the create: a status-patch failure is logged, not thrown.
  *
@@ -146,7 +152,10 @@ export async function recordGuardianRequestDeliveries(params: {
     if (deliveryId) {
       try {
         await updateGuardianRequestDelivery(deliveryId, {
-          status: result.status === "sent" ? "sent" : "failed",
+          status:
+            result.status === "sent"
+              ? DELIVERY_STATUS.sent
+              : DELIVERY_STATUS.failed,
         });
       } catch (err) {
         log.error(
@@ -157,5 +166,37 @@ export async function recordGuardianRequestDeliveries(params: {
     }
   }
 
+  await withdrawIfRequestAlreadyTerminal(requestId);
+
   return vellumDeliveryId;
 }
+
+/**
+ * Close the delivery/decision race: recording happens after the notification
+ * pipeline finishes, so a guardian who acts on a card the moment it lands can
+ * resolve the request before its delivery rows exist. That decision's
+ * withdrawal pass then finds nothing to withdraw, and the rows recorded here
+ * would describe live cards for an already-terminal request. Re-running
+ * withdrawal after recording converges them; rows a prior pass already
+ * withdrew are skipped, so the overlap never re-edits a surface.
+ *
+ * Best-effort like the rest of the recorder; the decided action isn't
+ * recoverable here, so denied outcomes render the plain status word.
+ */
+async function withdrawIfRequestAlreadyTerminal(
+  requestId: string,
+): Promise<void> {
+  const request = await getGuardianRequestOrNull(requestId);
+  if (!request || request.status === "pending") {
+    return;
+  }
+  // Imported at call time: the withdrawal module reaches the daemon's
+  // conversation-surface graph, and a static import here would put this
+  // recorder (imported by the guardian-request producers) into that cycle.
+  const { withdrawGuardianRequestCards } =
+    await import("../approvals/guardian-card-withdrawal.js");
+  await withdrawGuardianRequestCards({
+    request,
+    status: request.status,
+  });
+}