@vellumai/assistant 0.8.10 → 0.8.11-staging.1

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

@@ -15,6 +15,7 @@ import {
 } from "../../config/env.js";
 import { loadRawConfig, saveRawConfig } from "../../config/loader.js";
 import { loadSkillCatalog } from "../../config/skills.js";
+import { findConversation } from "../../daemon/conversation-registry.js";
 import {
   computeGatewayTarget,
   getIngressConfigResult,
@@ -41,7 +42,7 @@ import {
   type ManifestOverride,
   resolveExecutionTarget,
 } from "../../tools/execution-target.js";
-import { getAllTools, getTool } from "../../tools/registry.js";
+import { getAllTools, getTool, getToolOwner } from "../../tools/registry.js";
 import {
   ACTIVITY_SKIP_SET,
   injectActivityField,
@@ -80,10 +81,7 @@ function handleVoiceConfigUpdate({ body = {} }: RouteHandlerArgs) {
 // Avatar generation
 // ---------------------------------------------------------------------------
 
-async function handleGenerateAvatar({
-  body = {},
-  headers,
-}: RouteHandlerArgs) {
+async function handleGenerateAvatar({ body = {}, headers }: RouteHandlerArgs) {
   const { description } = body as { description?: string };
   if (!description?.trim()) {
     throw new BadRequestError("Description is required.");
@@ -380,14 +378,32 @@ function resolveManifestOverride(
   return undefined;
 }
 
-function handleToolNamesList() {
+type SchemaShape = {
+  type: string;
+  properties?: Record<string, unknown>;
+  required?: string[];
+};
+
+interface ToolNamesListResponse {
+  names: string[];
+  schemas: Record<string, SchemaShape>;
+  tools: ToolListEntry[];
+}
+
+/**
+ * Tool inventory. With no `conversationId`, reports every tool in the
+ * global registry (plus skill-manifest tools not yet loaded, for the
+ * permission-simulator catalog). With a `conversationId`, scopes the
+ * inventory to the tools available to that conversation as of its most
+ * recent turn — see {@link handleConversationToolList}.
+ */
+function handleToolNamesList(conversationId?: string): ToolNamesListResponse {
+  if (conversationId) {
+    return handleConversationToolList(conversationId);
+  }
+
   const tools = getAllTools();
   const nameSet = new Set(tools.map((t) => t.name));
-  type SchemaShape = {
-    type: string;
-    properties?: Record<string, unknown>;
-    required?: string[];
-  };
   const schemas: Record<string, SchemaShape> = {};
 
   const rawDefs: ToolDefinition[] = tools;
@@ -419,7 +435,89 @@ function handleToolNamesList() {
   }
 
   const names = Array.from(nameSet).sort((a, b) => a.localeCompare(b));
-  return { names, schemas };
+  return { names, schemas, tools: buildRegisteredToolEntries() };
+}
+
+/**
+ * Scope the tool inventory to a single conversation. Conversations gain
+ * tools over their lifecycle (skill loads, MCP reloads), so the global
+ * registry over-reports what a given conversation can actually call. We
+ * read the conversation's turn snapshot (`getRegisteredToolNames()`) — a
+ * pure read that does not re-run the side-effecting `resolveTools`
+ * callback — and resolve each name's metadata/schema from the registry.
+ */
+function handleConversationToolList(
+  conversationId: string,
+): ToolNamesListResponse {
+  const conversation = findConversation(conversationId);
+  if (!conversation) {
+    throw new NotFoundError(
+      `No active conversation "${conversationId}". Run 'assistant conversations list' to see active conversations.`,
+    );
+  }
+
+  const names = Array.from(conversation.getRegisteredToolNames()).sort((a, b) =>
+    a.localeCompare(b),
+  );
+
+  const schemaByName = new Map<string, SchemaShape>(
+    injectActivityField(getAllTools(), ACTIVITY_SKIP_SET).map((d) => [
+      d.name,
+      d.input_schema as SchemaShape,
+    ]),
+  );
+
+  const schemas: Record<string, SchemaShape> = {};
+  const tools: ToolListEntry[] = [];
+  for (const name of names) {
+    const schema = schemaByName.get(name);
+    if (schema) schemas[name] = schema;
+    tools.push(toolEntryForName(name));
+  }
+
+  return { names, schemas, tools };
+}
+
+interface ToolListEntry {
+  name: string;
+  description: string;
+  riskLevel: string;
+  category: string;
+  /** Tool origin: "core" for built-ins, otherwise "<kind>:<id>" (e.g. "plugin:echo"). */
+  source: string;
+}
+
+/**
+ * Build a catalog entry for one tool name, reading metadata and ownership
+ * from the registry (the single source of truth) rather than off any
+ * caller-supplied object, so `source` cannot be spoofed by a manifest
+ * field. `source` is `core` for built-ins, `<kind>:<id>` for an owned tool
+ * (e.g. `plugin:echo`), and `unknown` for a name no longer in the registry
+ * (e.g. a conversation snapshot referencing a since-unloaded skill tool).
+ */
+function toolEntryForName(name: string): ToolListEntry {
+  const tool = getTool(name);
+  const owner = getToolOwner(name);
+  return {
+    name,
+    description: tool?.description ?? "",
+    riskLevel: tool?.defaultRiskLevel ?? "unknown",
+    category: tool?.category ?? "",
+    source: owner ? `${owner.kind}:${owner.id}` : tool ? "core" : "unknown",
+  };
+}
+
+/**
+ * Build the registered-tool inventory with the metadata a catalog view
+ * needs: description, author-asserted risk band, category, and the
+ * extension that contributed the tool. Sorted by name for stable output.
+ * Covers only tools loaded into the registry; skill tools whose manifests
+ * are present but not yet loaded appear in `names`/`schemas` but not here.
+ */
+function buildRegisteredToolEntries(): ToolListEntry[] {
+  return getAllTools()
+    .map((tool) => toolEntryForName(tool.name))
+    .sort((a, b) => a.name.localeCompare(b.name));
 }
 
 async function handleToolPermissionSimulate({ body = {} }: RouteHandlerArgs) {
@@ -766,11 +864,38 @@ export const ROUTES: RouteDefinition[] = [
       requiredScopes: ["settings.read"],
       allowedPrincipalTypes: ACTOR_PRINCIPALS,
     },
-    summary: "List tools",
+    summary: "List registered tools with metadata and schemas",
     description:
-      "Return available tool names with their descriptions, risk levels, and categories.",
+      "Return registered tools. Without `conversationId`, returns every tool in the global registry; `tools` carries per-tool metadata (description, author-asserted risk level, category, and contributing source: core, skill, plugin, or MCP server) and `names`/`schemas` additionally cover skill tools whose manifests are present but not yet loaded, for the permission-simulator catalog. With `conversationId`, scopes the result to the tools available to that conversation as of its most recent turn (including skill/MCP tools registered over its lifecycle); 404 if no such conversation is active.",
     tags: ["tools"],
-    handler: () => handleToolNamesList(),
+    queryParams: [
+      {
+        name: "conversationId",
+        type: "string",
+        required: false,
+        description:
+          "When set, scope the tool inventory to this conversation's most recent turn instead of the global registry.",
+      },
+    ],
+    responseBody: z.object({
+      names: z.array(z.string()),
+      schemas: z.record(z.string(), z.record(z.string(), z.unknown())),
+      tools: z.array(
+        z.object({
+          name: z.string(),
+          description: z.string(),
+          riskLevel: z.string(),
+          category: z.string(),
+          source: z
+            .string()
+            .describe(
+              'Tool origin: "core" for built-ins, otherwise "<kind>:<id>" (e.g. "plugin:echo", "skill:my-skill", "mcp:server").',
+            ),
+        }),
+      ),
+    }),
+    handler: ({ queryParams }) =>
+      handleToolNamesList(queryParams?.conversationId),
   },
   {
     operationId: "tools_simulate_permission_post",

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

@@ -49,10 +49,22 @@ const slimSkillBase = {
   category: z.string(),
 };
 
+// Extension that ships a skill, mirroring the tool registry's OwnerInfo.
+// Plugin-resident skills carry `{ kind: "plugin", id: <plugin dir name> }` so
+// clients can attribute them instead of collapsing to their kind/origin.
+const skillOwnerSchema = z
+  .object({
+    kind: z.enum(["skill", "mcp", "plugin", "workspace"]),
+    id: z.string(),
+  })
+  .optional();
+
+const slimSkillBaseWithOwner = { ...slimSkillBase, owner: skillOwnerSchema };
+
 const slimSkillSchema = z.discriminatedUnion("origin", [
-  z.object({ ...slimSkillBase, origin: z.literal("vellum") }),
+  z.object({ ...slimSkillBaseWithOwner, origin: z.literal("vellum") }),
   z.object({
-    ...slimSkillBase,
+    ...slimSkillBaseWithOwner,
     origin: z.literal("clawhub"),
     slug: z.string(),
     author: z.string(),
@@ -63,18 +75,18 @@ const slimSkillSchema = z.discriminatedUnion("origin", [
     version: z.string(),
   }),
   z.object({
-    ...slimSkillBase,
+    ...slimSkillBaseWithOwner,
     origin: z.literal("skillssh"),
     slug: z.string(),
     sourceRepo: z.string(),
     installs: z.number(),
     audit: z.record(z.string(), partnerAuditSchema).optional(),
   }),
-  z.object({ ...slimSkillBase, origin: z.literal("custom") }),
+  z.object({ ...slimSkillBaseWithOwner, origin: z.literal("custom") }),
 ]);
 
 const skillDetailSchema = z.discriminatedUnion("origin", [
-  z.object({ ...slimSkillBase, origin: z.literal("vellum") }),
+  z.object({ ...slimSkillBaseWithOwner, origin: z.literal("vellum") }),
   z.object({
     ...slimSkillBase,
     origin: z.literal("clawhub"),
@@ -120,7 +132,7 @@ const skillDetailSchema = z.discriminatedUnion("origin", [
     installs: z.number(),
     audit: z.record(z.string(), partnerAuditSchema).optional(),
   }),
-  z.object({ ...slimSkillBase, origin: z.literal("custom") }),
+  z.object({ ...slimSkillBaseWithOwner, origin: z.literal("custom") }),
 ]);
 
 // ---------------------------------------------------------------------------

package/src/runtime/services/__tests__/conversation-serializer.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Unit tests for `serializeConversationSummary` — specifically the wire-level
+ * `groupId` normalization for surfaced conversations.
+ *
+ * Surfaced rows (`surfaced_at IS NOT NULL`) must serialize with
+ * `groupId: "system:all"` when their persisted group is the system
+ * Background/Scheduled bucket (or null), so legacy clients that bucket purely
+ * by `groupId` (macOS Swift app) render them in Recents without decoding
+ * `surfacedAt`. The persisted DB value is untouched — clearing `surfaced_at`
+ * (demotion) makes serialization return the original group again.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import type { ConversationRow } from "../../../memory/conversation-crud.js";
+import { serializeConversationSummary } from "../conversation-serializer.js";
+
+function makeConversationRow(
+  overrides: Partial<ConversationRow> = {},
+): ConversationRow {
+  return {
+    id: "conv-123",
+    title: "Background run",
+    createdAt: 1000,
+    updatedAt: 2000,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalEstimatedCost: 0,
+    contextSummary: null,
+    contextCompactedMessageCount: 0,
+    contextCompactedAt: null,
+    historyStrippedAt: null,
+    slackContextCompactionWatermarkTs: null,
+    slackContextCompactionWatermarkAt: null,
+    conversationType: "background",
+    source: "task",
+    memoryScopeId: "default",
+    originChannel: null,
+    originInterface: null,
+    forkParentConversationId: null,
+    forkParentMessageId: null,
+    isAutoTitle: 0,
+    scheduleJobId: null,
+    lastMessageAt: 3000,
+    archivedAt: null,
+    surfacedAt: null,
+    inferenceProfile: null,
+    inferenceProfileSessionId: null,
+    inferenceProfileExpiresAt: null,
+    lastNotifiedInferenceProfile: null,
+    ...overrides,
+  };
+}
+
+function serialize(
+  conversation: ConversationRow,
+  groupId: string | null = null,
+  isPinned = false,
+) {
+  return serializeConversationSummary({
+    conversation,
+    displayMeta: { displayOrder: null, isPinned, groupId },
+    parentCache: new Map(),
+    isProcessing: false,
+  });
+}
+
+describe("serializeConversationSummary · surfaced groupId normalization", () => {
+  test("surfaced row with persisted system:background serializes as system:all", () => {
+    const summary = serialize(
+      makeConversationRow({ surfacedAt: 1704067200000 }),
+      "system:background",
+    );
+    expect(summary.groupId).toBe("system:all");
+    expect(summary.surfacedAt).toBe(1704067200000);
+  });
+
+  test("surfaced row with persisted system:scheduled serializes as system:all", () => {
+    const summary = serialize(
+      makeConversationRow({
+        conversationType: "scheduled",
+        source: "schedule",
+        surfacedAt: 1704067200000,
+      }),
+      "system:scheduled",
+    );
+    expect(summary.groupId).toBe("system:all");
+    expect(summary.surfacedAt).toBe(1704067200000);
+  });
+
+  test("surfaced row with null persisted group serializes as system:all", () => {
+    // Legacy clients re-derive a null groupId into Background/Scheduled from
+    // `source`, so the surfaced normalization must cover the null case too.
+    const summary = serialize(
+      makeConversationRow({ surfacedAt: 1704067200000 }),
+      null,
+    );
+    expect(summary.groupId).toBe("system:all");
+  });
+
+  test("after demotion (surfaced_at cleared) the original group comes back", () => {
+    const summary = serialize(
+      makeConversationRow({ surfacedAt: null }),
+      "system:background",
+    );
+    expect(summary.groupId).toBe("system:background");
+    expect(summary.surfacedAt).toBeUndefined();
+  });
+
+  test("a custom group wins over surfacing", () => {
+    // Mirrors web's getEffectiveGroupId precedence: user-created groups
+    // take priority over the surfaced promotion.
+    const summary = serialize(
+      makeConversationRow({ surfacedAt: 1704067200000 }),
+      "group-custom-1",
+    );
+    expect(summary.groupId).toBe("group-custom-1");
+    expect(summary.surfacedAt).toBe(1704067200000);
+  });
+
+  test("a pin wins over surfacing", () => {
+    const summary = serialize(
+      makeConversationRow({ surfacedAt: 1704067200000 }),
+      "system:pinned",
+      true,
+    );
+    expect(summary.groupId).toBe("system:pinned");
+    expect("isPinned" in summary && summary.isPinned).toBe(true);
+  });
+
+  test("non-surfaced rows pass the persisted group through untouched", () => {
+    expect(serialize(makeConversationRow(), null).groupId).toBeNull();
+    expect(serialize(makeConversationRow(), "system:scheduled").groupId).toBe(
+      "system:scheduled",
+    );
+    expect(serialize(makeConversationRow(), "group-custom-1").groupId).toBe(
+      "group-custom-1",
+    );
+  });
+});

package/src/runtime/services/conversation-serializer.ts

@@ -94,6 +94,37 @@ function buildForkParent(
   };
 }
 
+/**
+ * Resolve the wire-level `groupId` for a conversation summary.
+ *
+ * Surfaced conversations (`surfaced_at IS NOT NULL`) render in the Recents
+ * grouping on every client, but legacy clients (the macOS Swift app) bucket
+ * purely by `groupId` and do not decode `surfacedAt`. Normalize the
+ * *serialized* `groupId` to `"system:all"` for surfaced rows so those
+ * clients render them in Recents without code changes — the persisted
+ * `group_id` is untouched, so clearing `surfaced_at` (demotion) makes
+ * serialization return the original group again.
+ *
+ * Mirrors web's `getEffectiveGroupId` precedence: an explicit pin
+ * (`system:pinned`) or a user-created custom group wins over surfacing, so
+ * only the system Background/Scheduled groups (and the null fallback, which
+ * legacy clients re-derive into those buckets from `source`) are rewritten.
+ */
+function resolveSerializedGroupId(
+  conversation: ConversationRow,
+  persistedGroupId: string | null,
+): string | null {
+  if (conversation.surfacedAt == null) return persistedGroupId;
+  if (
+    persistedGroupId == null ||
+    persistedGroupId === "system:background" ||
+    persistedGroupId === "system:scheduled"
+  ) {
+    return "system:all";
+  }
+  return persistedGroupId;
+}
+
 function buildChannelBinding(binding: ExternalConversationBinding) {
   const externalChatName =
     binding.externalChatName?.trim() ||
@@ -213,11 +244,17 @@ export function serializeConversationSummary(params: {
             displayOrder: displayMeta.displayOrder,
           }
         : {}),
-    groupId: displayMeta?.groupId ?? null,
+    groupId: resolveSerializedGroupId(
+      conversation,
+      displayMeta?.groupId ?? null,
+    ),
     ...(forkParent ? { forkParent } : {}),
     ...(conversation.archivedAt != null
       ? { archivedAt: conversation.archivedAt }
       : {}),
+    ...(conversation.surfacedAt != null
+      ? { surfacedAt: conversation.surfacedAt }
+      : {}),
     ...(conversation.inferenceProfile != null
       ? { inferenceProfile: conversation.inferenceProfile }
       : {}),

package/src/runtime/verification-outbound-actions.ts

@@ -2,7 +2,7 @@
  * Shared outbound verification action logic.
  *
  * These pure functions encapsulate the business logic for starting, resending,
- * and cancelling outbound verification flows (Telegram, voice, Slack).
+ * and cancelling outbound verification flows (Telegram, voice, Slack, email).
  * They return transport-agnostic result objects and are consumed by both the
  * message handler (config-channels.ts) and the HTTP route layer (channel-verification-routes.ts).
  */
@@ -26,6 +26,7 @@ import {
   updateSessionStatus,
 } from "./channel-verification-service.js";
 import {
+  composeVerificationEmail,
   composeVerificationSlack,
   composeVerificationTelegram,
   GUARDIAN_VERIFY_TEMPLATE_KEYS,
@@ -52,6 +53,8 @@ export const DESTINATION_RATE_WINDOW_MS = 3_600_000;
 /** Session TTL in seconds (matches challenge TTL of 10 minutes). */
 const SESSION_TTL_SECONDS = 600;
 
+const EMAIL_VERIFICATION_SUBJECT = "Vellum Assistant Guardian Verification";
+
 // ---------------------------------------------------------------------------
 // Telegram destination classification
 // ---------------------------------------------------------------------------
@@ -122,6 +125,8 @@ interface OutboundActionResult {
    *  reach the gateway.  The daemon HTTP route handler calls
    *  deliverVerificationSlack() after receiving this payload. */
   _pendingSlackDm?: { userId: string; text: string; assistantId: string };
+  /** Internal: email delivery payload for the caller to dispatch (same pattern as Slack). */
+  _pendingEmail?: { to: string; text: string; subject: string; assistantId: string };
 }
 
 // ---------------------------------------------------------------------------
@@ -512,6 +517,80 @@ export function deliverVerificationSlack(
   deliverVerificationSlackAsync(userId, text, assistantId);
 }
 
+// ---------------------------------------------------------------------------
+// Email delivery helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Deliver a verification email via the platform email send API.
+ * Fire-and-forget wrapper for use in the daemon process (HTTP route handlers).
+ */
+export function deliverVerificationEmail(
+  to: string,
+  text: string,
+  subject: string,
+  _assistantId: string,
+): void {
+  (async () => {
+    try {
+      const { VellumPlatformClient } = await import(
+        "../platform/client.js"
+      );
+      const client = await VellumPlatformClient.create();
+      if (!client?.platformAssistantId) {
+        log.error("Cannot deliver verification email: platform client not configured");
+        return;
+      }
+
+      const listResponse = await client.fetch(
+        `/v1/assistants/${client.platformAssistantId}/email-addresses/`,
+      );
+      if (!listResponse.ok) {
+        log.error({ status: listResponse.status }, "Failed to list email addresses for verification");
+        return;
+      }
+      const listData = (await listResponse.json()) as {
+        results: { address: string }[];
+      };
+      const addresses = listData.results ?? [];
+      if (addresses.length === 0) {
+        log.error("No email address registered — cannot deliver verification email");
+        return;
+      }
+      const fromAddress = addresses[0].address;
+
+      const { markdownToEmailHtml } = await import(
+        "../email/html-renderer.js"
+      );
+      const html = markdownToEmailHtml(text);
+
+      const response = await client.fetch("/v1/runtime-proxy/email/send/", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          to: [to],
+          from_address: fromAddress,
+          text,
+          subject,
+          html,
+        }),
+      });
+
+      if (response.ok) {
+        log.info({ to }, "Verification email delivered");
+      } else {
+        const respBody = await response.json().catch(() => ({}));
+        log.error(
+          { to, status: response.status, respBody },
+          "Failed to deliver verification email",
+        );
+      }
+    } catch (err) {
+      log.error({ err, to }, "Failed to deliver verification email");
+    }
+  })();
+}
+
 function startOutboundSlack(
   destination: string | undefined,
   assistantId: string,
@@ -644,13 +723,35 @@ function startOutboundEmail(
     verificationPurpose: "guardian",
   });
 
+  const emailBody = composeVerificationEmail(
+    GUARDIAN_VERIFY_TEMPLATE_KEYS.EMAIL_CHALLENGE_REQUEST,
+    {
+      code: sessionResult.secret,
+      expiresInMinutes: Math.floor(SESSION_TTL_SECONDS / 60),
+    },
+  );
+
+  const now = Date.now();
+  const nextResendAt = now + RESEND_COOLDOWN_MS;
+  const sendCount = 1;
+
+  updateSessionDelivery(sessionResult.sessionId, now, sendCount, nextResendAt);
+
   return {
     success: true,
     verificationSessionId: sessionResult.sessionId,
     secret: sessionResult.secret,
     expiresAt: sessionResult.expiresAt,
+    nextResendAt,
+    sendCount,
     channel,
     originConversationId,
+    _pendingEmail: {
+      to: normalizedEmail,
+      text: emailBody,
+      subject: EMAIL_VERIFICATION_SUBJECT,
+      assistantId,
+    },
   };
 }
 
@@ -851,12 +952,56 @@ export function resendOutbound(
       originConversationId,
       _pendingSlackDm: { userId: destination, text: slackBody, assistantId },
     };
+  } else if (channel === "email") {
+    const newSession = createOutboundSession({
+      channel,
+      expectedExternalUserId: destination,
+      expectedChatId: destination,
+      identityBindingStatus: "bound",
+      destinationAddress: destination,
+      verificationPurpose: "guardian",
+    });
+
+    const emailBody = composeVerificationEmail(
+      GUARDIAN_VERIFY_TEMPLATE_KEYS.EMAIL_RESEND,
+      {
+        code: newSession.secret,
+        expiresInMinutes: Math.floor(SESSION_TTL_SECONDS / 60),
+      },
+    );
+
+    const now = Date.now();
+    const newSendCount = currentSendCount + 1;
+    const nextResendAt = now + RESEND_COOLDOWN_MS;
+
+    updateSessionDelivery(
+      newSession.sessionId,
+      now,
+      newSendCount,
+      nextResendAt,
+    );
+
+    return {
+      success: true,
+      verificationSessionId: newSession.sessionId,
+      secret: newSession.secret,
+      nextResendAt,
+      sendCount: newSendCount,
+      channel,
+      originConversationId,
+      _pendingEmail: {
+        to: destination,
+        text: emailBody,
+        subject: EMAIL_VERIFICATION_SUBJECT,
+        assistantId,
+      },
+    };
   }
 
   return {
     success: false,
     error: "unsupported_channel",
-    message: `Resend is only supported for Telegram, phone, and Slack. Got: ${channel}`,
+    message: `Resend is only supported for Telegram, phone, Slack, and email. Got: ${channel}`,
     channel,
   };
 }