@vellumai/assistant 0.9.0 → 0.10.0-staging.2

package/src/notifications/approval-card-data.ts

@@ -0,0 +1,333 @@
+/**
+ * Unified resolver + renderer for guardian approval card seed content.
+ *
+ * `contextPayload` resolves into a typed {@link ApprovalCardData} discriminated
+ * union, then renders into Surface `[ui_surface, text]` blocks via the shared
+ * {@link buildApprovalCardBlocks}. Access-request and tool-approval
+ * notifications share this single entry point, which parses and shapes the raw
+ * payload into card data.
+ *
+ * The Surface card data shape matches `CardSurfaceData` from
+ * `daemon/message-types/surfaces.ts`. Actions use the canonical
+ * `apr:<requestId>:<action>` callback format consumed by
+ * `surface-action-routes.ts` → `processGuardianDecision`.
+ */
+
+import {
+  buildAccessRequestCardView,
+  buildAccessRequestContractText,
+  parseAccessRequestPayload,
+} from "./access-request-copy.js";
+import {
+  type ApprovalCardParams,
+  buildApprovalCardBlocks,
+} from "./approval-card-builder.js";
+import {
+  buildGuardianRequestCodeInstruction,
+  type GuardianQuestionPayload,
+  type LenientToolApprovalPayload,
+  LenientToolApprovalPayloadSchema,
+  parseGuardianQuestionPayload,
+  resolveGuardianInstructionModeFromFields,
+  resolveGuardianInstructionModeFromPayload,
+} from "./guardian-question-mode.js";
+import { nonEmpty, sanitizeIdentityField } from "./notification-utils.js";
+
+// ── Surface ids ──────────────────────────────────────────────────────────────
+
+/**
+ * `surfaceId` prefixes for the in-app approval cards. The full id is
+ * `${prefix}-${requestId}` (see {@link buildApprovalCardBlocks}). These are the
+ * single source of truth for the prefix, shared by the card builders below and
+ * by {@link approvalCardSurfaceId} so the withdrawal path can recompute the id.
+ */
+const ACCESS_REQUEST_SURFACE_PREFIX = "access-request";
+const TOOL_APPROVAL_SURFACE_PREFIX = "tool-approval";
+
+/**
+ * Resolve the `ui_surface` id for a guardian request's in-app approval card
+ * from its kind, or `null` for kinds that never render an approval card.
+ *
+ * The card is rendered once at notification time; when the request is later
+ * resolved from a different surface the withdrawal path recomputes the id here
+ * to complete that card. Keeping this beside the builders ensures the two stay
+ * in lockstep.
+ */
+export function approvalCardSurfaceId(
+  kind: string,
+  requestId: string,
+): string | null {
+  switch (kind) {
+    case "access_request":
+      return `${ACCESS_REQUEST_SURFACE_PREFIX}-${requestId}`;
+    case "tool_approval":
+    case "tool_grant_request":
+    case "pending_question":
+      return `${TOOL_APPROVAL_SURFACE_PREFIX}-${requestId}`;
+    default:
+      return null;
+  }
+}
+
+// ── Typed card data ─────────────────────────────────────────────────────────
+
+/** Resolved card data for an access-request notification. */
+export interface AccessRequestCardData {
+  kind: "access_request";
+  card: ApprovalCardParams;
+}
+
+/** Resolved card data for a tool-approval / tool-grant notification. */
+export interface ToolApprovalCardData {
+  kind: "tool_approval";
+  card: ApprovalCardParams;
+}
+
+/**
+ * Channel-agnostic approval card content, resolved once from `contextPayload`.
+ * The discriminant `kind` lets consumers branch on the approval type without
+ * re-parsing the payload.
+ */
+export type ApprovalCardData = AccessRequestCardData | ToolApprovalCardData;
+
+// ── Access-request resolution ────────────────────────────────────────────────
+
+/** Shape the parsed access-request payload into card params via the view model. */
+function resolveAccessRequestCard(
+  payload: Record<string, unknown>,
+): ApprovalCardParams {
+  const view = buildAccessRequestCardView(parseAccessRequestPayload(payload));
+
+  const metadata: Array<{ label: string; value: string }> = [];
+
+  if (view.username) {
+    metadata.push({
+      label: "Username",
+      value: `@${view.username}`,
+    });
+  }
+
+  if (view.sourceChannel === "slack" && view.conversationExternalId) {
+    metadata.push({
+      label: "Source",
+      value: view.isSlackDm
+        ? "Slack — Direct message"
+        : `Slack — #${view.conversationExternalId}`,
+    });
+  } else if (view.sourceChannel) {
+    metadata.push({ label: "Source", value: view.sourceChannel });
+  }
+
+  const bodyParts: string[] = [];
+
+  if (view.messagePreview) {
+    bodyParts.push(`> "${view.messagePreview}"`);
+  }
+  for (const w of view.warnings) {
+    bodyParts.push(`⚠️ ${w}`);
+  }
+  if (view.messagePermalink) {
+    bodyParts.push(`[View message](${view.messagePermalink})`);
+  }
+
+  const body =
+    bodyParts.length > 0
+      ? bodyParts.join("\n\n")
+      : "No additional context available.";
+
+  return {
+    surfaceIdPrefix: ACCESS_REQUEST_SURFACE_PREFIX,
+    cardTitle: "Access Request",
+    requesterName: view.displayName,
+    subtitle: "Requesting access to the assistant",
+    body,
+    metadata,
+    requestId: view.requestId,
+    fallbackText: buildAccessRequestContractText(payload),
+  };
+}
+
+// ── Tool-approval resolution ─────────────────────────────────────────────────
+
+/**
+ * Determine whether a typed guardian.question payload represents a tool
+ * approval (as opposed to a free-text answer). Uses the canonical mode
+ * resolver in `guardian-question-mode.ts` — the single source of truth
+ * for the requestKind → instructionMode mapping.
+ */
+function isToolApprovalPayload(payload: GuardianQuestionPayload): boolean {
+  const { mode } = resolveGuardianInstructionModeFromPayload(payload);
+  return mode === "approval" && payload.requestKind !== "access_request";
+}
+
+/**
+ * Lenient approval detection for partially-constructed payloads that don't
+ * satisfy the strict discriminated union schema.
+ */
+function isLenientToolApproval(payload: LenientToolApprovalPayload): boolean {
+  const modeResolution = resolveGuardianInstructionModeFromFields(
+    payload.requestKind,
+    payload.toolName,
+  );
+  if (!modeResolution) return false;
+  return (
+    modeResolution.mode === "approval" &&
+    payload.requestKind !== "access_request"
+  );
+}
+
+/** Shape a tool-approval/grant payload (strict or lenient) into card params. */
+function extractToolApprovalCard(
+  p: GuardianQuestionPayload | LenientToolApprovalPayload,
+): ApprovalCardParams {
+  const toolName =
+    ("toolName" in p ? nonEmpty(p.toolName) : undefined) ?? "unknown tool";
+  const rawRequester = nonEmpty(p.requesterIdentifier);
+  const requester = rawRequester
+    ? sanitizeIdentityField(rawRequester)
+    : "Someone";
+
+  const isGrant = p.requestKind === "tool_grant_request";
+
+  const metadata: Array<{ label: string; value: string }> = [];
+  metadata.push({ label: "Tool", value: toolName });
+  const sourceChannel = nonEmpty(p.sourceChannel);
+  if (sourceChannel) {
+    metadata.push({ label: "Source", value: sourceChannel });
+  }
+
+  const body = p.questionText
+    ? `> ${p.questionText}`
+    : "No additional context available.";
+
+  // Fallback text with request-code instructions for older clients.
+  const baseFallback =
+    p.questionText ?? `${requester} is requesting approval to use ${toolName}`;
+  let fallbackText = baseFallback;
+  const requestCode = nonEmpty(p.requestCode);
+  if (requestCode) {
+    const modeResolution = resolveGuardianInstructionModeFromFields(
+      p.requestKind,
+      "toolName" in p ? (p.toolName ?? undefined) : undefined,
+    );
+    const mode = modeResolution?.mode ?? "approval";
+    const instruction = buildGuardianRequestCodeInstruction(
+      requestCode.trim().toUpperCase(),
+      mode,
+    );
+    fallbackText = `${baseFallback}\n\n${instruction}`;
+  }
+
+  return {
+    surfaceIdPrefix: TOOL_APPROVAL_SURFACE_PREFIX,
+    cardTitle: isGrant ? "Tool Grant Request" : "Tool Approval",
+    requesterName: requester,
+    subtitle: isGrant
+      ? "Requesting permission to use this tool"
+      : "Requesting approval to run this tool",
+    body,
+    metadata,
+    requestId: nonEmpty(p.requestId),
+    fallbackText,
+  };
+}
+
+/**
+ * Resolve a guardian.question payload into tool-approval card params, or
+ * `null` when it does not represent a tool approval.
+ *
+ * Tries strict Zod parsing first (full discriminated union), then falls back
+ * to lenient field extraction so cards still render when optional fields are
+ * absent.
+ */
+function resolveToolApprovalCard(
+  payload: Record<string, unknown>,
+): ApprovalCardParams | null {
+  const strict = parseGuardianQuestionPayload(payload);
+  if (strict) {
+    if (!isToolApprovalPayload(strict)) return null;
+    return extractToolApprovalCard(strict);
+  }
+
+  const lenient = LenientToolApprovalPayloadSchema.safeParse(payload);
+  if (!lenient.success) return null;
+  if (!isLenientToolApproval(lenient.data)) return null;
+  return extractToolApprovalCard(lenient.data);
+}
+
+// ── Unified dispatcher + renderer ────────────────────────────────────────────
+
+/**
+ * Resolve a notification's `contextPayload` into typed {@link ApprovalCardData}
+ * based on its source event, or `null` when the signal does not carry a
+ * renderable approval card. Single entry point so each consumer (copy
+ * composition, decision engine) shapes the payload identically.
+ */
+export function resolveApprovalCardData(
+  sourceEventName: string,
+  contextPayload: Record<string, unknown> | undefined,
+): ApprovalCardData | null {
+  if (!contextPayload) return null;
+
+  if (sourceEventName === "ingress.access_request") {
+    return {
+      kind: "access_request",
+      card: resolveAccessRequestCard(contextPayload),
+    };
+  }
+
+  if (sourceEventName === "guardian.question") {
+    const card = resolveToolApprovalCard(contextPayload);
+    return card ? { kind: "tool_approval", card } : null;
+  }
+
+  return null;
+}
+
+/** Render resolved approval card data into Surface `[ui_surface, text]` blocks. */
+export function renderApprovalCardData(data: ApprovalCardData): unknown[] {
+  return buildApprovalCardBlocks(data.card);
+}
+
+// ── Public seed-content builders ─────────────────────────────────────────────
+
+/**
+ * Build structured content blocks for an access-request notification seed
+ * message. Produces a `ui_surface` card block that the web/macOS/iOS apps
+ * render as an interactive card via `SurfaceRouter → CardSurface`, plus a
+ * plain-text fallback block for search, CLI display, and backward-compatible
+ * clients that don't support surfaces.
+ */
+export function buildAccessRequestSeedContentBlocks(
+  payload: Record<string, unknown>,
+): unknown[] {
+  return renderApprovalCardData({
+    kind: "access_request",
+    card: resolveAccessRequestCard(payload),
+  });
+}
+
+/**
+ * Build structured content blocks for a tool approval/grant notification seed
+ * message. Returns `null` when the payload does not represent a tool approval.
+ *
+ * Accepts both strict `GuardianQuestionPayload` (Zod-validated) and raw
+ * `Record<string, unknown>` payloads. For raw payloads, attempts strict
+ * parsing first, then falls back to lenient field extraction so cards
+ * still render when optional fields are absent.
+ */
+export function buildToolApprovalSeedContentBlocks(
+  payload: GuardianQuestionPayload,
+): unknown[] | null;
+export function buildToolApprovalSeedContentBlocks(
+  payload: Record<string, unknown>,
+): unknown[] | null;
+export function buildToolApprovalSeedContentBlocks(
+  payload: GuardianQuestionPayload | Record<string, unknown>,
+): unknown[] | null {
+  const data = resolveApprovalCardData(
+    "guardian.question",
+    payload as Record<string, unknown>,
+  );
+  return data ? renderApprovalCardData(data) : null;
+}

