@vellumai/assistant 0.8.3 → 0.8.5

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

@@ -21,7 +21,10 @@ import {
   isValidConversationStarterText,
 } from "../../memory/conversation-starter-validation.js";
 import { getDb } from "../../memory/db-connection.js";
-import { enqueueMemoryJob } from "../../memory/jobs-store.js";
+import {
+  enqueueMemoryJob,
+  isMemoryEnabled,
+} from "../../memory/jobs-store.js";
 import { conversationStarters, memoryJobs } from "../../memory/schema.js";
 import { NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -203,7 +206,7 @@ function handleListConversationStarters({
       checkpointAhead ||
       (invalidItemCount > 0 && totalActive > 0 && !withinCooldown);
 
-    if (shouldRefresh && !hasActiveJob) {
+    if (shouldRefresh && !hasActiveJob && isMemoryEnabled()) {
       enqueueMemoryJob("generate_conversation_starters", { scopeId });
       hasActiveJob = true;
     }
@@ -225,7 +228,7 @@ function handleListConversationStarters({
 
   const existing = hasActiveConversationStarterJob(db, scopeId);
 
-  if (!existing) {
+  if (!existing && isMemoryEnabled()) {
     enqueueMemoryJob("generate_conversation_starters", { scopeId });
   }
 

package/src/runtime/routes/disk-pressure-routes.ts

@@ -11,7 +11,7 @@ import type { RouteDefinition } from "./types.js";
 
 const DiskPressureStatusSchema = z.object({
   enabled: z.boolean(),
-  state: z.enum(["disabled", "ok", "critical", "unknown"]),
+  state: z.enum(["disabled", "ok", "warning", "critical", "unknown"]),
   locked: z.boolean(),
   acknowledged: z.boolean(),
   overrideActive: z.boolean(),

package/src/runtime/routes/document-comments-routes.ts

@@ -0,0 +1,287 @@
+/**
+ * Route handlers for document comment CRUD operations.
+ *
+ * Exposes comment management over HTTP, delegating to the store layer in
+ * `documents/document-comments-store.ts`.
+ */
+import { z } from "zod";
+
+import {
+  createComment,
+  deleteComment,
+  getComment,
+  listComments,
+  reopenComment,
+  resolveComment,
+  updateCommentContent,
+} from "../../documents/document-comments-store.js";
+import { getLogger } from "../../util/logger.js";
+import { broadcastMessage } from "../assistant-event-hub.js";
+import { BadRequestError, NotFoundError } from "./errors.js";
+import type { RouteDefinition } from "./types.js";
+
+const log = getLogger("document-comments-routes");
+
+// ---------------------------------------------------------------------------
+// Request schemas
+// ---------------------------------------------------------------------------
+
+const listQuerySchema = z.object({
+  status: z
+    .enum(["open", "resolved", "all"])
+    .default("all")
+    .describe("Filter by comment status"),
+});
+
+const createBodySchema = z.object({
+  content: z.string().min(1).describe("Comment text content"),
+  author: z.literal("user").optional().default("user").describe("Comment author"),
+  anchorStart: z
+    .number()
+    .nullable()
+    .optional()
+    .describe("Selection start offset"),
+  anchorEnd: z.number().nullable().optional().describe("Selection end offset"),
+  anchorText: z
+    .string()
+    .nullable()
+    .optional()
+    .describe("Anchored text snippet"),
+  parentCommentId: z
+    .string()
+    .nullable()
+    .optional()
+    .describe("Parent comment ID for replies"),
+  conversationId: z.string().describe("Owning conversation ID"),
+});
+
+const updateBodySchema = z
+  .object({
+    status: z
+      .enum(["open", "resolved"])
+      .optional()
+      .describe("New comment status"),
+    content: z.string().min(1).optional().describe("Updated comment text"),
+    resolvedBy: z.string().optional().describe("Who resolved the comment"),
+  })
+  .refine((data) => data.status !== undefined || data.content !== undefined, {
+    message: "At least one of status or content must be provided",
+  });
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "listDocumentComments",
+    endpoint: "documents/:id/comments",
+    method: "GET",
+    policyKey: "documents",
+    requirePolicyEnforcement: true,
+    summary: "List comments for a document",
+    description:
+      "Return comments for a document, optionally filtered by status.",
+    tags: ["documents"],
+    queryParams: [
+      {
+        name: "status",
+        schema: { type: "string", enum: ["open", "resolved", "all"] },
+        description: "Filter by comment status (default: all)",
+      },
+    ],
+    responseBody: z.object({
+      comments: z.array(z.unknown()).describe("Comment records"),
+    }),
+    handler: ({ pathParams, queryParams }) => {
+      const parsed = listQuerySchema.safeParse(queryParams ?? {});
+      if (!parsed.success) {
+        throw new BadRequestError(parsed.error.issues[0].message);
+      }
+      const { status } = parsed.data;
+      const comments = listComments(pathParams!.id, { status });
+      return { comments };
+    },
+  },
+
+  {
+    operationId: "createDocumentComment",
+    endpoint: "documents/:id/comments",
+    method: "POST",
+    policyKey: "documents",
+    requirePolicyEnforcement: true,
+    summary: "Create a comment on a document",
+    description: "Add a new comment to a document.",
+    tags: ["documents"],
+    requestBody: createBodySchema,
+    responseBody: z.object({
+      id: z.string(),
+      surfaceId: z.string(),
+      conversationId: z.string(),
+      author: z.string(),
+      content: z.string(),
+      status: z.string(),
+      createdAt: z.number(),
+      updatedAt: z.number(),
+    }),
+    handler: ({ pathParams, body }) => {
+      const parsed = createBodySchema.safeParse(body ?? {});
+      if (!parsed.success) {
+        throw new BadRequestError(parsed.error.issues[0].message);
+      }
+      const {
+        content,
+        author,
+        anchorStart,
+        anchorEnd,
+        anchorText,
+        parentCommentId,
+        conversationId,
+      } = parsed.data;
+      const comment = createComment({
+        surfaceId: pathParams!.id,
+        conversationId,
+        author,
+        content,
+        anchorStart,
+        anchorEnd,
+        anchorText,
+        parentCommentId,
+      });
+      broadcastMessage(
+        {
+          type: "document_comment_created",
+          conversationId,
+          surfaceId: pathParams!.id,
+          comment: {
+            id: comment.id,
+            surfaceId: comment.surfaceId,
+            author: comment.author,
+            content: comment.content,
+            anchorStart: comment.anchorStart ?? undefined,
+            anchorEnd: comment.anchorEnd ?? undefined,
+            anchorText: comment.anchorText ?? undefined,
+            parentCommentId: comment.parentCommentId ?? undefined,
+            status: comment.status,
+            createdAt: comment.createdAt,
+            updatedAt: comment.updatedAt,
+          },
+        },
+        conversationId,
+      );
+      log.info(
+        { id: comment.id, surfaceId: pathParams!.id },
+        "Created document comment via HTTP",
+      );
+      return comment;
+    },
+  },
+
+  {
+    operationId: "updateDocumentComment",
+    endpoint: "documents/:id/comments/:commentId",
+    method: "PATCH",
+    policyKey: "documents",
+    requirePolicyEnforcement: true,
+    summary: "Update a document comment",
+    description: "Update the status or content of a comment.",
+    tags: ["documents"],
+    requestBody: updateBodySchema,
+    responseBody: z.object({
+      id: z.string(),
+      surfaceId: z.string(),
+      content: z.string(),
+      status: z.string(),
+      updatedAt: z.number(),
+    }),
+    handler: ({ pathParams, body }) => {
+      const parsed = updateBodySchema.safeParse(body ?? {});
+      if (!parsed.success) {
+        throw new BadRequestError(parsed.error.issues[0].message);
+      }
+      const { status, content, resolvedBy } = parsed.data;
+      const commentId = pathParams!.commentId;
+
+      const existing = getComment(commentId);
+      if (!existing || existing.surfaceId !== pathParams!.id) {
+        throw new NotFoundError("Comment not found");
+      }
+
+      if (status === "resolved") {
+        resolveComment(commentId, resolvedBy ?? "user");
+        broadcastMessage(
+          {
+            type: "document_comment_resolved",
+            conversationId: existing.conversationId,
+            surfaceId: pathParams!.id,
+            commentId,
+            resolvedBy: resolvedBy ?? "user",
+          },
+          existing.conversationId,
+        );
+      } else if (status === "open") {
+        reopenComment(commentId);
+        broadcastMessage(
+          {
+            type: "document_comment_reopened",
+            conversationId: existing.conversationId,
+            surfaceId: pathParams!.id,
+            commentId,
+          },
+          existing.conversationId,
+        );
+      }
+
+      if (content !== undefined) {
+        updateCommentContent(commentId, content);
+      }
+
+      const updated = getComment(commentId);
+      if (!updated) {
+        throw new NotFoundError("Comment not found after update");
+      }
+
+      log.info(
+        { id: commentId, surfaceId: pathParams!.id },
+        "Updated document comment via HTTP",
+      );
+      return updated;
+    },
+  },
+
+  {
+    operationId: "deleteDocumentComment",
+    endpoint: "documents/:id/comments/:commentId",
+    method: "DELETE",
+    policyKey: "documents",
+    requirePolicyEnforcement: true,
+    summary: "Delete a document comment",
+    description: "Permanently delete a comment.",
+    tags: ["documents"],
+    responseBody: z.object({
+      success: z.literal(true),
+    }),
+    handler: ({ pathParams }) => {
+      const commentId = pathParams!.commentId;
+      const existing = getComment(commentId);
+      if (!existing || existing.surfaceId !== pathParams!.id) {
+        throw new NotFoundError("Comment not found");
+      }
+      deleteComment(commentId);
+      broadcastMessage(
+        {
+          type: "document_comment_deleted",
+          conversationId: existing.conversationId,
+          surfaceId: pathParams!.id,
+          commentId,
+        },
+        existing.conversationId,
+      );
+      log.info(
+        { id: commentId, surfaceId: pathParams!.id },
+        "Deleted document comment via HTTP",
+      );
+      return { success: true as const };
+    },
+  },
+];

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

@@ -7,6 +7,7 @@
 import { z } from "zod";
 
 import {
+  addDocumentConversation,
   getDocumentById,
   getDocumentsForConversation,
   saveDocument,
@@ -181,6 +182,38 @@ export const ROUTES: RouteDefinition[] = [
     },
   },
 
+  {
+    operationId: "linkDocumentConversation",
+    endpoint: "documents/:id/conversations",
+    method: "POST",
+    policyKey: "documents",
+    requirePolicyEnforcement: true,
+    summary: "Link a document to a conversation",
+    description:
+      "Associate a document with a conversation so the assistant sees it as context.",
+    tags: ["documents"],
+    requestBody: z.object({
+      conversationId: z.string().describe("Conversation to link"),
+    }),
+    responseBody: z.object({ success: z.literal(true) }),
+    handler: ({ pathParams, body }) => {
+      const { conversationId } = (body ?? {}) as { conversationId?: string };
+      if (!conversationId) {
+        throw new BadRequestError("conversationId is required");
+      }
+      const doc = getDocumentById(pathParams!.id);
+      if (!doc) {
+        throw new NotFoundError("Document not found");
+      }
+      addDocumentConversation(pathParams!.id, conversationId);
+      log.info(
+        { surfaceId: pathParams!.id, conversationId },
+        "Linked document to conversation",
+      );
+      return { success: true as const };
+    },
+  },
+
   {
     operationId: "exportDocumentPDF",
     endpoint: "documents/:id/pdf",

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

@@ -35,7 +35,10 @@ async function requireClient(): Promise<VellumPlatformClient> {
 // ── Handlers ──────────────────────────────────────────────────────────
 
 async function handleDomainRegister({ body = {} }: RouteHandlerArgs) {
-  const { subdomain } = body as { subdomain?: string };
+  const { subdomain, email_username } = body as {
+    subdomain?: string;
+    email_username?: string;
+  };
   const client = await requireClient();
   const apexDomain = getApexDomain();
 
@@ -43,6 +46,9 @@ async function handleDomainRegister({ body = {} }: RouteHandlerArgs) {
   if (subdomain) {
     reqBody.subdomain = subdomain;
   }
+  if (email_username) {
+    reqBody.email_username = email_username;
+  }
 
   const response = await client.fetch(
     `/v1/assistants/${client.platformAssistantId}/domains/`,
@@ -58,12 +64,18 @@ async function handleDomainRegister({ body = {} }: RouteHandlerArgs) {
       string,
       unknown
     >;
+    const firstFieldError = ["subdomain", "email_username"].reduce<
+      string | undefined
+    >(
+      (found, field) =>
+        found ??
+        (Array.isArray(respBody[field])
+          ? (respBody[field][0] as string)
+          : undefined),
+      undefined,
+    );
     const detail =
-      respBody.detail ??
-      (Array.isArray(respBody.subdomain)
-        ? respBody.subdomain[0]
-        : undefined) ??
-      `HTTP ${response.status}`;
+      respBody.detail ?? firstFieldError ?? `HTTP ${response.status}`;
     throw new BadRequestError(String(detail));
   }
 
@@ -71,10 +83,9 @@ async function handleDomainRegister({ body = {} }: RouteHandlerArgs) {
     id: string;
     subdomain?: string;
     domain?: string;
-    status?: string;
-    verified?: boolean;
     created_at?: string;
     created?: string;
+    email_error?: { detail: string; code: string };
   };
 
   // Persist the subdomain to config so getAssistantDomain() can use it
@@ -117,8 +128,6 @@ async function handleDomainStatus(_args: RouteHandlerArgs) {
       id: string;
       subdomain?: string;
       domain?: string;
-      status?: string;
-      verified?: boolean;
       created_at?: string;
       created?: string;
     }[];
@@ -145,6 +154,39 @@ async function handleDomainStatus(_args: RouteHandlerArgs) {
   return data;
 }
 
+async function handleDomainVerificationStatus({
+  body = {},
+}: RouteHandlerArgs) {
+  const { domain_id } = body as { domain_id?: string };
+  if (!domain_id) {
+    throw new BadRequestError("domain_id is required");
+  }
+  const client = await requireClient();
+
+  const response = await client.fetch(
+    `/v1/assistants/${client.platformAssistantId}/domains/${domain_id}/verification-status/`,
+  );
+
+  if (!response.ok) {
+    const respBody = (await response.json().catch(() => ({}))) as Record<
+      string,
+      unknown
+    >;
+    const detail = respBody.detail ?? `HTTP ${response.status}`;
+    throw new RouteError(
+      String(detail),
+      "VERIFICATION_STATUS_FAILED",
+      response.status,
+    );
+  }
+
+  return (await response.json()) as {
+    domain: string;
+    status: string;
+    message: string;
+  };
+}
+
 // ── Route definitions ─────────────────────────────────────────────────
 
 export const ROUTES: RouteDefinition[] = [
@@ -164,4 +206,12 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Show domain registration and health",
     tags: ["domain"],
   },
+  {
+    operationId: "domain_verification_status",
+    endpoint: "domain/verification-status",
+    method: "POST",
+    handler: handleDomainVerificationStatus,
+    summary: "Get live DNS verification status for a domain",
+    tags: ["domain"],
+  },
 ];

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

@@ -277,13 +277,16 @@ async function handleEmailSend({ body = {} }: RouteHandlerArgs) {
 
   const fromAddress = addresses[0].address;
 
+  // LLMs often produce literal "\n" escape sequences instead of real newlines.
+  const normalizedText = text?.replace(/\\n/g, "\n") ?? "";
+
   // Auto-generate HTML from text if not provided
-  const resolvedHtml = html ?? markdownToEmailHtml(text);
+  const resolvedHtml = html ?? markdownToEmailHtml(normalizedText);
 
   const payload: Record<string, unknown> = {
     to,
     from_address: fromAddress,
-    text,
+    text: normalizedText,
   };
   if (subject) payload.subject = subject;
   if (resolvedHtml) payload.html = resolvedHtml;

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

@@ -26,6 +26,7 @@ import { z } from "zod";
 import type { HostProxyCapability } from "../../channels/types.js";
 import { parseInterfaceId, supportsHostProxy } from "../../channels/types.js";
 import { emitContactChange } from "../../contacts/contact-events.js";
+import { getConversation } from "../../memory/conversation-crud.js";
 import { getOrCreateConversation } from "../../memory/conversation-key-store.js";
 import { getLogger } from "../../util/logger.js";
 import { formatSseFrame, formatSseHeartbeat } from "../assistant-event.js";
@@ -39,7 +40,11 @@ import {
   assistantEventHub,
 } from "../assistant-event-hub.js";
 import { resolveActorPrincipalIdForLocalGuardian } from "../local-actor-identity.js";
-import { BadRequestError, ServiceUnavailableError } from "./errors.js";
+import {
+  BadRequestError,
+  NotFoundError,
+  ServiceUnavailableError,
+} from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("events-routes");
@@ -220,9 +225,17 @@ const defaultSseShedReporter: SseShedReporter = (reason, inst) => {
  * Stream assistant events as Server-Sent Events.
  *
  * Query params:
- *   conversationKey -- optional; when provided, scopes the stream to one
- *                      conversation. When omitted, the stream delivers events
- *                      from ALL conversations for this assistant.
+ *   conversationId  -- optional; assistant-minted internal conversation id.
+ *                      When provided, the stream is scoped to that one
+ *                      conversation; the daemon 404s if no such conversation
+ *                      exists (clients must obtain the id from a prior
+ *                      response).
+ *   conversationKey -- optional; external key (non-vellum channels) or the
+ *                      web idempotency key. Resolved via the conversation
+ *                      keys table; materializes a row on first use.
+ *                      Ignored when `conversationId` is also provided.
+ *   When both are omitted, the stream delivers events from ALL
+ *   conversations for this assistant.
  *
  * Headers (optional):
  *   X-Vellum-Client-Id    -- stable per-install UUID identifying this client.
@@ -248,8 +261,18 @@ export function handleSubscribeAssistantEvents(
 ): ReadableStream<Uint8Array> {
   const { queryParams, headers, abortSignal } = args;
 
-  const conversationKey = queryParams?.conversationKey;
-  if ("conversationKey" in (queryParams ?? {}) && !conversationKey?.trim()) {
+  const rawConversationId = queryParams?.conversationId;
+  const rawConversationKey = queryParams?.conversationKey;
+  if (
+    "conversationId" in (queryParams ?? {}) &&
+    !rawConversationId?.trim()
+  ) {
+    throw new BadRequestError("conversationId must not be empty");
+  }
+  if (
+    "conversationKey" in (queryParams ?? {}) &&
+    !rawConversationKey?.trim()
+  ) {
     throw new BadRequestError("conversationKey must not be empty");
   }
 
@@ -293,10 +316,25 @@ export function handleSubscribeAssistantEvents(
     "host_browser",
   ];
 
+  // Resolve the scope. `conversationId` (when supplied) is the
+  // assistant-minted internal id — looked up directly; 404 if absent.
+  // Otherwise fall through to `conversationKey`, which is treated as an
+  // external key and resolved via the conversation_keys table
+  // (materialized on first use, preserving the existing subscribe-time
+  // create behavior for the web idempotency flow).
   const filter: AssistantEventFilter = {};
-  if (conversationKey) {
-    const mapping = getOrCreateConversation(conversationKey);
+  let scopeConversationKey: string | null = null;
+  if (rawConversationId) {
+    const existing = getConversation(rawConversationId);
+    if (!existing) {
+      throw new NotFoundError(`Conversation ${rawConversationId} not found`);
+    }
+    filter.conversationId = existing.id;
+    scopeConversationKey = existing.id;
+  } else if (rawConversationKey) {
+    const mapping = getOrCreateConversation(rawConversationKey);
     filter.conversationId = mapping.conversationId;
+    scopeConversationKey = rawConversationKey;
   }
 
   const encoder = new TextEncoder();
@@ -316,7 +354,7 @@ export function handleSubscribeAssistantEvents(
     heartbeatsSent: 0,
     clientId,
     interfaceId,
-    conversationKey: conversationKey ?? null,
+    conversationKey: scopeConversationKey,
   };
 
   ensureEventLoopDelayMonitorStarted();
@@ -470,9 +508,15 @@ export const ROUTES: RouteDefinition[] = [
     description: "Stream assistant events as Server-Sent Events (SSE).",
     tags: ["events"],
     queryParams: [
+      {
+        name: "conversationId",
+        description:
+          "Scope to a single conversation by its assistant-minted internal id. 404s if no such conversation exists.",
+      },
       {
         name: "conversationKey",
-        description: "Scope to a single conversation",
+        description:
+          "Scope to a single conversation by an external key (non-vellum channels) or the web idempotency key. Materializes a row on first use. Ignored when conversationId is also provided.",
       },
     ],
     responseHeaders: {