@vellumai/assistant 0.11.2 → 0.11.3-staging.2

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;
+}

package/src/approvals/guardian-expiry-notifier.ts

@@ -28,7 +28,10 @@ import { deliverChannelReply } from "../runtime/gateway-client.js";
 import { introductionMode } from "../runtime/introduction-policy.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
 import { getLogger } from "../util/logger.js";
-import { resolveDeliverCallbackUrlForChannel } from "./guardian-channel-delivery.js";
+import {
+  resolveDeliverCallbackUrlForChannel,
+  resolveRequesterDeliveryTarget,
+} from "./guardian-channel-delivery.js";
 
 const log = getLogger("guardian-expiry-notifier");
 
@@ -108,9 +111,10 @@ function releaseExpiredInteraction(request: GuardianRequestWire): void {
  *
  * The sweep is timer-driven and holds no inbound reply callback URL, so this
  * mirrors the resolvers' off-channel (desktop) delivery path: post to the
- * callback-less `/deliver/<channel>` route. On Slack the notice is routed to
- * the requester's DM via their user id rather than the channel id, so it is
- * never posted into a shared channel. No-ops on channels without a deliverable
+ * callback-less `/deliver/<channel>` route. On Slack and Discord the notice is
+ * routed to the requester's DM via their user id rather than the channel id,
+ * so it is never posted into a shared channel (see
+ * `resolveRequesterDeliveryTarget`). No-ops on channels without a deliverable
  * route (e.g. email, the in-app vellum surface) or when the requester chat is
  * unknown. Best-effort: a delivery failure is logged, never thrown.
  */
@@ -128,13 +132,11 @@ async function notifyRequesterOfExpiry(
     return;
   }
 
-  // On Slack, target the requester's DM (their `U…` user id) instead of the
-  // channel id so the expiry notice stays private. Other channels deliver to
-  // the requester chat directly.
-  const targetChatId =
-    channel === "slack" && requesterExternalUserId
-      ? requesterExternalUserId
-      : requesterChatId;
+  const targetChatId = resolveRequesterDeliveryTarget({
+    channel,
+    requesterChatId,
+    requesterExternalUserId,
+  });
 
   try {
     await deliverChannelReply(deliverUrl, {