@vellumai/assistant 0.8.10 → 0.8.11-staging.1

package/src/runtime/verification-templates.ts

@@ -1,5 +1,5 @@
 /**
- * Template-only copy for outbound guardian verification messages (Telegram, Slack, and voice).
+ * Template-only copy for outbound guardian verification messages (Telegram, Slack, email, and voice).
  *
  * All outbound verification messages are composed from these templates
  * to prevent free-form caller/user text injection. Only typed variables
@@ -26,6 +26,10 @@ export const GUARDIAN_VERIFY_TEMPLATE_KEYS = {
     "guardian_verify.slack.trusted_contact_challenge",
   /** Resend Slack DM verification for inbound trusted contact (includes the code). */
   SLACK_TRUSTED_CONTACT_RESEND: "guardian_verify.slack.trusted_contact_resend",
+  /** Initial outbound email verification prompt (includes the code). */
+  EMAIL_CHALLENGE_REQUEST: "guardian_verify.email.challenge_request",
+  /** Resend email verification prompt (includes the code). */
+  EMAIL_RESEND: "guardian_verify.email.resend",
   /** Outbound voice call intro prompt: asks guardian to enter verification code via keypad. */
   VOICE_CALL_INTRO: "guardian_verify.voice.call_intro",
   /** Voice retry prompt after an incorrect code entry. */
@@ -42,7 +46,7 @@ export const GUARDIAN_VERIFY_TEMPLATE_KEYS = {
   CHANNEL_BOOTSTRAP_BOUND: "guardian_verify.channel.bootstrap_bound",
 } as const;
 
-/** Template keys for Telegram/Slack text-based verification messages. */
+/** Template keys for Telegram/Slack/email text-based verification messages. */
 type TextVerifyTemplateKey =
   | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.ALREADY_VERIFIED
   | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.TELEGRAM_CHALLENGE_REQUEST
@@ -50,7 +54,9 @@ type TextVerifyTemplateKey =
   | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.SLACK_CHALLENGE_REQUEST
   | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.SLACK_RESEND
   | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.SLACK_TRUSTED_CONTACT_CHALLENGE
-  | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.SLACK_TRUSTED_CONTACT_RESEND;
+  | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.SLACK_TRUSTED_CONTACT_RESEND
+  | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.EMAIL_CHALLENGE_REQUEST
+  | typeof GUARDIAN_VERIFY_TEMPLATE_KEYS.EMAIL_RESEND;
 
 /** Template keys for deterministic channel verification reply messages. */
 type ChannelVerifyReplyTemplateKey =
@@ -115,6 +121,14 @@ const templates: Record<
   [GUARDIAN_VERIFY_TEMPLATE_KEYS.SLACK_TRUSTED_CONTACT_RESEND]: (vars) => {
     return `Vellum assistant verification: your code is ${vars.code}. Reply with this code to verify your identity. It expires in ${vars.expiresInMinutes} minutes. (resent)`;
   },
