@vellumai/assistant 0.10.0 → 0.10.1-dev.202606240317.ea25efe

package/src/approvals/guardian-decision-primitive.ts

@@ -1,20 +1,17 @@
 /**
- * Unified guardian decision primitive.
+ * Canonical guardian decision primitive.
  *
- * All guardian decision entrypoints (callback buttons, conversational engine,
- * legacy parser, requester self-cancel) call through this module instead of
- * inlining the decision-application logic.  This centralizes:
+ * `applyCanonicalGuardianDecision` is the single write path for guardian
+ * decisions. It operates on the `canonical_guardian_requests` table and
+ * dispatches to kind-specific resolvers:
  *
- *   1. Identity validation (actor must match assigned guardian)
- *   2. Approval-info capture before the pending interaction is consumed
- *   3. Atomic decision application via `handleChannelDecision`
- *   4. Guardian approval record update
- *   5. Scoped grant minting on approve
- *
- * The canonical path (`applyCanonicalGuardianDecision`) adds:
- *   6. Canonical request lookup and status validation
- *   7. CAS resolution via `resolveCanonicalGuardianRequest`
- *   8. Kind-specific resolver dispatch via the resolver registry
+ *   1. Canonical request lookup and status validation
+ *   2. Principal-based identity authorization
+ *   3. Expiry check
+ *   4. CAS resolution via `resolveCanonicalGuardianRequest` (first-writer-wins)
+ *   5. Kind-specific resolver dispatch via the resolver registry
+ *   6. Scoped grant minting on approve for requests carrying tool metadata
+ *   7. Cross-surface approval-card withdrawal
  *
  * Security invariants enforced here:
  *   - Decision authorization is purely principal-based:
@@ -24,28 +21,13 @@
  *   - Scoped grant minting only on explicit approve for requests with tool metadata
  */
 
-import type { ChannelId } from "../channels/types.js";
 import {
   type CanonicalGuardianRequest,
   type CanonicalRequestStatus,
   getCanonicalGuardianRequest,
   resolveCanonicalGuardianRequest,
 } from "../memory/canonical-guardian-store.js";
-import {
-  type GuardianApprovalRequest,
-  updateApprovalDecision,
-} from "../memory/guardian-approvals.js";
-import type {
-  ApprovalAction,
-  ApprovalDecisionResult,
-} from "../runtime/channel-approval-types.js";
-import {
-  getApprovalInfoByConversation,
-  handleChannelDecision,
-  type PendingApprovalInfo,
-} from "../runtime/channel-approvals.js";
-import type { ApplyGuardianDecisionResult } from "../runtime/guardian-decision-types.js";
-import { computeToolApprovalDigest } from "../security/tool-approval-digest.js";
+import type { ApprovalAction } from "../runtime/channel-approval-types.js";
 import { getLogger } from "../util/logger.js";
 import { mintGrantFromDecision } from "./approval-primitive.js";
 import { withdrawGuardianRequestCards } from "./guardian-card-withdrawal.js";
@@ -71,186 +53,7 @@ function computeGrantExpiresAt(_action: ApprovalAction): number {
 }
 
 // ---------------------------------------------------------------------------