package/src/notifications/broadcaster.ts

@@ -14,7 +14,10 @@ import { v4 as uuid } from "uuid";
 import { getConversation } from "../memory/conversation-crud.js";
 import type { ApprovalUIMetadata } from "../runtime/channel-approval-types.js";
 import { getLogger } from "../util/logger.js";
-import { buildAccessRequestContractText } from "./access-request-copy.js";
+import {
+  buildAccessRequestContractText,
+  parseAccessRequestPayload,
+} from "./access-request-copy.js";
 import { isGuardianSensitiveEvent } from "./adapters/macos.js";
 import { pairDeliveryWithConversation } from "./conversation-pairing.js";
 import { composeFallbackCopy } from "./copy-composer.js";
@@ -80,11 +83,15 @@ function resolveApprovalContext(
     // Extract tool context so channel adapters can render structured
     // approval cards without re-parsing contextPayload.
     let toolName: string | undefined;
+    let riskLevel: string | undefined;
+    let commandPreview: string | undefined;
     if (
       parsed.requestKind === "tool_approval" ||
       parsed.requestKind === "tool_grant_request"
     ) {
       toolName = nonEmpty(parsed.toolName);
+      riskLevel = nonEmpty(parsed.riskLevel);
+      commandPreview = nonEmpty(parsed.commandPreview);
     } else if (parsed.requestKind === "pending_question") {
       toolName = nonEmpty(parsed.toolName);
     }
@@ -96,8 +103,8 @@ function resolveApprovalContext(
       permissionDetails: toolName
         ? {
             toolName,
-            riskLevel: "medium",
-            toolInput: {},
+            riskLevel: riskLevel ?? "medium",
+            toolInput: commandPreview ? { _summary: commandPreview } : {},
             requesterIdentifier: nonEmpty(parsed.requesterIdentifier),
           }
         : undefined,
@@ -181,6 +188,11 @@ export class NotificationBroadcaster {
     > | null = null;
 
     const approvalContext = resolveApprovalContext(signal);
+    const accessRequestContext =
+      signal.sourceEventName === "ingress.access_request" &&
+      signal.contextPayload
+        ? parseAccessRequestPayload(signal.contextPayload)
+        : undefined;
     const results: NotificationDeliveryResult[] = [];
 
     for (const channel of orderedChannels) {
@@ -411,6 +423,7 @@ export class NotificationBroadcaster {
         contextPayload: signal.contextPayload,
         urgency: signal.attentionHints.urgency,
         approvalContext,
+        accessRequestContext,
       };
 
       // Compute conversation decision audit fields for the delivery record

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

@@ -0,0 +1,139 @@
+/**
+ * The single sink for the per-(request, surface) `canonical_guardian_deliveries`
+ * registry.
+ *
+ * Guardian-request producers (access requests, tool approvals, tool-grant
+ * escalations, voice questions, trusted-contact confirmations) emit a
+ * notification signal and then record one canonical delivery row per surface the
+ * card reached. Capturing the surface address here — the conversation id for the
+ * in-app vellum card, or the channel-native message id (e.g. Slack `ts`) for a
+ * channel card — is what lets a delivered card be addressed back to its request
+ * later:
+ *
+ *   - to withdraw it in place when the request resolves
+ *     (`approvals/guardian-card-withdrawal.ts`), and
+ *   - to resolve an emoji reaction on the card to the right request when several
+ *     are pending in the same chat
+ *     (`getPendingCanonicalRequestByDestinationMessage`).
+ *
+ * Every producer records through here so the addressing convention lives in one
+ * place and cannot drift between the path that writes the row and the paths that
+ * read it back.
+ */
+
+import {
+  type CanonicalGuardianDelivery,
+  createCanonicalGuardianDelivery,
+  updateCanonicalGuardianDelivery,
+} from "../memory/canonical-guardian-store.js";
+import { getLogger } from "../util/logger.js";
+import type { NotificationDeliveryResult } from "./types.js";
+
+const log = getLogger("canonical-delivery-recorder");
+
+/**
+ * Where an approval card was delivered. Exactly one addressing modality is
+ * meaningful per channel:
+ *
+ *   - vellum (in-app): addressed by `conversationId` + the card's surface id.
+ *   - channels (slack/telegram/...): addressed by `chatId` + the channel-native
+ *     `messageId` (Slack `ts`).
+ */
+export interface ApprovalCardDeliveryAddress {
+  requestId: string;
+  channel: string;
+  /** In-app vellum addressing: the conversation the card was posted to. */
+  conversationId?: string;
+  /** Channel addressing: the chat the card was delivered to. */
+  chatId?: string;
+  /** Channel-native message id (e.g. Slack `ts`) — the reaction/withdrawal key. */
+  messageId?: string;
+  /** Initial delivery status (defaults to "pending"). */
+  status?: string;
+}
+
+/**
+ * Record where an approval card was delivered so it can be located later.
+ *
+ * Best-effort: a recording failure must never be mistaken for a delivery
+ * failure (which, in the prompt path, would trigger a fallback re-post), so
+ * errors are swallowed and logged and `null` is returned. Callers that need the
+ * row id (to apply a status afterwards) must null-check the result.
+ */
+export function recordApprovalCardDelivery(
+  address: ApprovalCardDeliveryAddress,
+): CanonicalGuardianDelivery | null {
+  try {
+    return createCanonicalGuardianDelivery({
+      requestId: address.requestId,
+      destinationChannel: address.channel,
+      destinationConversationId: address.conversationId,
+      destinationChatId: address.chatId,
+      destinationMessageId: address.messageId,
+      ...(address.status ? { status: address.status } : {}),
+    });
+  } catch (err) {
+    log.error(
+      { err, requestId: address.requestId, channel: address.channel },
+      "Failed to record approval card delivery; reaction/withdrawal on this card will not resolve",
+    );
+    return null;
+  }
+}
+
+/**
+ * Record every delivery for a guardian request from a notification signal's
+ * results, persisting each delivery's terminal status.
+ *
+ * This is the shared post-broadcast recording loop for the signal-based
+ * producers. The vellum row is normally created up front in the signal's
+ * `onConversationCreated` callback so the in-app client sees it immediately; pass
+ * that row's id as `vellumDeliveryId` and it is reused (only its status applied)
+ * — otherwise the vellum row is created here from the result.
+ *
+ * The pipeline result carries the delivered address directly: a `vellum` result
+ * carries a `conversationId`; channel results carry the chat (`destination`) and
+ * channel-native id (`messageId`). 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.
+ *
+ * Returns the vellum delivery id (passed in, or created here) so a caller can
+ * record its own "pipeline produced no vellum delivery" fallback.
+ */
+export function recordGuardianRequestDeliveries(params: {
+  requestId: string;
+  deliveryResults: NotificationDeliveryResult[];
+  vellumDeliveryId?: string;
+}): string | undefined {
+  const { requestId, deliveryResults } = params;
+  let vellumDeliveryId = params.vellumDeliveryId;
+
+  for (const result of deliveryResults) {
+    let deliveryId: string | undefined;
+    if (result.channel === "vellum") {
+      if (!vellumDeliveryId) {
+        vellumDeliveryId = recordApprovalCardDelivery({
+          requestId,
+          channel: "vellum",
+          conversationId: result.conversationId,
+        })?.id;
+      }
+      deliveryId = vellumDeliveryId;
+    } else {
+      deliveryId = recordApprovalCardDelivery({
+        requestId,
+        channel: result.channel,
+        chatId: result.destination.length > 0 ? result.destination : undefined,
+        messageId: result.messageId,
+      })?.id;
+    }
+
+    if (deliveryId) {
+      updateCanonicalGuardianDelivery(deliveryId, {
+        status: result.status === "sent" ? "sent" : "failed",
+      });
+    }
+  }
+
+  return vellumDeliveryId;
+}

package/src/notifications/copy-composer.ts

@@ -9,10 +9,11 @@
  * values from the context payload.
  */
 
+import { buildAccessRequestContractText } from "./access-request-copy.js";
 import {
-  buildAccessRequestContractText,
   buildAccessRequestSeedContentBlocks,
-} from "./access-request-copy.js";
+  buildToolApprovalSeedContentBlocks,
+} from "./approval-card-data.js";
 import {
   buildGuardianRequestCodeInstruction,
   parseGuardianQuestionPayload,
@@ -28,7 +29,6 @@ import type {
   NotificationSignal,
   NotificationSourceEventName,
 } from "./signal.js";
-import { buildToolApprovalSeedContentBlocks } from "./tool-approval-copy.js";
 import type { NotificationChannel, RenderedChannelCopy } from "./types.js";
 
 type CopyTemplate = (payload: Record<string, unknown>) => RenderedChannelCopy;

package/src/notifications/decision-engine.ts

@@ -26,10 +26,13 @@ import { truncate } from "../util/truncate.js";
 import {
   buildAccessRequestContractText,
   buildAccessRequestInviteDirective,
-  buildAccessRequestSeedContentBlocks,
   hasAccessRequestInstructions,
   hasInviteFlowDirective,
 } from "./access-request-copy.js";
+import {
+  buildAccessRequestSeedContentBlocks,
+  buildToolApprovalSeedContentBlocks,
+} from "./approval-card-data.js";
 import {
   buildConversationCandidates,
   type ConversationCandidateSet,
@@ -46,7 +49,6 @@ import {
 import { nonEmpty, readPayloadString } from "./notification-utils.js";
 import { getPreferenceSummary } from "./preference-summary.js";
 import type { NotificationSignal, RoutingIntent } from "./signal.js";
-import { buildToolApprovalSeedContentBlocks } from "./tool-approval-copy.js";
 import type {
   ConversationAction,
   NotificationChannel,

package/src/notifications/destination-resolver.ts

@@ -70,13 +70,12 @@ export function resolveDestinations(
             channel: channel as NotificationChannel,
             endpoint: externalChatId,
             metadata: {
-              externalUserId: guardianResult.channel.externalUserId,
+              externalUserId: guardianResult.channel.address,
             },
             bindingContext: {
               sourceChannel: channel as NotificationChannel,
               externalChatId,
-              externalUserId:
-                guardianResult.channel.externalUserId ?? undefined,
+              externalUserId: guardianResult.channel.address,
             },
           });
         }
@@ -101,13 +100,12 @@ export function resolveDestinations(
             channel: "slack",
             endpoint: chatId,
             metadata: {
-              externalUserId: guardianResult.channel.externalUserId,
+              externalUserId: guardianResult.channel.address,
             },
             bindingContext: {
               sourceChannel: "slack",
               externalChatId: chatId,
-              externalUserId:
-                guardianResult.channel.externalUserId ?? undefined,
+              externalUserId: guardianResult.channel.address,
             },
           });
         } else if (guardianResult && chatId) {

package/src/notifications/guardian-question-mode.ts

@@ -82,11 +82,19 @@ export const ToolApprovalPayloadSchema =
   GuardianQuestionPayloadBaseSchema.extend({
     requestKind: z.literal("tool_approval"),
     toolName: z.string().min(1),
+    /** Risk classification from the permission checker (e.g. "low", "medium", "high"). */
+    riskLevel: z.string().optional(),
+    /** Secret-redacted summary of the tool invocation arguments. */
+    commandPreview: z.string().optional(),
   });
 
 export const ToolGrantPayloadSchema = GuardianQuestionPayloadBaseSchema.extend({
   requestKind: z.literal("tool_grant_request"),
   toolName: z.string().min(1),
+  /** Risk classification from the permission checker (e.g. "low", "medium", "high"). */
+  riskLevel: z.string().optional(),
+  /** Secret-redacted summary of the tool invocation arguments. */
+  commandPreview: z.string().optional(),
 });
 
 export const AccessRequestGuardianPayloadSchema =
@@ -124,6 +132,8 @@ export const LenientToolApprovalPayloadSchema = z.object({
   requesterIdentifier: z.string().nullable().optional(),
   requesterExternalUserId: z.string().nullable().optional(),
   requesterChatId: z.string().nullable().optional(),
+  riskLevel: z.string().nullable().optional(),
+  commandPreview: z.string().nullable().optional(),
 });
 
 export type LenientToolApprovalPayload = z.infer<