@vellumai/assistant 0.8.7 → 0.8.8

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

@@ -10,6 +10,8 @@
  *     with the platform for this assistant.
  */
 
+import { z } from "zod";
+
 import { getIsPlatform } from "../../config/env-registry.js";
 import { getConfig } from "../../config/loader.js";
 import {
@@ -25,6 +27,38 @@ import {
 } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+const WebhooksRegisterRequestSchema = z.object({
+  type: z.string(),
+  path: z.string().optional(),
+  source: z.string().optional(),
+});
+
+const WebhooksRegisterResponseSchema = z.object({
+  callbackUrl: z.string(),
+  type: z.string(),
+  path: z.string(),
+  mode: z.enum(["platform", "self-hosted"]),
+});
+type WebhooksRegisterResponse = z.infer<typeof WebhooksRegisterResponseSchema>;
+
+const WebhookCallbackRouteSchema = z.object({
+  id: z.string(),
+  assistant_id: z.string(),
+  type: z.string(),
+  callback_path: z.string(),
+  callback_url: z.string(),
+  source_identifier: z.string().nullable(),
+});
+
+const WebhooksListResponseSchema = z.object({
+  routes: z.array(WebhookCallbackRouteSchema),
+});
+type WebhooksListResponse = z.infer<typeof WebhooksListResponseSchema>;
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -49,7 +83,7 @@ function deriveWebhookPath(type: string): string {
 
 async function handleWebhooksRegister(
   args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<WebhooksRegisterResponse> {
   const { type, path: pathOverride, source } = args.body ?? {};
 
   if (!type || typeof type !== "string") {
@@ -93,7 +127,9 @@ async function handleWebhooksRegister(
   };
 }
 
-async function handleWebhooksList(_args: RouteHandlerArgs): Promise<unknown> {
+async function handleWebhooksList(
+  _args: RouteHandlerArgs,
+): Promise<WebhooksListResponse> {
   const context = await resolvePlatformCallbackRegistrationContext();
 
   if (!context.platformBaseUrl || !context.authHeader) {
@@ -155,6 +191,8 @@ export const ROUTES: RouteDefinition[] = [
     description:
       "Resolves a stable callback URL for a webhook type. On platform-managed assistants, registers the route with the platform gateway. On self-hosted assistants, uses the configured ingress.publicBaseUrl.",
     tags: ["webhooks"],
+    requestBody: WebhooksRegisterRequestSchema,
+    responseBody: WebhooksRegisterResponseSchema,
     handler: handleWebhooksRegister,
   },
   {
@@ -169,6 +207,7 @@ export const ROUTES: RouteDefinition[] = [
     description:
       "Lists all webhook callback routes registered with the platform for this assistant.",
     tags: ["webhooks"],
+    responseBody: WebhooksListResponseSchema,
     handler: handleWebhooksList,
   },
 ];

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

@@ -663,6 +663,10 @@ export const ROUTES: RouteDefinition[] = [
         description: "Allow hidden files (true/false)",
       },
     ],
+    responseBody: {
+      contentType: "application/octet-stream",
+      schema: { type: "string", format: "binary" },
+    },
     responseStatus: ({ headers }) => (headers?.["range"] ? "206" : "200"),
     additionalResponses: {
       "416": { description: "Range Not Satisfiable" },

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

@@ -61,6 +61,12 @@ function makeConversation() {
     setSubagentAllowedTools: mock(() => {}),
     updateClient: mock(() => {}),
     processing: false,
+    isProcessing(this: { processing: boolean }) {
+      return this.processing;
+    },
+    setProcessing(this: { processing: boolean }, value: boolean) {
+      this.processing = value;
+    },
     abortController: null as AbortController | null,
     currentRequestId: null as string | null,
     loadedHistoryTrustClass: undefined as string | undefined,

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

@@ -198,7 +198,7 @@ export async function analyzeConversation(
   // `currentRequestId` and let two loops mutate the same Conversation
   // state. Skip this run instead — the next upstream trigger will
   // re-enqueue once the in-flight loop finishes.
-  if (opts.trigger === "auto" && analysisConversation.processing) {
+  if (opts.trigger === "auto" && analysisConversation.isProcessing()) {
     log.info(
       {
         sourceConversationId: resolvedId,
@@ -247,7 +247,7 @@ export async function analyzeConversation(
   analysisConversation.updateClient(broadcastMessage, !hasLiveSubscriber);
 
   // k. Set up processing state (required by runAgentLoop guard)
-  analysisConversation.processing = true;
+  analysisConversation.setProcessing(true);
   analysisConversation.abortController = new AbortController();
   analysisConversation.currentRequestId = crypto.randomUUID();
 

package/src/schedule/schedule-store.ts

@@ -49,6 +49,7 @@ export interface ScheduleJob {
   retryBackoffMs: number;
   /** Script-mode execution timeout override (ms); null = use the default. */
   timeoutMs: number | null;
+  createdFromConversationId: string | null;
   createdBy: string;
   mode: ScheduleMode;
   routingIntent: RoutingIntent;
@@ -102,6 +103,7 @@ export function createSchedule(params: {
   maxRetries?: number;
   retryBackoffMs?: number;
   timeoutMs?: number | null;
+  createdFromConversationId?: string | null;
 }): ScheduleJob {
   const expression = params.expression ?? params.cronExpression ?? null;
   const isOneShot = expression == null;
@@ -138,6 +140,7 @@ export function createSchedule(params: {
   const maxRetries = params.maxRetries ?? 3;
   const retryBackoffMs = params.retryBackoffMs ?? 60000;
   const timeoutMs = params.timeoutMs ?? null;
+  const createdFromConversationId = params.createdFromConversationId ?? null;
 
   let nextRunAt: number;
   if (isOneShot) {
@@ -165,6 +168,7 @@ export function createSchedule(params: {
     maxRetries,
     retryBackoffMs,
     timeoutMs,
+    createdFromConversationId,
     createdBy: params.createdBy ?? "agent",
     mode,
     routingIntent,
@@ -264,6 +268,7 @@ export function updateSchedule(
     maxRetries?: number;
     retryBackoffMs?: number;
     timeoutMs?: number | null;
+    createdFromConversationId?: string | null;
   },
 ): ScheduleJob | null {
   const db = getDb();
@@ -329,6 +334,8 @@ export function updateSchedule(
   if (updates.retryBackoffMs !== undefined)
     set.retryBackoffMs = updates.retryBackoffMs;
   if (updates.timeoutMs !== undefined) set.timeoutMs = updates.timeoutMs;
+  if (updates.createdFromConversationId !== undefined)
+    set.createdFromConversationId = updates.createdFromConversationId;
 
   // Recompute nextRunAt if schedule timing may have changed (only for recurring)
   if (
@@ -591,7 +598,7 @@ export function cancelSchedule(id: string): boolean {
 
 export function createScheduleRun(
   jobId: string,
-  conversationId: string,
+  conversationId: string | null,
 ): string {
   const db = getDb();
   const id = uuid();
@@ -613,6 +620,17 @@ export function createScheduleRun(
   return id;
 }
 
+export function setScheduleRunConversationId(
+  runId: string,
+  conversationId: string,
+): void {
+  const db = getDb();
+  db.update(scheduleRuns)
+    .set({ conversationId })
+    .where(eq(scheduleRuns.id, runId))
+    .run();
+}
+
 export function completeScheduleRun(
   runId: string,
   result: { status: "ok" | "error"; output?: string; error?: string },
@@ -977,6 +995,7 @@ function parseJobRow(row: typeof scheduleJobs.$inferSelect): ScheduleJob {
     maxRetries: row.maxRetries ?? 3,
     retryBackoffMs: row.retryBackoffMs ?? 60000,
     timeoutMs: row.timeoutMs ?? null,
+    createdFromConversationId: row.createdFromConversationId ?? null,
     createdBy: row.createdBy,
     mode: (row.mode ?? "execute") as ScheduleMode,
     routingIntent: (row.routingIntent ?? "all_channels") as RoutingIntent,

package/src/schedule/schedule-usage-store.ts

@@ -0,0 +1,83 @@
+import { rawAll } from "../memory/raw-query.js";
+import { buildScheduleAttributionSubquery } from "../memory/schedule-attribution-sql.js";
+
+export interface ScheduleUsageSummary {
+  scheduleId: string;
+  runCount: number;
+  totalEstimatedCostUsd: number;
+  eventCount: number;
+}
+
+interface ScheduleUsageSummaryRow {
+  schedule_id: string;
+  run_count: number;
+  total_estimated_cost_usd: number | null;
+  event_count: number | null;
+}
+
+export function getScheduleUsageSummaries({
+  from,
+  to,
+}: {
+  from: number;
+  to: number;
+}): ScheduleUsageSummary[] {
+  const now = Date.now();
+  const scheduleAttribution = buildScheduleAttributionSubquery({
+    eventAlias: "e",
+    now,
+    selectExpression: "schedule_attr_runs.job_id",
+  });
+  const rows = rawAll<ScheduleUsageSummaryRow>(
+    /*sql*/ `
+    WITH run_counts AS (
+      SELECT
+        job_id AS schedule_id,
+        COUNT(*) AS run_count
+      FROM cron_runs
+      WHERE started_at >= ?
+        AND started_at <= ?
+      GROUP BY job_id
+    ),
+    attributed_usage AS (
+      SELECT
+        e.estimated_cost_usd,
+        COALESCE(e.llm_call_count, 1) AS event_count,
+        ${scheduleAttribution.sql} AS schedule_id
+      FROM llm_usage_events e
+      WHERE e.created_at >= ?
+        AND e.created_at <= ?
+    ),
+    usage_totals AS (
+      SELECT
+        schedule_id,
+        COALESCE(SUM(estimated_cost_usd), 0) AS total_estimated_cost_usd,
+        COALESCE(SUM(event_count), 0) AS event_count
+      FROM attributed_usage
+      WHERE schedule_id IS NOT NULL
+      GROUP BY schedule_id
+    )
+    SELECT
+      cron_jobs.id AS schedule_id,
+      COALESCE(run_counts.run_count, 0) AS run_count,
+      COALESCE(usage_totals.total_estimated_cost_usd, 0) AS total_estimated_cost_usd,
+      COALESCE(usage_totals.event_count, 0) AS event_count
+    FROM cron_jobs
+    LEFT JOIN run_counts ON run_counts.schedule_id = cron_jobs.id
+    LEFT JOIN usage_totals ON usage_totals.schedule_id = cron_jobs.id
+    ORDER BY cron_jobs.created_at ASC, cron_jobs.id ASC
+    `,
+    from,
+    to,
+    ...scheduleAttribution.params,
+    from,
+    to,
+  );
+
+  return rows.map((row) => ({
+    scheduleId: row.schedule_id,
+    runCount: row.run_count,
+    totalEstimatedCostUsd: row.total_estimated_cost_usd ?? 0,
+    eventCount: row.event_count ?? 0,
+  }));
+}

package/src/schedule/scheduler.ts

@@ -28,6 +28,7 @@ import {
   type RoutingIntent,
   type ScheduleJob,
   scheduleRetry,
+  setScheduleRunConversationId,
 } from "./schedule-store.js";
 
 const log = getLogger("scheduler");
@@ -442,6 +443,7 @@ export async function runScheduleDueWorkOnce(
         job.syntax === "rrule" &&
         job.expression != null &&
         hasSetConstructs(job.expression);
+      const runId = createScheduleRun(job.id, null);
       let failed = false;
       try {
         log.info(
@@ -472,14 +474,13 @@ export async function runScheduleDueWorkOnce(
           },
         );
 
+        setScheduleRunConversationId(runId, result.conversationId);
         onScheduleConversationCreated?.({
           conversationId: result.conversationId,
           scheduleJobId: job.id,
           title: result.status === "failed" ? `${job.name}: Error` : job.name,
         });
 
-        // Track the schedule run using the task's conversation
-        const runId = createScheduleRun(job.id, result.conversationId);
         if (result.status === "failed") {
           const errorMessage = result.error ?? "Task run failed";
           completeScheduleRun(runId, {
@@ -530,7 +531,7 @@ export async function runScheduleDueWorkOnce(
           scheduleJobId: job.id,
           title: `${job.name}: Error`,
         });
-        const runId = createScheduleRun(job.id, fallbackConversation.id);
+        setScheduleRunConversationId(runId, fallbackConversation.id);
         completeScheduleRun(runId, { status: "error", error: message });
         emitTaskActivityFailed({
           taskId,
@@ -584,6 +585,8 @@ export async function runScheduleDueWorkOnce(
     let ok: boolean;
     let errorMsg: string | undefined;
     const conversationReused = reusedConversationId != null;
+    let runConversationId = reusedConversationId;
+    const runId = createScheduleRun(job.id, reusedConversationId);
 
     if (reusedConversationId) {
       // Reuse path: keep using the injected `processMessage` callback so the
@@ -625,6 +628,8 @@ export async function runScheduleDueWorkOnce(
         scheduleJobId: job.id,
         suppressFailureNotifications: job.quiet === true,
         onConversationCreated: (newConversationId) => {
+          runConversationId = newConversationId;
+          setScheduleRunConversationId(runId, newConversationId);
           onScheduleConversationCreated?.({
             conversationId: newConversationId,
             scheduleJobId: job.id,
@@ -641,12 +646,14 @@ export async function runScheduleDueWorkOnce(
         !result.ok && result.conversationId === ""
           ? `bootstrap-error:${job.id}`
           : result.conversationId;
+      if (runConversationId !== conversationId) {
+        runConversationId = conversationId;
+        setScheduleRunConversationId(runId, conversationId);
+      }
       ok = result.ok;
       errorMsg = result.error?.message;
     }
 
-    const runId = createScheduleRun(job.id, conversationId);
-
     if (ok) {
       completeScheduleRun(runId, { status: "ok" });
       if (isOneShot) completeOneShot(job.id);

package/src/skills/catalog-files.ts

@@ -37,7 +37,6 @@ import {
 import { getLogger } from "../util/logger.js";
 import { getCachedCatalogSync, getCatalog } from "./catalog-cache.js";
 import { type CatalogSkill, getRepoSkillsDir } from "./catalog-install.js";
-import { inferCategory } from "./category-inference.js";
 import type { SkillFileProvider } from "./skill-file-provider.js";
 
 const log = getLogger("catalog-files");
@@ -503,11 +502,12 @@ export function catalogSkillToSlim(cs: CatalogSkill): SlimSkillResponse {
     id: cs.id,
     name,
     description: cs.description,
+    icon: cs.icon ?? cs.metadata?.icon,
     emoji: cs.emoji ?? cs.metadata?.emoji,
     kind: "catalog",
     origin: "vellum",
     status: "available",
-    category: inferCategory(name, cs.description),
+    category: cs.metadata?.vellum?.category ?? "system",
   };
 }
 

package/src/skills/catalog-install.ts

@@ -29,17 +29,20 @@ export interface CatalogSkill {
   id: string;
   name: string;
   description: string;
+  icon?: string;
   emoji?: string;
   includes?: string[];
   version?: string;
   updatedAt?: string;
   metadata?: {
+    icon?: string;
     emoji?: string;
     vellum?: {
       "display-name"?: string;
       "activation-hints"?: string[];
       "avoid-when"?: string[];
       "feature-flag"?: string;
+      category?: string;
     };
   };
 }

package/src/skills/categories-cache.ts

@@ -0,0 +1,118 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { parse as parseYaml } from "yaml";
+
+import { getPlatformBaseUrl } from "../config/env.js";
+import { getLogger } from "../util/logger.js";
+import { getRepoSkillsDir } from "./catalog-install.js";
+
+const log = getLogger("categories-cache");
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+export interface SkillCategoryDef {
+  slug: string;
+  label: string;
+  description: string;
+  icon: string;
+}
+
+let cachedCategories: SkillCategoryDef[] | null = null;
+let cacheTimestamp = 0;
+
+async function fetchCategories(): Promise<SkillCategoryDef[]> {
+  const platformUrl = getPlatformBaseUrl();
+  const url = `${platformUrl}/v1/skills/categories/`;
+  const response = await fetch(url, {
+    signal: AbortSignal.timeout(10000),
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Platform API error ${response.status}: ${response.statusText}`,
+    );
+  }
+
+  const data = (await response.json()) as {
+    categories: SkillCategoryDef[];
+  };
+  if (!Array.isArray(data.categories)) {
+    throw new Error("Platform categories response has invalid categories array");
+  }
+  return data.categories.filter(
+    (c): c is SkillCategoryDef =>
+      !!c && typeof c.slug === "string" && typeof c.label === "string",
+  );
+}
+
+function readLocalCategories(repoSkillsDir: string): SkillCategoryDef[] {
+  try {
+    const raw = readFileSync(
+      join(repoSkillsDir, "skill-categories-catalog.yaml"),
+      "utf-8",
+    );
+    const parsed = parseYaml(raw) as { categories?: SkillCategoryDef[] };
+    if (!Array.isArray(parsed?.categories)) return [];
+    return parsed.categories.filter(
+      (c): c is SkillCategoryDef =>
+        !!c && typeof c.slug === "string" && typeof c.label === "string",
+    );
+  } catch {
+    return [];
+  }
+}
+
+export async function getCategories(): Promise<SkillCategoryDef[]> {
+  if (cachedCategories && Date.now() - cacheTimestamp < CACHE_TTL_MS) {
+    return cachedCategories;
+  }
+
+  const repoSkillsDir = getRepoSkillsDir();
+  const local = repoSkillsDir ? readLocalCategories(repoSkillsDir) : [];
+  let categories: SkillCategoryDef[];
+
+  try {
+    const remote = await fetchCategories();
+    if (local.length > 0) {
+      const localSlugs = new Set(local.map((c) => c.slug));
+      categories = [
+        ...local,
+        ...remote.filter((c) => !localSlugs.has(c.slug)),
+      ];
+    } else {
+      categories = remote;
+    }
+  } catch (err) {
+    if (cachedCategories) {
+      log.warn(
+        { err },
+        "Failed to fetch skill categories, keeping stale cache",
+      );
+      cacheTimestamp = Date.now();
+      return cachedCategories;
+    }
+    if (local.length > 0) {
+      log.warn(
+        { err },
+        "Failed to fetch skill categories, falling back to bundled local catalog",
+      );
+      categories = local;
+    } else {
+      log.warn({ err }, "Failed to fetch skill categories, returning empty");
+      return [];
+    }
+  }
+
+  cachedCategories = categories;
+  cacheTimestamp = Date.now();
+  return categories;
+}
+
+export function getCachedCategoriesSync(): SkillCategoryDef[] {
+  return cachedCategories ?? [];
+}
+
+export function invalidateCategoriesCache(): void {
+  cachedCategories = null;
+  cacheTimestamp = 0;
+}

package/src/skills/clawhub-files.ts

@@ -17,7 +17,6 @@ import type { SlimSkillResponse } from "../daemon/message-types/skills.js";
 import { isTextMimeType as isTextMime } from "../runtime/routes/workspace-utils.js";
 import { getLogger } from "../util/logger.js";
 import type { SkillFileEntry } from "./catalog-files.js";
-import { inferCategory } from "./category-inference.js";
 import {
   clawhubInspect,
   clawhubInspectFile,
@@ -199,7 +198,7 @@ export function createClawhubProvider(): SkillFileProvider {
         kind: "catalog",
         status: "available",
         origin: "clawhub",
-        category: inferCategory(data.skill.displayName, data.skill.summary),
+        category: "integrations",
         slug: data.skill.slug,
         author: data.owner?.handle ?? "",
         stars: data.stats?.stars ?? 0,

package/src/skills/skillssh-files.ts

@@ -24,7 +24,6 @@ import {
   sanitizeRelativePath,
   SKIP_DIRS,
 } from "./catalog-files.js";
-import { inferCategory } from "./category-inference.js";
 import type { SkillFileProvider } from "./skill-file-provider.js";
 import type { GitHubContentsEntry } from "./skillssh-registry.js";
 import {
@@ -384,7 +383,7 @@ export function createSkillsShProvider(): SkillFileProvider {
           kind: "catalog",
           status: "available",
           origin: "skillssh",
-          category: inferCategory(source.skillSlug, ""),
+          category: "integrations",
           slug: skillId,
           sourceRepo: `${source.owner}/${source.repo}`,
           installs: 0,

package/src/telemetry/types.ts

@@ -185,9 +185,37 @@ export interface OnboardingTelemetryEvent extends TelemetryEventBase {
   ab_variant?: string;
 }
 
+/**
+ * Auth-fallback event — aggregated count of requests served via the legacy
+ * loopback auth fallback. One event per (guard, path, failure_kind) per flush
+ * window. Lets the platform see which deployments still rely on the loopback
+ * exemption instead of sending a bearer token.
+ */
+export interface AuthFallbackTelemetryEvent extends TelemetryEventBase {
+  type: "auth_fallback";
+  /** Which auth guard fell back: `"edge"` | `"edge-scoped"` | `"edge-guardian"`. */
+  guard: string;
+  /** Request pathname that fell back. */
+  path: string;
+  /**
+   * Why the bearer-token check did not succeed before the fallback:
+   * `"missing_authorization"` | `"malformed_authorization"` |
+   * `"token_validation_failed"` | `"insufficient_scope"` |
+   * `"non_actor_principal"` | `"guardian_mismatch"`.
+   */
+  failure_kind: string;
+  /** Number of requests that fell back for this key during the window. */
+  count: number;
+  /** Window start (epoch ms) the count was accumulated over. */
+  window_start: number;
+  /** Window end (epoch ms) the count was accumulated over. */
+  window_end: number;
+}
+
 /** Discriminated union of all telemetry event types. */
 export type TelemetryEvent =
   | LlmUsageTelemetryEvent
   | TurnTelemetryEvent
   | LifecycleTelemetryEvent
-  | OnboardingTelemetryEvent;
+  | OnboardingTelemetryEvent
+  | AuthFallbackTelemetryEvent;