+
+  [GUARDIAN_VERIFY_TEMPLATE_KEYS.EMAIL_CHALLENGE_REQUEST]: (vars) => {
+    return `Vellum assistant guardian verification requested.\n\nYour verification code is: ${vars.code}\n\nReply to this email with only the 6-digit code above to complete verification. This code expires in ${vars.expiresInMinutes} minutes.`;
+  },
+
+  [GUARDIAN_VERIFY_TEMPLATE_KEYS.EMAIL_RESEND]: (vars) => {
+    return `Vellum assistant guardian verification requested.\n\nYour new verification code is: ${vars.code}\n\nReply to this email with only the 6-digit code above to complete verification. This code expires in ${vars.expiresInMinutes} minutes. (resent)`;
+  },
 };
 
 /**
@@ -129,6 +143,18 @@ export function composeVerificationSlack(
   return composer(vars);
 }
 
+/**
+ * Compose an outbound verification email from a template key and typed variables.
+ * Returns plain string content suitable for email delivery.
+ */
+export function composeVerificationEmail(
+  templateKey: TextVerifyTemplateKey,
+  vars: GuardianVerifyTemplateVars,
+): string {
+  const composer = templates[templateKey];
+  return composer(vars);
+}
+
 /**
  * Compose an outbound verification Telegram message from a template key and typed variables.
  * Returns plain string content suitable for Telegram delivery.

package/src/schedule/schedule-store.ts

@@ -33,6 +33,7 @@ export type ScheduleStatus = "active" | "firing" | "fired" | "cancelled";
 export interface ScheduleJob {
   id: string;
   name: string;
+  description: string;
   enabled: boolean;
   syntax: ScheduleSyntax;
   expression: string | null;
@@ -85,6 +86,7 @@ export function isValidCronExpression(expr: string): boolean {
 
 export function createSchedule(params: {
   name: string;
+  description?: string;
   cronExpression?: string | null;
   timezone?: string | null;
   message: string;
@@ -141,6 +143,10 @@ export function createSchedule(params: {
   const retryBackoffMs = params.retryBackoffMs ?? 60000;
   const timeoutMs = params.timeoutMs ?? null;
   const createdFromConversationId = params.createdFromConversationId ?? null;
+  const description = normalizeDescription(
+    params.description,
+    params.createdBy === "defer" ? "" : params.name,
+  );
 
   let nextRunAt: number;
   if (isOneShot) {
@@ -154,6 +160,7 @@ export function createSchedule(params: {
   const row = {
     id,
     name: params.name,
+    description,
     enabled,
     cronExpression: expression,
     scheduleSyntax: syntax,
@@ -252,6 +259,7 @@ export function updateSchedule(
   id: string,
   updates: {
     name?: string;
+    description?: string;
     cronExpression?: string;
     timezone?: string | null;
     message?: string;
@@ -313,6 +321,8 @@ export function updateSchedule(
   const set: Record<string, unknown> = { updatedAt: now };
 
   if (updates.name !== undefined) set.name = updates.name;
+  if (updates.description !== undefined)
+    set.description = normalizeDescription(updates.description);
   if (updates.cronExpression !== undefined || updates.expression !== undefined)
     set.cronExpression = newExpr;
   if (updates.syntax !== undefined) set.scheduleSyntax = newSyntax;
@@ -980,6 +990,7 @@ function parseJobRow(row: typeof scheduleJobs.$inferSelect): ScheduleJob {
   return {
     id: row.id,
     name: row.name,
+    description: row.description ?? "",
     enabled: row.enabled,
     syntax: row.scheduleSyntax as ScheduleSyntax,
     expression: row.cronExpression,
@@ -1008,6 +1019,14 @@ function parseJobRow(row: typeof scheduleJobs.$inferSelect): ScheduleJob {
   };
 }
 
+function normalizeDescription(
+  value: string | undefined,
+  fallback = "",
+): string {
+  const normalized = value?.trim() ?? "";
+  return normalized || fallback;
+}
+
 function safeParseJson(
   json: string | null | undefined,
 ): Record<string, unknown> {

package/src/skills/catalog-install.ts

@@ -47,11 +47,6 @@ export interface CatalogSkill {
   };
 }
 
-export interface CatalogManifest {
-  version: number;
-  skills: CatalogSkill[];
-}
-
 /**
  * Resolve the directory containing a `catalog.json` and first-party skill
  * sources — either bundled next to a compiled binary (e.g. `Vellum.app`) or
@@ -97,6 +92,75 @@ export function getRepoSkillsDir(): string | undefined {
 
 // ─── Catalog operations ──────────────────────────────────────────────────────
 
+/**
+ * Raw skill entry as returned by the platform `/v1/skills/` API. The platform
+ * serializer flattens the skill's metadata into top-level fields
+ * (`category`, `display_name`, `icon`) rather than the nested
+ * `metadata.vellum.*` shape used by the local `catalog.json`. Both shapes are
+ * accepted here so the daemon has a single canonical representation downstream.
+ */
+interface RawCatalogEntry {
+  id?: unknown;
+  name?: unknown;
+  description?: unknown;
+  icon?: unknown;
+  emoji?: string;
+  includes?: string[];
+  version?: string;
+  updatedAt?: unknown;
+  display_name?: unknown;
+  category?: unknown;
+  updated_at?: unknown;
+  metadata?: CatalogSkill["metadata"];
+}
+
+function asStr(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/**
+ * Normalize a platform API entry into a canonical {@link CatalogSkill}.
+ *
+ * The platform flattens `category`, `display_name`, and `icon` to the top
+ * level, so re-nest them under `metadata.vellum` to match the local catalog
+ * shape that the rest of the daemon reads (`metadata.vellum.category`,
+ * `metadata.vellum["display-name"]`). Existing nested values take precedence
+ * so a future API change to the nested shape keeps working.
+ */
+function normalizeCatalogEntry(raw: unknown): CatalogSkill | null {
+  if (typeof raw !== "object" || raw === null) return null;
+  const entry = raw as RawCatalogEntry;
+
+  const id = asStr(entry.id);
+  if (!id) return null;
+
+  const nested = entry.metadata?.vellum;
+  const category = nested?.category ?? asStr(entry.category);
+  const displayName = nested?.["display-name"] ?? asStr(entry.display_name);
+  const icon = asStr(entry.icon) ?? asStr(entry.metadata?.icon);
+  const updatedAt = asStr(entry.updatedAt) ?? asStr(entry.updated_at);
+
+  return {
+    id,
+    name: asStr(entry.name) ?? id,
+    description: asStr(entry.description) ?? "",
+    ...(icon ? { icon } : {}),
+    ...(entry.emoji ? { emoji: entry.emoji } : {}),
+    ...(entry.includes ? { includes: entry.includes } : {}),
+    ...(entry.version ? { version: entry.version } : {}),
+    ...(updatedAt ? { updatedAt } : {}),
+    metadata: {
+      ...entry.metadata,
+      ...(icon ? { icon } : {}),
+      vellum: {
+        ...nested,
+        ...(displayName ? { "display-name": displayName } : {}),
+        ...(category ? { category } : {}),
+      },
+    },
+  };
+}
+
 export async function fetchCatalog(): Promise<CatalogSkill[]> {
   const platformUrl = getPlatformBaseUrl();
   const url = `${platformUrl}/v1/skills/`;
@@ -110,23 +174,23 @@ export async function fetchCatalog(): Promise<CatalogSkill[]> {
     );
   }
 
-  const manifest = (await response.json()) as CatalogManifest;
+  const manifest = (await response.json()) as { skills?: unknown };
   if (!Array.isArray(manifest.skills)) {
     throw new Error("Platform catalog has invalid skills array");
   }
-  return manifest.skills.filter(
-    (s): s is CatalogSkill => !!s && typeof s.id === "string",
-  );
+  return manifest.skills
+    .map((s) => normalizeCatalogEntry(s))
+    .filter((s): s is CatalogSkill => s !== null);
 }
 
 export function readLocalCatalog(repoSkillsDir: string): CatalogSkill[] {
   try {
     const raw = readFileSync(join(repoSkillsDir, "catalog.json"), "utf-8");
-    const manifest = JSON.parse(raw) as CatalogManifest;
+    const manifest = JSON.parse(raw) as { skills?: unknown };
     if (!Array.isArray(manifest.skills)) return [];
-    return manifest.skills.filter(
-      (s): s is CatalogSkill => !!s && typeof s.id === "string",
-    );
+    return manifest.skills
+      .map((s) => normalizeCatalogEntry(s))
+      .filter((s): s is CatalogSkill => s !== null);
   } catch {
     return [];
   }

package/src/tasks/task-scheduler.ts

@@ -13,6 +13,7 @@ export function scheduleTask(opts: {
 }): ReturnType<typeof createSchedule> {
   return createSchedule({
     name: opts.name,
+    description: `Run task: ${opts.name}`,
     cronExpression: opts.cronExpression,
     timezone: opts.timezone ?? null,
     message: `run_task:${opts.taskId}`,

package/src/telemetry/types.ts

@@ -34,6 +34,27 @@ export interface TelemetryEventBase {
   assistant_version: string | null;
 }
 
+/**
+ * Base for telemetry events that occur in the context of a model call.
+ * Standardizes model attribution across event types — field names/shapes
+ * mirror the existing llm_usage event so downstream consumers (dbt, admin
+ * charts) can join/group consistently.
+ *
+ * `provider`/`model` are nullable on the wire because rows persisted before
+ * the attribution columns existed, and rows whose attribution resolution
+ * failed, must still ship; the platform serializer accepts null.
+ */
+export interface ModelTelemetryEventBase extends TelemetryEventBase {
+  /** Provider serving the call, e.g. "anthropic", "fireworks". */
+  provider: string | null;
+  /** Model id active for the call, e.g. "claude-fable-5". */
+  model: string | null;
+  /** Inference profile slug. Null when no profile applied. */
+  inference_profile: string | null;
+  /** How the profile was attributed (same enum as llm_usage). */
+  inference_profile_source: UsageAttributionProfileSource | null;
+}
+
 /** LLM usage event — one per provider API call. */
 export interface LlmUsageTelemetryEvent extends TelemetryEventBase {
   type: "llm_usage";
@@ -225,10 +246,54 @@ export interface AuthFallbackTelemetryEvent extends TelemetryEventBase {
   window_end: number;
 }
 
+/**
+ * Tool-executed event — one per tool invocation. Carries NO tool
+ * args/inputs or result contents (customer PII per ToS) — payload sizes
+ * and metadata only; no raw error messages. Identity/attribution come
+ * from the upload envelope per the per-event-wins contract. Not to be
+ * confused with the since-reverted `tool_execution` permission-audit
+ * event, which no longer exists on the wire.
+ */
+export interface ToolExecutedTelemetryEvent extends ModelTelemetryEventBase {
+  type: "tool_executed";
+  tool_name: string;
+  /**
+   * `"errored"` means the invocation failed at the execution layer — a
+   * thrown error / infra failure (audit decision `"error"`). A tool that
+   * runs to completion but returns an `isError` result payload still
+   * counts as `"fulfilled"`: it executed.
+   */
+  status: "fulfilled" | "errored";
+  duration_ms: number;
+  /** Serialized tool-argument size in bytes. Null when unknown. */
+  arg_bytes: number | null;
+  /** Serialized tool-result size in bytes. Null when unknown. */
+  result_bytes: number | null;
+  conversation_id: string | null;
+}
+
+/**
+ * Skill-loaded event — one per skill load. Emitted only for
+ * Vellum-produced skills (bundled, or managed with vellum origin).
+ * Metadata only — no skill output or conversation content.
+ */
+export interface SkillLoadedTelemetryEvent extends ModelTelemetryEventBase {
+  type: "skill_loaded";
+  skill_name: string;
+  /**
+   * ISO 8601 timestamp — the catalog's `updatedAt`, effectively the
+   * skill version. Null when the catalog carries no timestamp.
+   */
+  skill_updated_at: string | null;
+  conversation_id: string | null;
+}
+
 /** Discriminated union of all telemetry event types. */
 export type TelemetryEvent =
   | LlmUsageTelemetryEvent
   | TurnTelemetryEvent
   | LifecycleTelemetryEvent
   | OnboardingTelemetryEvent
-  | AuthFallbackTelemetryEvent;
+  | AuthFallbackTelemetryEvent
+  | ToolExecutedTelemetryEvent
+  | SkillLoadedTelemetryEvent;