@vellumai/assistant 0.11.2 → 0.11.3-staging.1

package/src/agent/image-optimize.ts

@@ -110,10 +110,10 @@ export function upscaleTargetDimensions(dims: {
  * Reactive only: called by the image-recovery plugin after an actual
  * "Could not process image" rejection, never on the pre-send path.
  */
-export function upscaleImageToMinimum(
+export async function upscaleImageToMinimum(
   base64Data: string,
   mediaType: string,
-): { data: string; mediaType: string } | null {
+): Promise<{ data: string; mediaType: string } | null> {
   const dims = parseImageDimensions(base64Data, mediaType);
   if (!dims) {
     return null;
@@ -122,7 +122,7 @@ export function upscaleImageToMinimum(
   if (!target) {
     return null;
   }
-  const upscaled = convertImageToJpeg(Buffer.from(base64Data, "base64"), {
+  const upscaled = await convertImageToJpeg(Buffer.from(base64Data, "base64"), {
     resizeToPx: target,
     quality: JPEG_QUALITY,
   });
@@ -144,10 +144,10 @@ export function upscaleImageToMinimum(
  * Conversion (and its content-addressed disk cache) is shared with attachment
  * storage normalization — see `util/image-conversion.ts`.
  */
-export function optimizeImageForTransport(
+export async function optimizeImageForTransport(
   base64Data: string,
   mediaType: string,
-): { data: string; mediaType: string } {
+): Promise<{ data: string; mediaType: string }> {
   const rawBytes = Buffer.from(base64Data, "base64");
   const dims = parseImageDimensions(base64Data, mediaType);
 
@@ -155,7 +155,7 @@ export function optimizeImageForTransport(
     return { data: base64Data, mediaType };
   }
 
-  const optimized = convertImageToJpeg(rawBytes, {
+  const optimized = await convertImageToJpeg(rawBytes, {
     maxDimensionPx: MAX_DIMENSION,
     quality: JPEG_QUALITY,
   });

package/src/agent/loop.ts

@@ -1,8 +1,8 @@
-import { getConfig } from "../config/loader.js";
-import { isMemoryV3Live } from "../config/memory-v3-gate.js";
+import type { AnsweredQuestion } from "../api/events/question-answered.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import { recordEstimate } from "../context/estimator-calibration.js";
 import { preModelCallSanitize } from "../context/outbound-sanitize.js";
+import { turnStartUserMessageHasSpotlight } from "../context/strip-injections.js";
 import {
   estimatePromptTokensRaw,
   estimatePromptTokensWithTools,
@@ -116,9 +116,9 @@ export interface AgentLoopConfig {
    * This is a SERVER tool the provider runs itself, distinct from the client
    * tool list (`tools` / `resolveTools`): it is never executed by
    * {@link AgentLoopConstructorOptions.toolExecutor} and does not require any
-   * client-tool allowlist entry. Used by the tool-less advisor consult to
-   * ground its guidance with live web access while staying one-shot for client
-   * tools. Defaults to false — existing behavior.
+   * client-tool allowlist entry. Used by the advisor consult to ground its
+   * guidance with live web access on top of its read-only client tools.
+   * Defaults to false.
    */
   enableNativeWebSearch?: boolean;
 }
@@ -289,6 +289,8 @@ export type AgentEvent =
       approvalReason?: string;
       riskThreshold?: string;
       activityMetadata?: ToolActivityMetadata;
+      /** Answered `ask_question` record (see `ToolExecutionResult.answeredQuestion`). */
+      answeredQuestion?: AnsweredQuestion;
       /** Stable machine-readable error classification (see `ToolExecutionResult.errorCode`). */
       errorCode?: string;
       /**
@@ -698,6 +700,7 @@ export type LoopToolExecutor = (
   approvalReason?: string;
   riskThreshold?: string;
   activityMetadata?: ToolActivityMetadata;
+  answeredQuestion?: AnsweredQuestion;
   errorCode?: string;
 }>;
 
@@ -1355,9 +1358,9 @@ export class AgentLoop {
         // `this.provider.supportsNativeWebSearch` snapshot; providers without
         // the routing-aware probe fall back to the static flag. This is a SERVER
         // tool — it bypasses the client allowlist and the tool executor — so the
-        // tool-less advisor consult can ground its guidance with live web access
-        // while staying one-shot for client tools. Skip when a `web_search` tool
-        // is already present so we never duplicate the name.
+        // advisor consult can ground its guidance with live web access on top of
+        // its read-only client tools. Skip when a `web_search` tool is already
+        // present so we never duplicate the name.
         const supportsRoutedNativeWebSearch = this.provider
           .supportsNativeWebSearchFor
           ? this.provider.supportsNativeWebSearchFor(
@@ -1420,9 +1423,7 @@ export class AgentLoop {
         if (this.config.toolChoice) {
           providerConfig.tool_choice = this.config.toolChoice;
         } else if (attachNativeWebSearch) {
-          // The native web-search tool is the only tool on this turn (the
-          // advisor consult is otherwise tool-less). Let the model decide
-          // whether to search rather than forcing it.
+          // Let the model decide whether to search rather than forcing it.
           providerConfig.tool_choice = { type: "auto" };
         }
 
@@ -1430,14 +1431,18 @@ export class AgentLoop {
           providerConfig.cacheTtl = this.config.cacheTtl;
         }
 
-        // Cache-anchor signal for volatile latest-user-message turns: when
-        // memory-v3 is live it injects a per-turn `<memory>` block into the
-        // latest user message, so the provider must anchor its long-TTL cache
-        // breakpoint on the most recent STABLE user message instead of the
-        // volatile latest one. Read here alongside the rest of the provider
-        // config; only set when true so the wire/config stays byte-identical
-        // when off.
-        if (isMemoryV3Live(getConfig())) {
+        // Cache-anchor signal for turns whose opening message is volatile. The
+        // memory-v3 `<memory_spotlight>` block is the only injected block that
+        // is strip-and-replaced from every user message each turn, so when it
+        // is present that message's bytes do not recur next turn and a
+        // long-TTL breakpoint on it could never be read back. The provider
+        // marks it at the short TTL instead. Derived from the history actually
+        // being sent rather than from configuration, so turns where memory
+        // contributed no spotlight keep a normal anchor. Read off the
+        // turn-starting message, so the signal holds for every request in the
+        // turn rather than flipping once tool results arrive. Only set when
+        // true so the wire/config stays byte-identical when absent.
+        if (turnStartUserMessageHasSpotlight(history)) {
           providerConfig.mutableLatestUserMessage = true;
         }
 
@@ -1459,8 +1464,17 @@ export class AgentLoop {
           // conversation id). Absent for standalone `AgentLoop` instances
           // (unit tests constructed without a conversation id) — those fall
           // back to per-call random mix selection.
+          //
+          // The same id also travels as `conversationId`, which
+          // `RetryProvider.normalizeSendMessageOptions` uses to resolve the
+          // conversation's subagent role and spawn mode for the runtime
+          // proxy's billing-attribution headers. Both are stripped before any
+          // provider wire request; they are carried separately because
+          // `selectionSeed` is an opaque hashing input that callers may set to
+          // something other than a conversation id.
           if (this.conversationId) {
             providerConfig.selectionSeed = this.conversationId;
+            providerConfig.conversationId = this.conversationId;
           }
         }
 
@@ -2201,13 +2215,16 @@ export class AgentLoop {
         // message between calls would invalidate the prompt-cache prefix on
         // every iteration).
         if (conversationDir) {
-          const toolNameByUseId = new Map(
-            toolUseBlocks.map((tu) => [tu.id, tu.name]),
+          const toolCallByUseId = new Map(
+            toolUseBlocks.map((tu) => [
+              tu.id,
+              { name: tu.name, input: tu.input },
+            ]),
           );
           try {
             spoolAndStubOversizedToolResults(rawResultBlocks, {
               conversationDir,
-              toolNameById: (id) => toolNameByUseId.get(id),
+              toolCallById: (id) => toolCallByUseId.get(id),
             });
           } catch (err) {
             rlog.warn(
@@ -2286,6 +2303,7 @@ export class AgentLoop {
             approvalReason: result.approvalReason,
             riskThreshold: result.riskThreshold,
             activityMetadata: result.activityMetadata,
+            answeredQuestion: result.answeredQuestion,
             errorCode: result.errorCode,
           });
         }

package/src/agent/message-types.ts

@@ -4,15 +4,15 @@ import {
   type MessageAttachmentInput,
 } from "./attachments.js";
 
-export function createUserMessage(
+export async function createUserMessage(
   text: string,
   attachments: MessageAttachmentInput[] = [],
-): Message {
+): Promise<Message> {
   const content = [] as Message["content"];
   if (text.trim().length > 0) {
     content.push({ type: "text", text });
   }
-  content.push(...attachmentsToContentBlocks(attachments));
+  content.push(...(await attachmentsToContentBlocks(attachments)));
   return { role: "user", content };
 }
 

package/src/api/constants/document-tools.ts

@@ -0,0 +1,55 @@
+/**
+ * The document tools that mutate the stored document set, and what each one
+ * leaves behind. This is the single declaration both the daemon and the web
+ * client derive their tool sets from, so a new mutating document tool is added
+ * here once and every consumer picks it up.
+ *
+ * Tool names are the ones the runner sees. Calls arriving through the bundled
+ * `document-editor` skill reach the daemon already unwrapped to the inner tool
+ * name, and the web client unwraps the `skill_execute` envelope itself.
+ */
+
+export interface DocumentMutationTool {
+  /** The executed tool name. */
+  readonly name: string;
+  /**
+   * Whether the document is still openable once the tool has run. A deleted
+   * document has nothing to open, so it cannot anchor a link back to itself.
+   */
+  readonly reopenable: boolean;
+  /**
+   * Whether the tool writes into an already-created document, as opposed to
+   * the create that opened it.
+   */
+  readonly edit: boolean;
+}
+
+export const DOCUMENT_MUTATION_TOOLS: readonly DocumentMutationTool[] = [
+  { name: "document_create", reopenable: true, edit: false },
+  { name: "document_update", reopenable: true, edit: true },
+  { name: "document_replace_text", reopenable: true, edit: true },
+  { name: "document_delete", reopenable: false, edit: false },
+];
+
+/**
+ * Every tool that changes the document list. The daemon hooks these to publish
+ * a documents-changed broadcast, because they carry no list-level change signal
+ * of their own and client asset lists would otherwise keep serving a cached
+ * list after an edit and a deleted document would linger as a ghost row.
+ */
+export const DOCUMENT_MUTATION_TOOL_NAMES: readonly string[] =
+  DOCUMENT_MUTATION_TOOLS.map((tool) => tool.name);
+
+/**
+ * The mutating tools that leave the document openable. The web transcript
+ * anchors its changed-document chips on these, so a delete never produces a
+ * chip pointing at a document that is gone.
+ */
+export const REOPENABLE_DOCUMENT_MUTATION_TOOL_NAMES: readonly string[] =
+  DOCUMENT_MUTATION_TOOLS.filter((tool) => tool.reopenable).map(
+    (tool) => tool.name,
+  );
+
+/** The mutating tools that write into an already-created document. */
+export const DOCUMENT_EDIT_TOOL_NAMES: readonly string[] =
+  DOCUMENT_MUTATION_TOOLS.filter((tool) => tool.edit).map((tool) => tool.name);

package/src/api/events/question-answered.ts

@@ -0,0 +1,53 @@
+/**
+ * Durable record of an `ask_question` prompt the user has answered.
+ *
+ * The pending counterpart (`question_request` / `PendingToolQuestion`) is live
+ * registry state: it exists only while the prompt is outstanding and vanishes
+ * the moment the interaction resolves. This record is the opposite. It is
+ * produced by the `ask_question` executor once the prompt settles, rides the
+ * `tool_result` event, and is persisted on the tool_use block, so the answered
+ * question and the user's choice stay readable in the transcript across
+ * conversation switches, reloads, and history reopens.
+ *
+ * `questions` mirrors the `question_request` event's `questions[]` (same
+ * daemon-assigned `q1`, `q2`, ... ids) so the answered card renders from the
+ * same shape the interactive card did. `responses` is ordered to match, one
+ * entry per question.
+ *
+ * Only user-driven outcomes are recorded: a completed batch, or a card the
+ * user closed without answering (every question `skipped`). A prompt that
+ * timed out or was aborted produced no user decision, so it carries no record
+ * and the tool's own error result stands on its own.
+ *
+ * Canonical wire-contract source. Daemon code imports the type directly from
+ * this file; external consumers import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+import { QuestionEntrySchema } from "./question-request.js";
+
+export const AnsweredQuestionResponseSchema = z.object({
+  /** Daemon-assigned question id (`q1`, `q2`, ...) this answer belongs to. */
+  questionId: z.string(),
+  decision: z.enum(["option", "free_text", "skipped"]),
+  /** Chosen option id. Present only when `decision` is `"option"`. */
+  optionId: z.string().optional(),
+  /** The user's typed answer. Present only when `decision` is `"free_text"`. */
+  text: z.string().optional(),
+});
+
+export type AnsweredQuestionResponse = z.infer<
+  typeof AnsweredQuestionResponseSchema
+>;
+
+export const AnsweredQuestionSchema = z.object({
+  /** The resolved interaction's request id, matching the `question_request` that raised it. */
+  requestId: z.string(),
+  questions: z.array(QuestionEntrySchema),
+  responses: z.array(AnsweredQuestionResponseSchema),
+  /** `"completed"` when the user submitted a batch, `"closed"` when they dismissed the card. */
+  overall: z.enum(["completed", "closed"]),
+});
+
+export type AnsweredQuestion = z.infer<typeof AnsweredQuestionSchema>;

package/src/api/events/tool-result.ts

@@ -34,6 +34,7 @@ import {
   ConfirmationDiffSchema,
   DirectoryScopeOptionSchema,
 } from "./confirmation-request.js";
+import { AnsweredQuestionSchema } from "./question-answered.js";
 
 export const RiskScopeOptionSchema = z.object({
   pattern: z.string(),
@@ -131,6 +132,12 @@ export const ToolResultEventSchema = z.object({
   approvalReason: z.string().optional(),
   riskThreshold: z.string().optional(),
   activityMetadata: ToolActivityMetadataSchema.optional(),
+  /**
+   * Set only by `ask_question`: the questions asked and the answers the user
+   * gave. Carried here so the answered card renders the instant the prompt
+   * resolves, from the same record the daemon persists on the tool_use block.
+   */
+  answeredQuestion: AnsweredQuestionSchema.optional(),
   /**
    * Stable, machine-readable classification for an error result (only set when
    * `isError`). Lets a client branch on a known failure — e.g.

package/src/api/index.ts

@@ -137,6 +137,13 @@ export {
   CALL_SITE_COMPACTION_AGENT,
   CALL_SITE_SYNTHETIC_AGENT_ERROR_MESSAGE,
 } from "./constants/call-sites.js";
+export {
+  DOCUMENT_EDIT_TOOL_NAMES,
+  DOCUMENT_MUTATION_TOOL_NAMES,
+  DOCUMENT_MUTATION_TOOLS,
+  type DocumentMutationTool,
+  REOPENABLE_DOCUMENT_MUTATION_TOOL_NAMES,
+} from "./constants/document-tools.js";
 export {
   SSE_REPLAY_RING_AGE_LIMIT_MS,
   SSE_REPLAY_RING_COUNT_LIMIT,
@@ -493,6 +500,12 @@ export {
   type PlatformDisconnectedEvent,
   PlatformDisconnectedEventSchema,
 } from "./events/platform-disconnected.js";
+export {
+  type AnsweredQuestion,
+  type AnsweredQuestionResponse,
+  AnsweredQuestionResponseSchema,
+  AnsweredQuestionSchema,
+} from "./events/question-answered.js";
 export {
   type QuestionEntry,
   QuestionEntrySchema,

package/src/api/responses/conversation-message.ts

@@ -29,6 +29,7 @@ import {
   DirectoryScopeOptionSchema,
   ScopeOptionSchema,
 } from "../events/confirmation-request.js";
+import { AnsweredQuestionSchema } from "../events/question-answered.js";
 import { QuestionEntrySchema } from "../events/question-request.js";
 import { ToolActivityMetadataSchema } from "../events/tool-result.js";
 
@@ -242,6 +243,16 @@ export const ConversationMessageToolCallSchema = z.object({
    * render time). Lets a cold reconnect restore the inline question card.
    */
   pendingQuestion: PendingToolQuestionSchema.optional(),
+  /**
+   * The answered counterpart to `pendingQuestion`: the questions an
+   * `ask_question` call asked and the answers the user gave. Persisted on the
+   * tool_use block rather than stamped from the live registry, so it survives a
+   * conversation switch, a reload, and a history reopen. A tool call carries at
+   * most one of the two: the pending prompt while it is outstanding, the
+   * answered record once it settles. Absent on history rows written before the
+   * daemon recorded it.
+   */
+  answeredQuestion: AnsweredQuestionSchema.optional(),
 });
 export type ConversationMessageToolCall = z.infer<
   typeof ConversationMessageToolCallSchema

package/src/api/surfaces-oauth-connect.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  type OAuthConnectSurfaceData,
+  OAuthConnectSurfaceDataSchema,
+} from "./surfaces.js";
+
+describe("OAuthConnectSurfaceDataSchema requestedScopes", () => {
+  test("parses a valid scopes array and preserves order", () => {
+    const parsed = OAuthConnectSurfaceDataSchema.parse({
+      providerKey: "google",
+      requestedScopes: [
+        "https://www.googleapis.com/auth/tasks",
+        "https://www.googleapis.com/auth/calendar",
+        "openid",
+      ],
+    });
+    expect(parsed.requestedScopes).toEqual([
+      "https://www.googleapis.com/auth/tasks",
+      "https://www.googleapis.com/auth/calendar",
+      "openid",
+    ]);
+  });
+
+  test("absent requestedScopes parses to undefined", () => {
+    const parsed = OAuthConnectSurfaceDataSchema.parse({
+      providerKey: "google",
+    });
+    expect(parsed.requestedScopes).toBeUndefined();
+  });
+
+  test("an empty array collapses to undefined", () => {
+    const parsed = OAuthConnectSurfaceDataSchema.parse({
+      providerKey: "google",
+      requestedScopes: [],
+    });
+    expect(parsed.requestedScopes).toBeUndefined();
+  });
+
+  test("non-array values collapse to undefined instead of rejecting", () => {
+    for (const value of [
+      "https://www.googleapis.com/auth/tasks, openid",
+      42,
+      true,
+      { scope: "openid" },
+      null,
+    ]) {
+      const parsed = OAuthConnectSurfaceDataSchema.parse({
+        providerKey: "google",
+        requestedScopes: value,
+      });
+      expect(parsed.requestedScopes).toBeUndefined();
+    }
+  });
+
+  test("an array of blanks collapses to undefined", () => {
+    const parsed = OAuthConnectSurfaceDataSchema.parse({
+      providerKey: "google",
+      requestedScopes: ["", "   ", "\t"],
+    });
+    expect(parsed.requestedScopes).toBeUndefined();
+  });
+
+  test("entries are trimmed and blank or non-string junk is dropped", () => {
+    const parsed = OAuthConnectSurfaceDataSchema.parse({
+      providerKey: "google",
+      requestedScopes: [
+        "  https://www.googleapis.com/auth/tasks  ",
+        "",
+        null,
+        { nope: true },
+        "openid",
+      ],
+    });
+    expect(parsed.requestedScopes).toEqual([
+      "https://www.googleapis.com/auth/tasks",
+      "openid",
+    ]);
+  });
+
+  test("a bare string is not split on commas (scopes are opaque URIs)", () => {
+    const parsed = OAuthConnectSurfaceDataSchema.parse({
+      providerKey: "google",
+      requestedScopes: "a,b,c",
+    });
+    expect(parsed.requestedScopes).toBeUndefined();
+  });
+
+  test("legacy payload { providerKey: 'google' } still parses (skew guard)", () => {
+    const parsed: OAuthConnectSurfaceData = OAuthConnectSurfaceDataSchema.parse(
+      { providerKey: "google" },
+    );
+    expect(parsed.providerKey).toBe("google");
+    expect(parsed.requestedScopes).toBeUndefined();
+  });
+});

package/src/api/surfaces.ts

@@ -120,6 +120,21 @@ export const CardSurfaceDataSchema = z.object({
 });
 export type CardSurfaceData = z.infer<typeof CardSurfaceDataSchema>;
 
+/**
+ * Stringify+trim entries, drop blanks and non-scalars, and collapse an
+ * empty result to `undefined` so a schema treats it as "field absent".
+ */
+function cleanedStringEntries(items: unknown[]): string[] | undefined {
+  const cleaned = items
+    .map((item) =>
+      typeof item === "string" || typeof item === "number"
+        ? String(item).trim()
+        : "",
+    )
+    .filter((item) => item.length > 0);
+  return cleaned.length > 0 ? cleaned : undefined;
+}
+
 /**
  * Accepted MIME-type / extension patterns for a `file_upload` surface.
  *
@@ -137,14 +152,7 @@ const FileUploadAcceptedTypesSchema = z.preprocess((value) => {
       : Array.isArray(value)
         ? value
         : [];
-  const cleaned = items
-    .map((item) =>
-      typeof item === "string" || typeof item === "number"
-        ? String(item).trim()
-        : "",
-    )
-    .filter((item) => item.length > 0);
-  return cleaned.length > 0 ? cleaned : undefined;
+  return cleanedStringEntries(items);
 }, z.array(z.string()).optional());
 
 export const FileUploadSurfaceDataSchema = z.object({
@@ -238,6 +246,19 @@ export const ChoiceSurfaceDataSchema = z.object({
 });
 export type ChoiceSurfaceData = z.infer<typeof ChoiceSurfaceDataSchema>;
 
+/**
+ * Requested OAuth scopes for an `oauth_connect` surface.
+ *
+ * Unlike `FileUploadAcceptedTypesSchema`, a bare string is NOT split on
+ * commas: OAuth scopes are opaque URIs, so only arrays are accepted.
+ * Entries are stringified and trimmed, blanks are dropped, and an empty
+ * result or any non-array value collapses to `undefined` (use defaults).
+ */
+const RequestedScopesSchema = z.preprocess(
+  (value) => (Array.isArray(value) ? cleanedStringEntries(value) : undefined),
+  z.array(z.string()).optional(),
+);
+
 export const OAuthConnectSurfaceDataSchema = z.object({
   /** OAuth provider key from the managed provider catalog, e.g. "google". */
   providerKey: z
@@ -246,6 +267,13 @@ export const OAuthConnectSurfaceDataSchema = z.object({
       z.string(),
     )
     .catch(""),
+  /**
+   * Optional OAuth scopes to request for the managed connection. A full
+   * replacement set: when present, the platform uses exactly these scopes
+   * instead of its defaults (it does not merge). Omit to use the platform's
+   * default scopes for the provider.
+   */
+  requestedScopes: RequestedScopesSchema,
   /** Optional display label. The client falls back to the provider catalog. */
   displayName: tolerantString(),
   /** Optional helper text. The client falls back to the provider catalog. */

package/src/approvals/guardian-channel-delivery.ts

@@ -15,6 +15,11 @@
  * guardian decided off-channel (desktop), or the expiry sweep fired on a timer
  * with no originating request in hand. Returns null for channels that have no
  * deliverable route (e.g. email, the in-app vellum surface).
+ *
+ * Discord carries `dm=1`, which tells its transport that the `chatId` it is
+ * handed names a person to open a DM with rather than a channel to post in.
+ * Pair it with {@link resolveRequesterDeliveryTarget}, which supplies that
+ * person.
  */
 export function resolveDeliverCallbackUrlForChannel(
   channel: string,
@@ -24,7 +29,85 @@ export function resolveDeliverCallbackUrlForChannel(
     case "whatsapp":
     case "slack":
       return `/deliver/${channel}`;
+    case "discord":
+      return "/deliver/discord?dm=1";
     default:
       return null;
   }
 }
+
+/**
+ * Whether a message posted back in-band on this channel can be kept to one
+ * reader.
+ *
+ * Slack can, with `chat.postEphemeral`. Discord cannot: it has no ephemeral
+ * message outside an interaction response, so anything posted into the room a
+ * guardian replied in, or the room a request came from, is readable by every
+ * member of the server. That applies to a decision notice and to a
+ * verification code alike, which is why the callers treat an in-band reply
+ * context as unusable for Discord and fall through to the DM route instead.
+ *
+ * Telegram and WhatsApp are trivially true: their conversation already has one
+ * reader.
+ */
+export function channelCanAddressOneReaderInBand(channel: string): boolean {
+  return channel !== "discord";
+}
+
+/**
+ * Whether a notice can be addressed to one person by their user id rather than
+ * to the conversation the request arrived in.
+ *
+ * Slack opens a 1:1 DM when a `U…` id is posted as the channel. Discord
+ * resolves a user snowflake to a DM channel on its `dm`-marked route. This is
+ * an OUTBOUND question only: it says a message can be put in front of one
+ * person, and nothing about whether they can answer it.
+ */
+export function channelDeliversToUserId(channel: string): boolean {
+  return channel === "slack" || channel === "discord";
+}
+
+/**
+ * Whether a verification code can be sent straight to the requester, rather
+ * than handed to the guardian to relay out of band.
+ *
+ * Deliberately NOT the same set as {@link channelDeliversToUserId}, though it
+ * looks like it. That one asks whether a message reaches one person; this asks
+ * whether a code handshake can COMPLETE there, which additionally needs the
+ * reply to be heard. The copy this gates says "reply with it here", so a
+ * channel that can send into a DM but not receive from one would strand the
+ * requester holding a code they can never spend.
+ *
+ * Discord qualifies on both halves: its `dm`-marked route reaches the person,
+ * and `gateway/src/discord/admit.ts` admits DMs so the reply is heard.
+ */
+export function channelCanCompleteCodeHandshakeInDm(channel: string): boolean {
+  return channel === "slack" || channel === "discord";
+}
+
+/**
+ * Resolve who a requester notice is addressed to on the callback-less route.
+ *
+ * A request's `requesterChatId` is wherever the request came from, and where
+ * the channel has a private route to a user id that room is one other people
+ * can read. "Your request was denied" posted into a community channel is worse
+ * than not sending it, so those channels address the requester's own user id
+ * instead and let their transport turn it into a DM.
+ *
+ * Telegram and WhatsApp fall through to the chat id because theirs already is
+ * the private one-to-one conversation. So does a request with no actor
+ * identity: there is nobody to open a DM with, and on the channels that need
+ * one the transport reports that as a delivery failure rather than posting to
+ * the room.
+ */
+export function resolveRequesterDeliveryTarget(params: {
+  channel: string;
+  requesterChatId: string;
+  requesterExternalUserId: string;
+}): string {
+  const { channel, requesterChatId, requesterExternalUserId } = params;
+  if (channelDeliversToUserId(channel) && requesterExternalUserId) {
+    return requesterExternalUserId;
+  }
+  return requesterChatId;
+}