@vellumai/assistant 0.8.12 → 0.9.0-staging.2

package/src/__tests__/guardian-action-sweep.test.ts

@@ -1,4 +1,4 @@
-import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
+import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 mock.module("../util/logger.js", () => ({
   getLogger: () =>
@@ -18,27 +18,11 @@ mock.module("../runtime/gateway-client.js", () => ({
   },
 }));
 
-import {
-  createCallSession,
-  createPendingQuestion,
-  getPendingQuestion,
-} from "../calls/call-store.js";
-import {
-  startGuardianActionSweep,
-  stopGuardianActionSweep,
-  sweepExpiredGuardianActions,
-} from "../calls/guardian-action-sweep.js";
+import type { ExpiryDeliveryInfo } from "../calls/guardian-action-sweep.js";
+import { sendGuardianExpiryNotices } from "../calls/guardian-action-sweep.js";
 import { getDb } from "../memory/db-connection.js";
 import { initializeDb } from "../memory/db-init.js";
-import {
-  createGuardianActionDelivery,
-  createGuardianActionRequest,
-  getDeliveriesByRequestId,
-  getGuardianActionRequest,
-  updateDeliveryStatus,
-} from "../memory/guardian-action-store.js";
-import { conversations } from "../memory/schema.js";
-import { resetDbForTesting } from "./db-test-helpers.js";
+import { conversations, messages } from "../memory/schema.js";
 
 initializeDb();
 
@@ -55,218 +39,71 @@ function ensureConversation(id: string): void {
     .run();
 }
 
-function resetTables(): void {
-  const db = getDb();
-  db.run("DELETE FROM guardian_action_deliveries");
-  db.run("DELETE FROM guardian_action_requests");
-  db.run("DELETE FROM call_pending_questions");
-  db.run("DELETE FROM call_events");
-  db.run("DELETE FROM call_sessions");
-  db.run("DELETE FROM messages");
-  db.run("DELETE FROM conversations");
-  deliveredMessages.length = 0;
+function makeDelivery(
+  overrides: Partial<ExpiryDeliveryInfo> = {},
+): ExpiryDeliveryInfo {
+  return {
+    id: "delivery-1",
+    status: "sent",
+    destinationChannel: "telegram",
+    destinationConversationId: null,
+    destinationChatId: "chat-123",
+    ...overrides,
+  };
 }
 
-describe("guardian-action-sweep", () => {
+describe("sendGuardianExpiryNotices", () => {
   beforeEach(() => {
-    resetTables();
-  });
-
-  afterAll(() => {
-    stopGuardianActionSweep();
-    resetDbForTesting();
+    const db = getDb();
+    db.run("DELETE FROM messages");
+    db.run("DELETE FROM conversations");
+    deliveredMessages.length = 0;
   });
 
-  test("sweepExpiredGuardianActions expires requests past their expiresAt", async () => {
-    const convId = "conv-sweep-1";
-    ensureConversation(convId);
-
-    const session = createCallSession({
-      conversationId: convId,
-      provider: "twilio",
-      fromNumber: "+15550001111",
-      toNumber: "+15550002222",
-    });
-    const pq = createPendingQuestion(session.id, "What is the code?");
-
-    // Create request that has already expired
-    const request = createGuardianActionRequest({
-      kind: "ask_guardian",
-      sourceChannel: "phone",
-      sourceConversationId: convId,
-      callSessionId: session.id,
-      pendingQuestionId: pq.id,
-      questionText: pq.questionText,
-      expiresAt: Date.now() - 10_000, // expired 10s ago
-    });
-
-    ensureConversation("conv-mac-1");
-    createGuardianActionDelivery({
-      requestId: request.id,
-      destinationChannel: "vellum",
-      destinationConversationId: "conv-mac-1",
-    });
-    updateDeliveryStatus(
-      getDeliveriesByRequestId(request.id).find(
-        (d) => d.destinationChannel === "vellum",
-      )!.id,
-      "sent",
+  test("sends external channel expiry notices for sent deliveries", async () => {
+    await sendGuardianExpiryNotices(
+      [makeDelivery({ status: "sent" }), makeDelivery({ id: "d2", status: "pending", destinationChatId: "chat-456" })],
+      "assistant-1",
     );
 
-    await sweepExpiredGuardianActions();
-
-    const updatedRequest = getGuardianActionRequest(request.id);
-    expect(updatedRequest).not.toBeNull();
-    expect(updatedRequest!.status).toBe("expired");
-
-    const deliveries = getDeliveriesByRequestId(request.id);
-    expect(deliveries).toHaveLength(1);
-    expect(deliveries[0].status).toBe("expired");
-  });
-
-  test("sweepExpiredGuardianActions expires pending questions", async () => {
-    const convId = "conv-sweep-2";
-    ensureConversation(convId);
-
-    const session = createCallSession({
-      conversationId: convId,
-      provider: "twilio",
-      fromNumber: "+15550001111",
-      toNumber: "+15550002222",
-    });
-    const pq = createPendingQuestion(session.id, "What is the gate code?");
-
-    createGuardianActionRequest({
-      kind: "ask_guardian",
-      sourceChannel: "phone",
-      sourceConversationId: convId,
-      callSessionId: session.id,
-      pendingQuestionId: pq.id,
-      questionText: pq.questionText,
-      expiresAt: Date.now() - 5_000,
-    });
-
-    // Verify the question is still pending before sweep
-    expect(getPendingQuestion(session.id)).not.toBeNull();
-
-    await sweepExpiredGuardianActions();
-
-    // Pending question should be expired
-    expect(getPendingQuestion(session.id)).toBeNull();
+    expect(deliveredMessages).toHaveLength(2);
+    expect(deliveredMessages[0].url).toBe("/deliver/telegram");
+    expect(deliveredMessages[0].body.chatId).toBe("chat-123");
+    expect(deliveredMessages[0].body.assistantId).toBe("assistant-1");
+    expect(deliveredMessages[1].body.chatId).toBe("chat-456");
   });
 
-  test("sweepExpiredGuardianActions does nothing when no expired requests exist", async () => {
-    const convId = "conv-sweep-3";
-    ensureConversation(convId);
-
-    const session = createCallSession({
-      conversationId: convId,
-      provider: "twilio",
-      fromNumber: "+15550001111",
-      toNumber: "+15550002222",
-    });
-    const pq = createPendingQuestion(session.id, "Still valid?");
-
-    // Request that expires in the future
-    const request = createGuardianActionRequest({
-      kind: "ask_guardian",
-      sourceChannel: "phone",
-      sourceConversationId: convId,
-      callSessionId: session.id,
-      pendingQuestionId: pq.id,
-      questionText: pq.questionText,
-      expiresAt: Date.now() + 60_000, // expires in 60s
-    });
-
-    await sweepExpiredGuardianActions();
-
-    const updatedRequest = getGuardianActionRequest(request.id);
-    expect(updatedRequest!.status).toBe("pending");
-    expect(getPendingQuestion(session.id)).not.toBeNull();
-  });
-
-  test("sweepExpiredGuardianActions sends external channel expiry notices for sent deliveries", async () => {
-    const convId = "conv-sweep-4";
-    ensureConversation(convId);
-
-    const session = createCallSession({
-      conversationId: convId,
-      provider: "twilio",
-      fromNumber: "+15550001111",
-      toNumber: "+15550002222",
-    });
-    const pq = createPendingQuestion(session.id, "External question?");
-
-    const request = createGuardianActionRequest({
-      kind: "ask_guardian",
-      sourceChannel: "phone",
-      sourceConversationId: convId,
-      callSessionId: session.id,
-      pendingQuestionId: pq.id,
-      questionText: pq.questionText,
-      expiresAt: Date.now() - 5_000,
-    });
-
-    const delivery = createGuardianActionDelivery({
-      requestId: request.id,
-      destinationChannel: "telegram",
-      destinationChatId: "chat-123",
-    });
-    updateDeliveryStatus(delivery.id, "sent");
-
-    await sweepExpiredGuardianActions();
-
-    // Wait for the fire-and-forget async delivery to complete
-    await new Promise((resolve) => setTimeout(resolve, 50));
-
-    // The external delivery should trigger an HTTP POST to the gateway
-    expect(deliveredMessages.length).toBeGreaterThanOrEqual(1);
-  });
-
-  test("sweepExpiredGuardianActions skips failed deliveries", async () => {
-    const convId = "conv-sweep-5";
-    ensureConversation(convId);
-
-    const session = createCallSession({
-      conversationId: convId,
-      provider: "twilio",
-      fromNumber: "+15550001111",
-      toNumber: "+15550002222",
-    });
-    const pq = createPendingQuestion(session.id, "Skip this?");
-
-    const request = createGuardianActionRequest({
-      kind: "ask_guardian",
-      sourceChannel: "phone",
-      sourceConversationId: convId,
-      callSessionId: session.id,
-      pendingQuestionId: pq.id,
-      questionText: pq.questionText,
-      expiresAt: Date.now() - 5_000,
-    });
-
-    const delivery = createGuardianActionDelivery({
-      requestId: request.id,
-      destinationChannel: "telegram",
-      destinationChatId: "chat-456",
-    });
-    updateDeliveryStatus(delivery.id, "failed", "Network error");
-
-    deliveredMessages.length = 0;
-
-    await sweepExpiredGuardianActions();
+  test("skips deliveries that are not sent or pending", async () => {
+    await sendGuardianExpiryNotices(
+      [
+        makeDelivery({ status: "failed" }),
+        makeDelivery({ id: "d2", status: "expired" }),
+      ],
+      "assistant-1",
+    );
 
-    // Should NOT have sent an expiry notice for a failed delivery
     expect(deliveredMessages).toHaveLength(0);
   });
 
-  test("startGuardianActionSweep and stopGuardianActionSweep manage timer", () => {
-    startGuardianActionSweep();
-    // Calling start again should be a no-op (idempotent)
-    startGuardianActionSweep();
+  test("adds an expiry message to vellum guardian conversations", async () => {
+    ensureConversation("guardian-conv");
+
+    await sendGuardianExpiryNotices(
+      [
+        makeDelivery({
+          destinationChannel: "vellum",
+          destinationConversationId: "guardian-conv",
+          destinationChatId: null,
+        }),
+      ],
+      "assistant-1",
+    );
 
-    stopGuardianActionSweep();
-    // Calling stop again should be safe
-    stopGuardianActionSweep();
+    expect(deliveredMessages).toHaveLength(0);
+    const db = getDb();
+    const rows = db.select().from(messages).all();
+    expect(rows).toHaveLength(1);
+    expect(rows[0].conversationId).toBe("guardian-conv");
+    expect(rows[0].content).toContain("expired");
   });
 });

package/src/__tests__/guardian-routing-invariants.test.ts

@@ -45,12 +45,14 @@ import {
 } from "../memory/canonical-guardian-store.js";
 import { getDb } from "../memory/db-connection.js";
 import { initializeDb } from "../memory/db-init.js";
+import { processGuardianDecision } from "../runtime/guardian-action-service.js";
 import { GUARDIAN_DECISION_ACTIONS } from "../runtime/guardian-decision-types.js";
 import {
   type GuardianReplyContext,
   routeGuardianReply,
 } from "../runtime/guardian-reply-router.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
+import { parseCallbackData } from "../runtime/routes/channel-route-shared.js";
 import { listGuardianDecisionPrompts } from "../runtime/routes/guardian-action-routes.js";
 
 initializeDb();
@@ -168,6 +170,12 @@ describe("routing invariant: all decision paths reference applyCanonicalGuardian
       path: "runtime/routes/guardian-action-routes.ts",
       symbols: ["processGuardianDecision"],
     },
+    // Surface action route handler (Vellum in-app card buttons) — intercepts
+    // apr:* action IDs and routes through processGuardianDecision
+    {
+      path: "runtime/routes/surface-action-routes.ts",
+      symbols: ["processGuardianDecision"],
+    },
     // Shared service where processGuardianDecision is defined — must route
     // through the canonical primitive to complete the chain:
     // entrypoint → processGuardianDecision → applyCanonicalGuardianDecision
@@ -1941,3 +1949,133 @@ describe("routing invariant: kind-specific action sets in prompt mapping", () =>
     expect(actionIds).not.toContain("approve_conversation");
   });
 });
+
+// ===========================================================================
+// SECTION 11: Surface action → access request approval routing
+// ===========================================================================
+
+describe("routing invariant: surface action apr:* buttons route through canonical primitive", () => {
+  beforeEach(() => resetTables());
+
+  test("parseCallbackData extracts requestId and action from apr: action IDs", () => {
+    const result = parseCallbackData(
+      "apr:access-req-test-slack-U123-1700000000:approve_once",
+      "vellum",
+    );
+    expect(result).not.toBeNull();
+    expect(result!.requestId).toBe("access-req-test-slack-U123-1700000000");
+    expect(result!.action).toBe("approve_once");
+    expect(result!.source).toBe("vellum_surface");
+  });
+
+  test("parseCallbackData returns vellum_surface source for vellum channel", () => {
+    const result = parseCallbackData("apr:req-1:reject", "vellum");
+    expect(result).not.toBeNull();
+    expect(result!.source).toBe("vellum_surface");
+  });
+
+  test("processGuardianDecision approves access_request from vellum surface", async () => {
+    const requestId = `access-req-test-slack-U123-${Date.now()}`;
+    createCanonicalGuardianRequest({
+      id: requestId,
+      kind: "access_request",
+      sourceType: "channel",
+      sourceChannel: "slack",
+      conversationId: "conv-surface-test",
+      requesterExternalUserId: "U123",
+      requesterChatId: "D456",
+      guardianExternalUserId: "guardian-1",
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
+      toolName: "ingress_access_request",
+      expiresAt: Date.now() + 60_000,
+    });
+
+    const result = await processGuardianDecision({
+      requestId,
+      action: "approve_once",
+      channel: "vellum",
+      actorContext: {
+        actorPrincipalId: TEST_PRINCIPAL_ID,
+        guardianPrincipalId: TEST_PRINCIPAL_ID,
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok && "applied" in result) {
+      expect(result.applied).toBe(true);
+    }
+
+    const resolved = getCanonicalGuardianRequest(requestId);
+    expect(resolved!.status).toBe("approved");
+  });
+
+  test("processGuardianDecision denies access_request from vellum surface", async () => {
+    const requestId = `access-req-test-slack-U789-${Date.now()}`;
+    createCanonicalGuardianRequest({
+      id: requestId,
+      kind: "access_request",
+      sourceType: "channel",
+      sourceChannel: "slack",
+      conversationId: "conv-surface-deny",
+      requesterExternalUserId: "U789",
+      requesterChatId: "D012",
+      guardianExternalUserId: "guardian-1",
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
+      toolName: "ingress_access_request",
+      expiresAt: Date.now() + 60_000,
+    });
+
+    const result = await processGuardianDecision({
+      requestId,
+      action: "reject",
+      channel: "vellum",
+      actorContext: {
+        actorPrincipalId: TEST_PRINCIPAL_ID,
+        guardianPrincipalId: TEST_PRINCIPAL_ID,
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok && "applied" in result) {
+      expect(result.applied).toBe(true);
+    }
+
+    const resolved = getCanonicalGuardianRequest(requestId);
+    expect(resolved!.status).toBe("denied");
+  });
+
+  test("principal mismatch rejects surface action decision", async () => {
+    const requestId = `access-req-test-slack-U999-${Date.now()}`;
+    createCanonicalGuardianRequest({
+      id: requestId,
+      kind: "access_request",
+      sourceType: "channel",
+      sourceChannel: "slack",
+      conversationId: "conv-surface-mismatch",
+      requesterExternalUserId: "U999",
+      requesterChatId: "D345",
+      guardianExternalUserId: "guardian-1",
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
+      toolName: "ingress_access_request",
+      expiresAt: Date.now() + 60_000,
+    });
+
+    const result = await processGuardianDecision({
+      requestId,
+      action: "approve_once",
+      channel: "vellum",
+      actorContext: {
+        actorPrincipalId: "wrong-principal",
+        guardianPrincipalId: "wrong-principal",
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok && "applied" in result) {
+      expect(result.applied).toBe(false);
+    }
+
+    const req = getCanonicalGuardianRequest(requestId);
+    expect(req!.status).toBe("pending");
+  });
+});

package/src/__tests__/helpers/channel-test-adapter.ts

@@ -64,7 +64,6 @@ mock.module("../../daemon/approval-generators.js", () => ({
 import type {
   ApprovalConversationGenerator,
   ApprovalCopyGenerator,
-  GuardianActionCopyGenerator,
   MessageProcessor,
 } from "../../runtime/http-types.js";
 import {
@@ -111,7 +110,6 @@ export async function handleChannelInbound(
   _assistantId?: string,
   _approvalCopyGenerator?: ApprovalCopyGenerator,
   _approvalConversationGenerator?: ApprovalConversationGenerator,
-  _guardianActionCopyGenerator?: GuardianActionCopyGenerator,
 ): Promise<Response> {
   const body = await req.json();
   return wrapHandler(() => _handleChannelInbound({ body }));

package/src/__tests__/list-messages-hidden-metadata.test.ts

@@ -33,6 +33,10 @@ import {
 } from "../memory/conversation-crud.js";
 import { getDb } from "../memory/db-connection.js";
 import { initializeDb } from "../memory/db-init.js";
+import {
+  MEMORY_RETROSPECTIVE_FORK_SOURCE,
+  MEMORY_RETROSPECTIVE_INSTRUCTION_KIND,
+} from "../memory/memory-retrospective-constants.js";
 import { messages } from "../memory/schema.js";
 import { handleListMessages } from "../runtime/routes/conversation-routes.js";
 
@@ -334,4 +338,99 @@ describe("handleListMessages metadata.hidden filtering", () => {
     expect(latest.hasMore).toBe(false);
     expect(latest.oldestTimestamp).not.toBeNull();
   });
+
+  test("fork retrospective conversations expose the hidden instruction and keep the review as its own turn", async () => {
+    const conv = createConversation({
+      source: MEMORY_RETROSPECTIVE_FORK_SOURCE,
+    });
+    await addMessage(
+      conv.id,
+      "user",
+      JSON.stringify([{ type: "text", text: "source question" }]),
+    );
+    await addMessage(
+      conv.id,
+      "assistant",
+      JSON.stringify([{ type: "text", text: "source answer" }]),
+    );
+    await addMessage(
+      conv.id,
+      "user",
+      JSON.stringify([
+        { type: "text", text: "background memory pass instruction" },
+      ]),
+      {
+        metadata: { kind: MEMORY_RETROSPECTIVE_INSTRUCTION_KIND, hidden: true },
+      },
+    );
+    await addMessage(
+      conv.id,
+      "assistant",
+      JSON.stringify([{ type: "text", text: "retrospective review" }]),
+    );
+
+    const response = handleListMessages({
+      queryParams: { conversationId: conv.id },
+    });
+    const body = response as { messages: MessagePayload[] };
+
+    // The hidden instruction is shown, and because it sits between the two
+    // assistant rows they do NOT merge — the review stands as its own turn.
+    expect(body.messages.map((m) => m.role)).toEqual([
+      "user",
+      "assistant",
+      "user",
+      "assistant",
+    ]);
+    expect(plainText(body.messages[1])).toBe("source answer");
+    expect(plainText(body.messages[2])).toContain(
+      "background memory pass instruction",
+    );
+    expect(plainText(body.messages[3])).toBe("retrospective review");
+  });
+
+  test("non-fork conversations still hide the retrospective instruction (relaxation is fork-scoped)", async () => {
+    const conv = createConversation();
+    await addMessage(
+      conv.id,
+      "user",
+      JSON.stringify([{ type: "text", text: "source question" }]),
+    );
+    await addMessage(
+      conv.id,
+      "assistant",
+      JSON.stringify([{ type: "text", text: "source answer" }]),
+    );
+    await addMessage(
+      conv.id,
+      "user",
+      JSON.stringify([
+        { type: "text", text: "background memory pass instruction" },
+      ]),
+      {
+        metadata: { kind: MEMORY_RETROSPECTIVE_INSTRUCTION_KIND, hidden: true },
+      },
+    );
+    await addMessage(
+      conv.id,
+      "assistant",
+      JSON.stringify([{ type: "text", text: "retrospective review" }]),
+    );
+
+    const response = handleListMessages({
+      queryParams: { conversationId: conv.id },
+    });
+    const body = response as { messages: MessagePayload[] };
+
+    // Instruction stays hidden for non-retrospective conversations; the review
+    // (a normal assistant message) is still returned.
+    expect(
+      body.messages.some((m) =>
+        plainText(m).includes("background memory pass instruction"),
+      ),
+    ).toBe(false);
+    expect(
+      body.messages.some((m) => plainText(m).includes("retrospective review")),
+    ).toBe(true);
+  });
 });