@vellumai/assistant 0.11.4 → 0.11.5-staging.2

package/src/runtime/routes/conversation-management-routes.ts

@@ -691,17 +691,16 @@ async function handleRetryLastAssistantTurn({
   const conversation = await getOrCreateConversationInstance(conversationId);
   touchConversation(conversationId);
 
-  // Bind the requesting actor's trust before the turn. A freshly hydrated
-  // conversation has no trust context, and `loadFromDb` under an unset
-  // context filters guardian-provenance history — the re-run would see an
-  // empty transcript.
+  // Resolved before the busy gate so the awaits stay outside the
+  // check-then-claim window below, but bound only once the claim succeeds: a
+  // retry that loses the race is rejected, and a rejected request must not
+  // repoint the conversation's actor at its requester.
   const actorPrincipalId = headers?.["x-vellum-actor-principal-id"];
-  conversation.setTrustContext(
-    await resolveVellumActorTrustContext(actorPrincipalId, {
-      healResetDrift: true,
-    }),
+  const retryTrustContext = await resolveVellumActorTrustContext(
+    actorPrincipalId,
+    { healResetDrift: true },
   );
-  conversation.currentTurnSourceActorPrincipalId =
+  const retrySourceActorPrincipalId =
     await resolveActorPrincipalIdForLocalGuardian(actorPrincipalId);
 
   // Synchronous check-then-claim (no await between them) so a concurrent
@@ -714,6 +713,13 @@ async function handleRetryLastAssistantTurn({
   }
   conversation.setProcessing(true);
 
+  // Bind the requesting actor's trust for the turn we just claimed. A freshly
+  // hydrated conversation has no trust context, and `loadFromDb` under an
+  // unset context filters guardian-provenance history — the re-run would see
+  // an empty transcript.
+  conversation.setTrustContext(retryTrustContext);
+  conversation.currentTurnSourceActorPrincipalId = retrySourceActorPrincipalId;
+
   const requestId = uuidv7();
   const abortController = new AbortController();
   let discarded: ReturnType<typeof discardLastAssistantDisplayTurn>;

package/src/runtime/routes/conversation-routes.ts

@@ -1236,12 +1236,10 @@ export async function handleListMessages({
 
       const alignedContentOrder = aligned.rewriteContentOrder(contentOrder);
 
-      // Use sentAt (actual event time) for the display timestamp when available,
-      // falling back to createdAt (persistence time). Clients use this display
-      // timestamp as their pagination cursor after memory-pressure trimming,
-      // while server-side pagination filters on createdAt. The mismatch is
-      // benign: it may return slightly extra data on a page boundary but never
-      // loses messages.
+      // Use sentAt (actual event time) for the display timestamp when
+      // available, falling back to createdAt (persistence time). Pagination
+      // is unaffected: the cursor is `oldestTimestamp`, built from
+      // `createdAt` on both ends.
       const displayTimestamp = m.sentAt ?? m.createdAt;
       return {
         id: m.id ?? "",
@@ -1849,6 +1847,11 @@ export async function handleSendMessage(
 
   // Resolve guardian context from the AuthContext's actorPrincipalId via the
   // gateway guardian binding: a vellum principal is the guardian or nobody.
+  //
+  // Resolved into a local; the conversation's slot is stamped only where this
+  // request commits to running a turn, since that write is what supplies the
+  // acting actor for a run and must not fire for a send that merely queues.
+  let resolvedTrustCtx: TrustContext;
   if (actorPrincipalId) {
     // Dev bypass (HTTP auth disabled): the synthetic "dev-bypass" principal
     // won't match any guardian binding. Resolve the real guardian principal and
@@ -1874,7 +1877,7 @@ export async function handleSendMessage(
           trustCtx = healed;
         }
       }
-      conversation.setTrustContext(trustCtx);
+      resolvedTrustCtx = trustCtx;
     } else {
       let trustCtx = withSourceChannel(
         sourceChannel,
@@ -1907,22 +1910,19 @@ export async function handleSendMessage(
           );
         }
       }
-      conversation.setTrustContext(trustCtx);
+      resolvedTrustCtx = trustCtx;
     }
   } else {
     // Service principals (svc_gateway) or tokens without an actor ID
     // get a minimal guardian context so downstream code has something.
-    conversation.setTrustContext({ trustClass: "guardian", sourceChannel });
+    resolvedTrustCtx = { trustClass: "guardian", sourceChannel };
   }
 
-  // The trust this request's turn runs under, captured here rather than read
-  // back at the agent loop below. Every branch above has just written it and
-  // nothing awaits in between, so this is the resolved sender. Between here
-  // and the loop the conversation slot is writable by paths that do not own
-  // this turn (channel ingress for another actor, live-voice hydration,
-  // pointer elevation, the voice bridge), and the loop would otherwise
-  // re-read it and run this turn as whoever wrote last.
-  const turnTrustContext = conversation.trustContext;
+  // The trust this request's turn runs under: the sender resolved above,
+  // never a read of the shared slot. Between here and the loop that slot is
+  // writable by paths that do not own this turn (channel ingress for another
+  // actor, live-voice hydration, pointer elevation, the voice bridge).
+  const turnTrustContext = resolvedTrustCtx;
 
   const isInteractive = isInteractiveInterface(sourceInterface);
   // Translate the dev-bypass actor principal to the real guardian principal
@@ -2053,12 +2053,15 @@ export async function handleSendMessage(
         requestId: uuidv7(),
         metadata: greetingMeta,
         clientMessageId,
+        // This path answers and returns without starting a turn, so it never
+        // reaches the stamp below; name the sender on the row directly.
+        trustContext: resolvedTrustCtx,
         ...(clientOs ? { requestClientOs: clientOs } : {}),
       });
 
       const conversationId = mapping.conversationId;
       const channelMeta = buildChannelMetadata(sourceChannel, sourceInterface, {
-        trustContext: conversation.trustContext,
+        trustContext: resolvedTrustCtx,
       });
 
       const assistantMsg = createAssistantMessage(cannedGreeting);
@@ -2165,10 +2168,9 @@ export async function handleSendMessage(
 
   // Resolve the verified actor's external user ID and principal for inline
   // approval routing from the conversation's guardian context.
-  const verifiedActorExternalUserId =
-    conversation.trustContext?.guardianExternalUserId;
+  const verifiedActorExternalUserId = resolvedTrustCtx.guardianExternalUserId;
   const verifiedActorPrincipalId =
-    conversation.trustContext?.guardianPrincipalId ?? undefined;
+    resolvedTrustCtx.guardianPrincipalId ?? undefined;
 
   // Try to consume the message as a guardian approval/rejection reply.
   // On failure, degrade to the existing queue/auto-deny path rather than
@@ -2242,6 +2244,10 @@ export async function handleSendMessage(
       sourceActorPrincipalId,
       transport,
       clientMessageId,
+      // The sender's own trust, so the drain runs this message as the actor
+      // who sent it rather than as whoever the slot happens to hold when the
+      // queue is worked.
+      trustContext: resolvedTrustCtx,
     });
     if (enqueueResult.rejected) {
       return new RouteResponse(
@@ -2340,7 +2346,15 @@ export async function handleSendMessage(
   // matching in-memory pending interaction (e.g. prompter timeouts).
   await expireOrphanedGuardianRequests(mapping.conversationId);
 
-  // Conversation is idle — persist and fire agent loop immediately
+  // Conversation is idle — persist and fire agent loop immediately.
+  //
+  // Stamping the sender here rather than at resolution is what keeps the two
+  // in step: the slot hydrates and scopes the turn started just below
+  // (`ensureActorScopedHistory`, persisted provenance, the loop's own trust),
+  // so it must name whoever this request is about to run as. A request that
+  // queues instead returns above without stamping — it is not starting a run,
+  // and its actor rides the queue item to the drain.
+  conversation.setTrustContext(resolvedTrustCtx);
   conversation.setTurnChannelContext({
     userMessageChannel: sourceChannel,
     assistantMessageChannel: sourceChannel,

package/src/runtime/routes/credential-in-use.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared in-use guard for the credential-delete surfaces
+ * (`POST /v1/credentials/delete` and `DELETE /v1/secrets`).
+ *
+ * A credential removed while an LLM connection resolves its auth through it
+ * takes that connection offline, so such a delete is refused until the caller
+ * confirms it with `force`. Both surfaces run the same guard, so a protection on
+ * only one of them is one a client can route around.
+ */
+
+import { findConnectionsUsingCredential } from "../../providers/inference/credential-usage.js";
+import { clearConnectionProviderCache } from "../../providers/registry.js";
+import { getLogger } from "../../util/logger.js";
+import { RouteError } from "./errors.js";
+
+const log = getLogger("runtime/routes/credential-in-use");
+
+/**
+ * A credential is still referenced by at least one provider connection.
+ *
+ * Carries the dependent connection names in both the message and
+ * `details.connections`, so a client can name them in its confirmation
+ * prompt, and a distinct `code` so it can tell this refusal apart from an
+ * ordinary bad request and offer the forced retry.
+ */
+export class CredentialInUseError extends RouteError {
+  constructor(
+    readonly connections: string[],
+    message: string,
+  ) {
+    super(message, "CREDENTIAL_IN_USE", 400, { connections });
+    this.name = "CredentialInUseError";
+  }
+}
+
+/**
+ * Refuse to delete `credentialAccount` while provider connections resolve
+ * their auth through it, unless `force` is set. Returns the affected
+ * connection names so the caller can invalidate what depended on them.
+ *
+ * The credential itself is never logged beyond its `credential/{service}/
+ * {field}` account name, which holds no secret material.
+ */
+export function assertCredentialNotInUse(
+  credentialAccount: string,
+  force: boolean,
+): string[] {
+  const connections = findConnectionsUsingCredential(credentialAccount);
+  if (connections.length === 0) {
+    return connections;
+  }
+  if (!force) {
+    const list = connections.map((name) => `"${name}"`).join(", ");
+    throw new CredentialInUseError(
+      connections,
+      `Credential ${credentialAccount} is in use by ${
+        connections.length === 1 ? "connection" : "connections"
+      } ${list}. ${
+        connections.length === 1 ? "It" : "They"
+      } will stop working without it. Delete it anyway to continue.`,
+    );
+  }
+  log.warn(
+    { credential: credentialAccount, connections },
+    "Force-deleting a credential that provider connections depend on. Those connections can no longer dispatch until a new credential is added",
+  );
+  return connections;
+}
+
+/**
+ * Drop cached adapters built around a deleted credential so the next dispatch
+ * re-resolves auth and reports the missing credential instead of replaying a
+ * cached adapter holding the removed key.
+ */
+export function invalidateConnectionsAfterCredentialDelete(
+  affectedConnections: string[],
+): void {
+  if (affectedConnections.length === 0) {
+    return;
+  }
+  // The cache is keyed by connection + model + provider, so entries for one
+  // connection are not addressable individually; clearing it costs the next
+  // dispatch per connection one credential re-read.
+  clearConnectionProviderCache();
+}

package/src/runtime/routes/credential-routes.ts

@@ -16,22 +16,13 @@
 
 import { z } from "zod";
 
-import {
-  ACP_SERVICE,
-  AcpCredentialFormatError,
-  assertAcpCredentialFormat,
-} from "../../acp/acp-credentials.js";
+import { AcpCredentialFormatError } from "../../acp/acp-credentials.js";
 import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import {
   fetchManagedCatalog,
   type ManagedCredentialDescriptor,
 } from "../../credential-execution/managed-catalog.js";
 import { buildForChatSentinel } from "../../daemon/chat-credential-redaction.js";
-import {
-  isNonSecretPlatformField,
-  scrubStoredCredentialFromTranscripts,
-} from "../../daemon/credential-transcript-scrub.js";
-import { syncManualTokenConnection } from "../../oauth/manual-token-connection.js";
 import {
   disconnectOAuthProvider,
   getConnectionByProvider,
@@ -39,14 +30,11 @@ import {
   type OAuthConnectionRow,
 } from "../../oauth/oauth-store.js";
 import { credentialKey } from "../../security/credential-key.js";
-import { normalizeSecretValue } from "../../security/secret-normalize.js";
 import {
   deleteSecureKeyAsync,
   getActiveBackendInfoAsync,
-  getActiveBackendName,
   getSecureKeyAsync,
   getSecureKeyResultAsync,
-  setSecureKeyAsync,
 } from "../../security/secure-keys.js";
 import {
   assertMetadataWritable,
@@ -55,19 +43,24 @@ import {
   getCredentialMetadata,
   getCredentialMetadataById,
   listCredentialMetadata,
-  upsertCredentialMetadata,
 } from "../../tools/credentials/metadata-store.js";
 import type { CredentialInjectionTemplate } from "../../tools/credentials/policy-types.js";
-import { getLogger } from "../../util/logger.js";
+import {
+  CredentialStorageError,
+  InvalidCredentialInputError,
+  storeCredentialValue,
+} from "../../tools/credentials/store.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { recordForChatMint } from "../for-chat-mint-registry.js";
 import { recordRevealSuccess } from "../reveal-success-registry.js";
+import {
+  assertCredentialNotInUse,
+  invalidateConnectionsAfterCredentialDelete,
+} from "./credential-in-use.js";
 import { InjectionTemplateSchema } from "./credential-prompt-routes.js";
 import { BadRequestError, InternalError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
-const log = getLogger("credential-routes");
-
 // ---------------------------------------------------------------------------
 // Shared helpers
 // ---------------------------------------------------------------------------
@@ -458,74 +451,29 @@ async function handleCredentialsSet({ body }: RouteHandlerArgs) {
     throw new BadRequestError("value is required");
   }
 
-  const normalizedValue = normalizeSecretValue(value);
-  if (normalizedValue.length === 0) {
-    throw new BadRequestError("value is required");
-  }
-
-  // Reject an Anthropic API key pasted into the ACP OAuth-token field (a 401
-  // footgun) as a 400 rather than letting the guard surface as a 500.
-  if (service === ACP_SERVICE) {
-    try {
-      assertAcpCredentialFormat(field, normalizedValue);
-    } catch (err) {
-      if (err instanceof AcpCredentialFormatError) {
-        throw new BadRequestError(err.message);
-      }
-      throw err;
+  try {
+    return await storeCredentialValue({
+      service,
+      field,
+      value,
+      alias: label,
+      usageDescription: description,
+      allowedTools,
+      allowedDomains,
+      injectionTemplates,
+    });
+  } catch (err) {
+    if (
+      err instanceof InvalidCredentialInputError ||
+      err instanceof AcpCredentialFormatError
+    ) {
+      throw new BadRequestError(err.message);
     }
-  }
-
-  assertMetadataWritable();
-
-  const key = credentialKey(service, field);
-  const stored = await setSecureKeyAsync(key, normalizedValue);
-  if (!stored) {
-    throw new InternalError(
-      `Failed to store credential in secure storage (backend: ${getActiveBackendName()})`,
-    );
-  }
-
-  // The stored plaintext may already sit in recent transcripts: the user
-  // message that pasted it, the persisted tool_use input, the tool result
-  // echoing the command. This route is the scrub seam — not
-  // setSecureKeyAsync, which also fires on OAuth refresh rotations and MCP
-  // header writes whose values never transited a transcript. The scrub runs
-  // immediately after the secure-store write, BEFORE the metadata upsert and
-  // connection sync: those side effects can throw (oauth-store work), and a
-  // stored-but-unscrubbed secret must not depend on them succeeding. The
-  // credential IS stored at this point; the scrub is best-effort hygiene and
-  // must stay invisible to the caller.
-  if (!isNonSecretPlatformField(service, field)) {
-    try {
-      const scrubbed =
-        await scrubStoredCredentialFromTranscripts(normalizedValue);
-      log.info(
-        { service, field, ...scrubbed },
-        "Credential stored; scrubbed value from recent transcripts",
-      );
-    } catch (err) {
-      log.warn(
-        { err, service, field },
-        "Credential stored, but transcript scrub failed",
-      );
+    if (err instanceof CredentialStorageError) {
+      throw new InternalError(err.message);
     }
+    throw err;
   }
-
-  const metadata = upsertCredentialMetadata(service, field, {
-    alias: label,
-    usageDescription: description,
-    allowedTools,
-    allowedDomains,
-    injectionTemplates,
-  });
-  await syncManualTokenConnection(service);
-
-  return {
-    credentialId: metadata.credentialId,
-    service,
-    field,
-  };
 }
 
 async function handleCredentialsDelete({ body }: RouteHandlerArgs) {
@@ -533,9 +481,10 @@ async function handleCredentialsDelete({ body }: RouteHandlerArgs) {
     throw new BadRequestError("Request body is required");
   }
 
-  const { service, field } = body as {
+  const { service, field, force } = body as {
     service?: string;
     field?: string;
+    force?: boolean;
   };
 
   if (!service || typeof service !== "string") {
@@ -557,6 +506,7 @@ async function handleCredentialsDelete({ body }: RouteHandlerArgs) {
     service === "slack_channel" && field === "user_token";
 
   const key = credentialKey(service, field);
+  const affectedConnections = assertCredentialNotInUse(key, force === true);
   const existing = await getSecureKeyAsync(key);
   const deleteResult =
     existing != null ? await deleteSecureKeyAsync(key) : "not-found";
@@ -567,6 +517,11 @@ async function handleCredentialsDelete({ body }: RouteHandlerArgs) {
     );
   }
 
+  // Cached provider adapters hold the deleted credential, so they are dropped
+  // as soon as the secure vault no longer has it: a later failure in this
+  // handler must not leave them dispatching with a credential that is gone.
+  invalidateConnectionsAfterCredentialDelete(affectedConnections);
+
   const metadataDeleted = deleteCredentialMetadata(service, field);
 
   // Clean up OAuth connection (best-effort).
@@ -593,7 +548,9 @@ async function handleCredentialsDelete({ body }: RouteHandlerArgs) {
     throw new BadRequestError("Credential not found");
   }
 
-  return { service, field };
+  invalidateConnectionsAfterCredentialDelete(affectedConnections);
+
+  return { service, field, affectedConnections };
 }
 
 async function handleCredentialsStatus() {
@@ -746,15 +703,28 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Delete a credential",
     description:
-      "Remove a secret, its metadata, and any associated OAuth connection from the vault.",
+      "Remove a secret, its metadata, and any associated OAuth connection from the vault. " +
+      "Refused with CREDENTIAL_IN_USE while an LLM provider connection resolves its auth " +
+      "through the credential, unless `force` is set.",
     tags: ["credentials"],
     requestBody: z.object({
       service: z.string().describe("Service namespace"),
       field: z.string().describe("Field name"),
+      force: z
+        .boolean()
+        .optional()
+        .describe(
+          "Delete even when provider connections depend on the credential",
+        ),
     }),
     responseBody: z.object({
       service: z.string(),
       field: z.string(),
+      affectedConnections: z
+        .array(z.string())
+        .describe(
+          "Provider connections that depended on the deleted credential",
+        ),
     }),
     handler: handleCredentialsDelete,
   },

package/src/runtime/routes/guardian-approval-interception.ts

@@ -7,8 +7,10 @@
  */
 import type { KnownBlock } from "@slack/types";
 
+import { audienceForReader } from "../../channels/message-audience.js";
 import type { ChannelId } from "../../channels/types.js";
 import type { TrustContext } from "../../daemon/trust-context-types.js";
+import { editChannelMessage } from "../../messaging/providers/index.js";
 import { getLogger } from "../../util/logger.js";
 import { resolveCapabilities } from "../capabilities.js";
 import type { ApprovalDecisionResult } from "../channel-approval-types.js";
@@ -33,18 +35,6 @@ import { deliverStaleApprovalReply } from "./guardian-approval-reply-helpers.js"
 
 const log = getLogger("runtime-http");
 
-/**
- * Resolve the Slack ephemeral user ID when the source channel is Slack.
- * Returns `undefined` for non-Slack channels so callers can pass the
- * result directly to `ephemeralUserId` without branching.
- */
-function slackEphemeralUserId(
-  sourceChannel: ChannelId,
-  userId: string | undefined,
-): string | undefined {
-  return sourceChannel === "slack" && userId ? userId : undefined;
-}
-
 export interface ApprovalInterceptionParams {
   conversationId: string;
   callbackData?: string;
@@ -170,7 +160,11 @@ export async function handleApprovalInterception(
           errorLogMessage:
             "Failed to deliver guardian-pending notice to non-guardian actor (pre-row guard)",
           errorLogContext: { conversationId },
-          ephemeralUserId: slackEphemeralUserId(sourceChannel, actorExternalId),
+          audience: audienceForReader(
+            sourceChannel,
+            conversationExternalId,
+            actorExternalId,
+          ),
         });
         return { handled: true, type: "assistant_turn" };
       }
@@ -205,8 +199,9 @@ export async function handleApprovalInterception(
         "Blocking guardian-class approval decision: acting principal missing or does not match the bound guardian principal",
       );
       if (replyCallbackUrl) {
-        const ephemeralUser = slackEphemeralUserId(
+        const rejectionAudience = audienceForReader(
           sourceChannel,
+          conversationExternalId,
           actorExternalId,
         );
         try {
@@ -214,7 +209,10 @@ export async function handleApprovalInterception(
             chatId: conversationExternalId,
             text: "Sorry, I couldn't process that. Please try again.",
             assistantId,
-            ...(ephemeralUser ? { ephemeral: true, user: ephemeralUser } : {}),
+            // Stated rather than spread. A rejection that loses its
+            // audience becomes a public one, so the key is always present
+            // and the compiler checks it.
+            audience: rejectionAudience,
           });
         } catch (err) {
           log.error(
@@ -273,11 +271,10 @@ export async function handleApprovalInterception(
             decisionOutcome === "approved" ? "\u2713" : "\u2717";
           const statusLabel =
             decisionOutcome === "approved" ? "Approved" : "Denied";
-          deliverChannelReply(replyCallbackUrl, {
+          editChannelMessage(replyCallbackUrl, {
             chatId: conversationExternalId,
+            messageId: approvalMessageTs,
             text: `${statusEmoji} ${statusLabel}`,
-            messageTs: approvalMessageTs,
-            assistantId,
           }).catch((err) => {
             log.error(
               { err, conversationId, messageTs: approvalMessageTs },
@@ -362,7 +359,11 @@ export async function handleApprovalInterception(
       toolName: pending.length > 0 ? pending[0].toolName : undefined,
     },
     errorLogContext: { conversationId },
-    ephemeralUserId: slackEphemeralUserId(sourceChannel, actorExternalId),
+    audience: audienceForReader(
+      sourceChannel,
+      conversationExternalId,
+      actorExternalId,
+    ),
   });
 
   return { handled: true, type: "assistant_turn" };
@@ -395,12 +396,11 @@ function editStaleSlackApprovalMessage(params: {
       elements: [{ type: "mrkdwn", text: statusText }],
     },
   ];
-  deliverChannelReply(params.replyCallbackUrl, {
+  editChannelMessage(params.replyCallbackUrl, {
     chatId: params.chatId,
+    messageId: params.messageTs,
     text: statusText,
     blocks,
-    messageTs: params.messageTs,
-    assistantId: params.assistantId,
   }).catch((err) => {
     log.error(
       {

package/src/runtime/routes/guardian-approval-reply-helpers.ts

@@ -3,6 +3,7 @@
  * identity mismatch notices, reminders, etc.) that were duplicated across
  * guardian-approval-interception.ts.
  */
+import type { MessageAudience } from "@vellumai/gateway-client";
 import type pino from "pino";
 
 import type { ChannelId } from "../../channels/types.js";
@@ -45,7 +46,8 @@ interface DeliverApprovalReplyParams {
    * sees the message. Used to keep approval-related noise out of shared
    * channels.
    */
-  ephemeralUserId?: string;
+  /** Restricts the reply to one reader. Absent means the room. */
+  audience?: MessageAudience;
 }
 
 /**
@@ -61,7 +63,7 @@ async function composeAndDeliver(
     chatId,
     assistantId,
     approvalCopyGenerator,
-    ephemeralUserId,
+    audience,
   } = params;
 
   const text = await composeApprovalMessageGenerative(
@@ -74,9 +76,8 @@ async function composeAndDeliver(
     text,
     assistantId,
   };
-  if (ephemeralUserId) {
-    payload.ephemeral = true;
-    payload.user = ephemeralUserId;
+  if (audience) {
+    payload.audience = audience;
   }
   await deliverChannelReply(replyCallbackUrl, payload);
 }
@@ -120,7 +121,8 @@ export interface DeliverStaleApprovalReplyParams {
    * When set, deliver via `chat.postEphemeral` so only this Slack user
    * sees the message. Keeps approval noise out of shared channels.
    */
-  ephemeralUserId?: string;
+  /** Restricts the reply to one reader. Absent means the room. */
+  audience?: MessageAudience;
 }
 
 /**
@@ -134,12 +136,11 @@ export interface DeliverStaleApprovalReplyParams {
 export async function deliverStaleApprovalReply(
   params: DeliverStaleApprovalReplyParams,
 ): Promise<void> {
-  const { scenario, sourceChannel, extraContext, ephemeralUserId, ...rest } =
-    params;
+  const { scenario, sourceChannel, extraContext, audience, ...rest } = params;
 
   const replyParams: DeliverApprovalReplyParams = {
     ...rest,
-    ephemeralUserId,
+    audience,
     context: {
       scenario,
       channel: sourceChannel,
@@ -190,7 +191,8 @@ export interface DeliverIdentityMismatchReplyParams {
    * When set, deliver via `chat.postEphemeral` so only this Slack user
    * sees the message.
    */
-  ephemeralUserId?: string;
+  /** Restricts the reply to one reader. Absent means the room. */
+  audience?: MessageAudience;
 }
 
 /**
@@ -200,11 +202,11 @@ export interface DeliverIdentityMismatchReplyParams {
 export async function deliverIdentityMismatchReply(
   params: DeliverIdentityMismatchReplyParams,
 ): Promise<void> {
-  const { sourceChannel, ephemeralUserId, ...rest } = params;
+  const { sourceChannel, audience, ...rest } = params;
 
   await deliverApprovalReply({
     ...rest,
-    ephemeralUserId,
+    audience,
     context: {
       scenario: "guardian_identity_mismatch",
       channel: sourceChannel,