-// Scoped grant minting
-// ---------------------------------------------------------------------------
-
-/**
- * Mint a `tool_signature` scoped grant when a guardian approves a tool-approval
- * request.  Only mints when the approval info contains a tool invocation with
- * input (so we can compute the input digest).  Informational ASK_GUARDIAN
- * requests that lack tool input are skipped.
- *
- * Fails silently on error -- grant minting is best-effort and must never block
- * the approval flow.
- */
-function tryMintToolApprovalGrant(params: {
-  approvalInfo: PendingApprovalInfo;
-  approval: GuardianApprovalRequest;
-  decisionChannel: ChannelId;
-  guardianExternalUserId: string;
-  effectiveAction: ApprovalAction;
-}): void {
-  const {
-    approvalInfo,
-    approval,
-    decisionChannel,
-    guardianExternalUserId,
-    effectiveAction,
-  } = params;
-
-  if (!approvalInfo.toolName) {
-    return;
-  }
-
-  let inputDigest: string;
-  try {
-    inputDigest = computeToolApprovalDigest(
-      approvalInfo.toolName,
-      approvalInfo.input,
-    );
-  } catch (err) {
-    log.error(
-      {
-        err,
-        toolName: approvalInfo.toolName,
-        conversationId: approval.conversationId,
-      },
-      "Failed to compute tool approval digest for grant minting (non-fatal)",
-    );
-    return;
-  }
-
-  const result = mintGrantFromDecision({
-    scopeMode: "tool_signature",
-    toolName: approvalInfo.toolName,
-    inputDigest,
-    requestChannel: approval.channel,
-    decisionChannel,
-    executionChannel: null,
-    conversationId: approval.conversationId,
-    callSessionId: null,
-    guardianExternalUserId,
-    requesterExternalUserId: approval.requesterExternalUserId,
-    expiresAt: computeGrantExpiresAt(effectiveAction),
-  });
-
-  if (result.ok) {
-    log.info(
-      {
-        toolName: approvalInfo.toolName,
-        conversationId: approval.conversationId,
-      },
-      "Minted scoped approval grant for guardian tool-approval decision",
-    );
-  } else {
-    log.error(
-      {
-        reason: result.reason,
-        toolName: approvalInfo.toolName,
-        conversationId: approval.conversationId,
-      },
-      "Failed to mint scoped approval grant (non-fatal)",
-    );
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Apply guardian decision (unified primitive)
-// ---------------------------------------------------------------------------
-
-export interface ApplyGuardianDecisionParams {
-  /** The guardian approval record from the store. */
-  approval: GuardianApprovalRequest;
-  /** The parsed decision (action + source + optional requestId). */
-  decision: ApprovalDecisionResult;
-  /** Principal ID of the actor making the decision (undefined in callback/interception paths without JWT/auth context). */
-  actorPrincipalId: string | undefined;
-  /** Channel-native external user ID of the deciding actor (Telegram user ID, phone, etc.). */
-  actorExternalUserId: string | undefined;
-  /** Channel the decision arrived on. */
-  actorChannel: ChannelId;
-  /** Optional decision context passed to handleChannelDecision. */
-  decisionContext?: string;
-}
-
-/**
- * Apply a guardian decision through the unified primitive.
- *
- * This function centralizes the core logic that was previously duplicated
- * across callback, conversational engine, legacy parser, and requester
- * self-cancel paths:
- *
- *   1. Capture pending approval info before resolution
- *   2. Apply the decision atomically via `handleChannelDecision`
- *   3. Update the guardian approval record
- *   4. Mint a scoped grant on approve
- *
- * Returns a structured result so callers can handle stale/race outcomes.
- */
-export async function applyGuardianDecision(
-  params: ApplyGuardianDecisionParams,
-): Promise<ApplyGuardianDecisionResult> {
-  const {
-    approval,
-    decision,
-    actorPrincipalId,
-    actorExternalUserId,
-    actorChannel,
-    decisionContext,
-  } = params;
-
-  // Capture pending approval info before handleChannelDecision resolves
-  // (and removes) the pending interaction. Needed for grant minting.
-  const approvalInfo = getApprovalInfoByConversation(approval.conversationId);
-  const matchedInfo = decision.requestId
-    ? approvalInfo.find((a) => a.requestId === decision.requestId)
-    : approvalInfo[0];
-
-  // Apply the decision to the underlying session
-  const result = await handleChannelDecision(
-    approval.conversationId,
-    decision,
-    decisionContext,
-  );
-
-  if (!result.applied) {
-    return {
-      applied: false,
-      reason: "stale",
-      requestId: decision.requestId,
-    };
-  }
-
-  // Update the guardian approval request record
-  const approvalStatus =
-    decision.action === "reject" ? ("denied" as const) : ("approved" as const);
-  updateApprovalDecision(approval.id, {
-    status: approvalStatus,
-    decidedByExternalUserId: actorExternalUserId ?? actorPrincipalId,
-  });
-
-  // Mint a scoped grant when a guardian approves a tool-approval request.
-  // Skip when neither actor identity is available -- minting a grant without
-  // a known guardian identity is meaningless (e.g. requester self-cancel).
-  const effectiveGuardianId = actorExternalUserId ?? actorPrincipalId;
-  if (decision.action !== "reject" && matchedInfo && effectiveGuardianId) {
-    tryMintToolApprovalGrant({
-      approvalInfo: matchedInfo,
-      approval,
-      decisionChannel: actorChannel,
-      guardianExternalUserId: effectiveGuardianId,
-      effectiveAction: decision.action,
-    });
-  }
-
-  return {
-    applied: true,
-    requestId: result.requestId,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Consolidated canonical grant minting
+// Canonical grant minting
 // ---------------------------------------------------------------------------
 
 /**

package/src/approvals/guardian-request-resolvers.ts

@@ -24,6 +24,10 @@ import {
   isNotificationSourceChannel,
   type NotificationSourceChannel,
 } from "../notifications/signal.js";
+import type {
+  TrustedContactDecisionPayload,
+  TrustedContactVerificationSentPayload,
+} from "../notifications/trusted-contact-payloads.js";
 import type { UserDecision } from "../permissions/types.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../runtime/assistant-scope.js";
 import type { ApprovalAction } from "../runtime/channel-approval-types.js";
@@ -136,6 +140,35 @@ function buildRequesterChannelNotice(params: {
   return payload;
 }
 
+/**
+ * Emit the `verification_sent` lifecycle signal on guardian approve.
+ *
+ * Always `visibleInSourceNow: true` so the notification pipeline suppresses
+ * delivery — the guardian already received the code (on-channel via the channel
+ * reply, off-channel via the inline reply text), so this records the lifecycle
+ * transition without sending a redundant "approved" message. It also stands in
+ * for `guardian_decision` on approve (which would notify), so the pipeline
+ * doesn't announce approval before verification.
+ */
+function emitVerificationSentSignal(
+  payload: TrustedContactVerificationSentPayload,
+  conversationId: string | null | undefined,
+): void {
+  void emitNotificationSignal({
+    sourceEventName: "ingress.trusted_contact.verification_sent",
+    sourceChannel: payload.sourceChannel,
+    sourceContextId: conversationId ?? "",
+    attentionHints: {
+      requiresAction: false,
+      urgency: "low",
+      isAsyncBackground: true,
+      visibleInSourceNow: true,
+    },
+    contextPayload: payload,
+    dedupeKey: `trusted-contact:verification-sent:${payload.verificationSessionId}`,
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -418,15 +451,11 @@ const pendingQuestionResolver: GuardianRequestResolver = {
  * Instead, they create identity-bound verification sessions so the requester
  * can prove their identity.
  *
- * This resolver directly mints the verification session on approve rather
- * than going through handleAccessRequestDecision -> resolveApprovalRequest,
- * because canonical requests have no legacy channel_guardian_approval_requests
- * row, making the resolveApprovalRequest step a no-op that returns 'stale'.
+ * On approve, the resolver mints the verification session directly.
  *
  * When a `channelDeliveryContext` is provided (channel path), the resolver
  * also delivers the verification code to the guardian, notifies the requester,
- * and emits lifecycle notification signals — mirroring the legacy
- * handleAccessRequestApproval side effects.
+ * and emits lifecycle notification signals.
  *
  * For deny: notifies the requester and emits denial lifecycle signals when
  * channelDeliveryContext is available.
@@ -500,14 +529,14 @@ const accessRequestResolver: GuardianRequestResolver = {
           );
         }
 
-        const deniedPayload = {
+        const deniedPayload: TrustedContactDecisionPayload = {
           sourceChannel: channel,
           requesterExternalUserId,
           requesterChatId,
           decidedByExternalUserId,
           requesterDisplayName,
           decidedByDisplayName,
-          decision: "denied" as const,
+          decision: "denied",
         };
 
         void emitNotificationSignal({
@@ -782,20 +811,10 @@ const accessRequestResolver: GuardianRequestResolver = {
         }
       }
 
-      // Emit verification_sent with visibleInSourceNow=true so the notification
-      // pipeline suppresses delivery — the guardian already received the code.
+      // Record the verification_sent lifecycle transition (delivery suppressed).
       if (codeDelivered) {
-        void emitNotificationSignal({
-          sourceEventName: "ingress.trusted_contact.verification_sent",
-          sourceChannel: channel,
-          sourceContextId: request.conversationId ?? "",
-          attentionHints: {
-            requiresAction: false,
-            urgency: "low",
-            isAsyncBackground: true,
-            visibleInSourceNow: true,
-          },
-          contextPayload: {
+        emitVerificationSentSignal(
+          {
             sourceChannel: channel,
             requesterExternalUserId,
             requesterChatId,
@@ -803,48 +822,75 @@ const accessRequestResolver: GuardianRequestResolver = {
             decidedByDisplayName,
             verificationSessionId: session.sessionId,
           },
-          dedupeKey: `trusted-contact:verification-sent:${session.sessionId}`,
-        });
+          request.conversationId,
+        );
       }
-    } else if (desktopDeliverUrl && requesterChatId) {
-      // Guardian decided off-channel (e.g. desktop) but the requester is on a
-      // deliverable channel. On Slack, DM the code directly (parity with the
-      // on-channel path); otherwise fall back to the courier notice.
-      const requesterCodeDelivered =
-        channel === "slack" && requesterExternalUserId
-          ? await deliverVerificationCodeToSlackRequester({
-              replyCallbackUrl: desktopDeliverUrl,
-              requesterExternalUserId,
-              verificationCode: session.secret,
-              assistantId,
-            })
-          : false;
-
-      if (requesterCodeDelivered) {
-        requesterNotified = true;
-      } else {
-        // For Slack, route to DM via requesterExternalUserId (user ID) instead
-        // of requesterChatId (channel ID) to avoid posting in public channels.
-        const targetChatId =
+    } else {
+      // Guardian decided off-channel (e.g. desktop). The guardian receives the
+      // verification code inline via `guardianReplyText` regardless of the
+      // requester's channel, so the lifecycle transition is recorded for every
+      // off-channel approve — including channels with no deliverable callback
+      // (e.g. email), where the requester cannot be auto-notified here.
+      if (desktopDeliverUrl && requesterChatId) {
+        // The requester is on a deliverable channel. On Slack, DM the code
+        // directly (parity with the on-channel path); otherwise fall back to
+        // the courier notice.
+        const requesterCodeDelivered =
           channel === "slack" && requesterExternalUserId
-            ? requesterExternalUserId
-            : requesterChatId;
-        try {
-          await deliverChannelReply(desktopDeliverUrl, {
-            chatId: targetChatId,
-            text:
-              "Your access request has been approved! " +
-              "Please enter the 6-digit verification code you receive from the guardian.",
-            assistantId,
-          });
+            ? await deliverVerificationCodeToSlackRequester({
+                replyCallbackUrl: desktopDeliverUrl,
+                requesterExternalUserId,
+                verificationCode: session.secret,
+                assistantId,
+              })
+            : false;
+
+        if (requesterCodeDelivered) {
           requesterNotified = true;
-        } catch (err) {
-          log.error(
-            { err, requesterChatId },
-            "Failed to notify requester of access request approval (desktop decision path)",
-          );
+        } else {
+          // For Slack, route to DM via requesterExternalUserId (user ID)
+          // instead of requesterChatId (channel ID) to avoid posting in public
+          // channels.
+          const targetChatId =
+            channel === "slack" && requesterExternalUserId
+              ? requesterExternalUserId
+              : requesterChatId;
+          try {
+            await deliverChannelReply(desktopDeliverUrl, {
+              chatId: targetChatId,
+              text:
+                "Your access request has been approved! " +
+                "Please enter the 6-digit verification code you receive from the guardian.",
+              assistantId,
+            });
+            requesterNotified = true;
+          } catch (err) {
+            log.error(
+              { err, requesterChatId },
+              "Failed to notify requester of access request approval (desktop decision path)",
+            );
+          }
         }
       }
+
+      // Record the verification_sent lifecycle transition for every off-channel
+      // approve. The session is minted and the guardian has the code via
+      // `guardianReplyText` regardless of whether (or how) the requester was
+      // notified — mirroring the on-channel branch, which keys off guardian
+      // receipt rather than requester delivery. Without this, approves on
+      // channels with no deliverable callback (e.g. email) would silently skip
+      // the audit/lifecycle record.
+      emitVerificationSentSignal(
+        {
+          sourceChannel: channel,
+          requesterExternalUserId,
+          requesterChatId,
+          requesterDisplayName,
+          decidedByDisplayName,
+          verificationSessionId: session.sessionId,
+        },
+        request.conversationId,
+      );
     }
 
     const verificationReplyText = requesterNotified

package/src/background-wake/wake-intent-hooks.test.ts

@@ -102,7 +102,7 @@ const { getDb } = await import("../memory/db-connection.js");
 const { createSchedule, deleteSchedule, updateSchedule } =
   await import("../schedule/schedule-store.js");
 
-initializeDb();
+await initializeDb();
 
 describe("background wake intent publisher hooks", () => {
   beforeEach(() => {

package/src/calls/__tests__/inbound-trust-reader.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Tests for the gateway-backed per-actor inbound trust reader.
+ *
+ * The reader returns `null` on ANY failure (transport failure, undefined,
+ * malformed shape, thrown error); the Combo 9/10 consumer decides fail-open
+ * vs fail-closed. These tests pin that contract plus the forwarded method +
+ * params.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ── Controllable IPC mock ────────────────────────────────────────────────────
+
+type IpcHandler = (params?: Record<string, unknown>) => unknown;
+
+const ipcHandlers = new Map<string, IpcHandler>();
+const ipcCallLog: Array<{
+  method: string;
+  params?: Record<string, unknown>;
+  timeoutMs?: number;
+}> = [];
+
+mock.module("../../ipc/gateway-client.js", () => ({
+  ipcCall: async (
+    method: string,
+    params?: Record<string, unknown>,
+    timeoutMs?: number,
+  ) => {
+    ipcCallLog.push({ method, params, timeoutMs });
+    const handler = ipcHandlers.get(method);
+    return handler ? handler(params) : undefined;
+  },
+  ipcCallPersistent: async () => undefined,
+  resetPersistentClient: () => {},
+}));
+
+import type { TrustVerdict } from "@vellumai/gateway-client";
+
+import { getInboundTrustVerdict } from "../inbound-trust-reader.js";
+
+const METHOD = "resolve_inbound_trust";
+
+const VALID_VERDICT = {
+  trustClass: "trusted_contact",
+  canonicalSenderId: "U_MEMBER",
+  contactId: "c-member",
+  status: "active",
+} satisfies TrustVerdict;
+
+describe("getInboundTrustVerdict", () => {
+  beforeEach(() => {
+    ipcHandlers.clear();
+    ipcCallLog.length = 0;
+  });
+
+  test("returns the gateway-resolved verdict on a valid response", async () => {
+    ipcHandlers.set(METHOD, () => ({ verdict: VALID_VERDICT }));
+
+    const verdict = await getInboundTrustVerdict({
+      channelType: "telegram",
+      actorExternalId: "U_MEMBER",
+    });
+
+    expect(verdict).toEqual(VALID_VERDICT);
+  });
+
+  test("forwards the correct method, params, and timeout to ipcCall", async () => {
+    ipcHandlers.set(METHOD, () => ({ verdict: VALID_VERDICT }));
+
+    const input = {
+      channelType: "telegram" as const,
+      actorExternalId: "U_MEMBER",
+    };
+    await getInboundTrustVerdict(input);
+
+    const call = ipcCallLog.find((c) => c.method === METHOD);
+    expect(call?.params).toEqual(input);
+    expect(call?.timeoutMs).toBe(2_000);
+  });
+
+  test("returns null when IPC transport fails (undefined)", async () => {
+    ipcHandlers.set(METHOD, () => undefined);
+    expect(
+      await getInboundTrustVerdict({ channelType: "telegram" }),
+    ).toBeNull();
+  });
+
+  test("returns null for a malformed verdict shape", async () => {
+    ipcHandlers.set(METHOD, () => ({ verdict: { trustClass: "bogus" } }));
+    expect(
+      await getInboundTrustVerdict({ channelType: "telegram" }),
+    ).toBeNull();
+  });
+
+  test("returns null when the verdict field is missing", async () => {
+    ipcHandlers.set(METHOD, () => ({}));
+    expect(
+      await getInboundTrustVerdict({ channelType: "telegram" }),
+    ).toBeNull();
+  });
+
+  test("returns null when the IPC call throws", async () => {
+    ipcHandlers.set(METHOD, () => {
+      throw new Error("socket exploded");
+    });
+    expect(
+      await getInboundTrustVerdict({ channelType: "telegram" }),
+    ).toBeNull();
+  });
+});