@vellumai/assistant 0.8.0 → 0.8.2

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

@@ -51,6 +51,7 @@ import { getLogger } from "../../util/logger.js";
 import { getAvatarImagePath, getWorkspaceDir } from "../../util/platform.js";
 import { buildAssistantEvent } from "../assistant-event.js";
 import { assistantEventHub } from "../assistant-event-hub.js";
+import { publishAvatarChanged } from "../sync/resource-sync-events.js";
 import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 import { resolveWorkspacePath } from "./workspace-utils.js";
@@ -94,16 +95,7 @@ async function handleGenerateAvatar({ body = {} }: RouteHandlerArgs) {
 
     const avatarPath = getAvatarImagePath();
 
-    assistantEventHub
-      .publish(
-        buildAssistantEvent({
-          type: "avatar_updated",
-          avatarPath,
-        }),
-      )
-      .catch((err) => {
-        log.warn({ err }, "Failed to publish avatar_updated event");
-      });
+    publishAvatarChanged();
 
     return { ok: true, avatarPath };
   } catch (err) {

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

@@ -17,6 +17,7 @@ import {
   getSkill,
   getSkillFileContent,
   getSkillFiles,
+  getSkillLocalDetail,
   inspectSkill,
   installSkill,
   listSkills,
@@ -360,6 +361,11 @@ export const ROUTES: RouteDefinition[] = [
         schema: { type: "string" },
         description: "Search query (required)",
       },
+      {
+        name: "limit",
+        schema: { type: "string" },
+        description: "Max community results to fetch (default 25)",
+      },
     ],
     responseBody: z.object({
       skills: z
@@ -369,7 +375,9 @@ export const ROUTES: RouteDefinition[] = [
     handler: async ({ queryParams = {} }: RouteHandlerArgs) => {
       const query = queryParams.q ?? "";
       if (!query) throw new BadRequestError("q query parameter is required");
-      const result = await searchSkills(query);
+      const limitRaw = queryParams.limit;
+      const limit = limitRaw ? Math.max(1, Number.parseInt(limitRaw, 10) || 25) : 25;
+      const result = await searchSkills(query, limit);
       if (!result.success) throw new InternalError(result.error);
       return { skills: result.skills };
     },
@@ -498,6 +506,8 @@ export const ROUTES: RouteDefinition[] = [
         .describe(
           "Which registry to install from. When omitted, the install flow auto-detects based on slug format.",
         ),
+      overwrite: z.boolean().optional().describe("Replace an existing install. Defaults to true for back-compat with the legacy in-process API."),
+      catalogOnly: z.boolean().optional().describe("When true, restrict to bundled and Vellum catalog skills only — do not fall through to community registries."),
     }),
     responseBody: z.object({
       ok: z.boolean(),
@@ -516,6 +526,8 @@ export const ROUTES: RouteDefinition[] = [
           slug,
           version: body.version as string | undefined,
           origin: body.origin as "clawhub" | "skillssh" | undefined,
+          catalogOnly: body.catalogOnly as boolean | undefined,
+          overwrite: body.overwrite as boolean | undefined,
         },
       );
       if (!result.success) throw new InternalError(result.error);
@@ -556,4 +568,22 @@ export const ROUTES: RouteDefinition[] = [
       return { ok: true };
     },
   },
+  {
+    operationId: "skillsLocalInspect",
+    endpoint: "skills/:id/local-inspect",
+    method: "GET",
+    policyKey: "skills",
+    requirePolicyEnforcement: true,
+    summary: "Local skill inspect",
+    description: "Return full local detail for an installed or bundled skill, including featureFlag, toolManifest, installMeta, configEntry, and directoryPath.",
+    tags: ["skills"],
+    handler: ({ pathParams }: RouteHandlerArgs) => {
+      const result = getSkillLocalDetail(pathParams!.id);
+      if (!result.ok) {
+        if (result.status === 404) throw new NotFoundError(result.error);
+        throw new InternalError(result.error);
+      }
+      return result;
+    },
+  },
 ];

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

@@ -1,17 +1,28 @@
 /**
  * Transport-agnostic route definitions for speech-to-text.
  *
- * GET  /v1/stt/providers  — list available STT providers and their metadata
- * POST /v1/stt/transcribe — transcribe base64-encoded audio to text
+ * GET  /v1/stt/providers        — list available STT providers and their metadata
+ * POST /v1/stt/transcribe       — transcribe base64-encoded audio to text
+ * POST /v1/stt/transcribe-file  — transcribe audio/video file to text (full ffmpeg + chunking flow)
  */
 
+import { randomUUID } from "node:crypto";
+import { access, mkdir, readdir, readFile, rm, unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { extname, join } from "node:path";
+
 import { z } from "zod";
 
 import { listProviderEntries } from "../../providers/speech-to-text/provider-catalog.js";
 import { resolveBatchTranscriber } from "../../providers/speech-to-text/resolve.js";
 import { normalizeSttError } from "../../stt/daemon-batch-transcriber.js";
-import type { SttErrorCategory } from "../../stt/types.js";
+import type { BatchTranscriber, SttErrorCategory } from "../../stt/types.js";
 import { getLogger } from "../../util/logger.js";
+import {
+  FFMPEG_TRANSCODE_TIMEOUT_MS,
+  FFPROBE_TIMEOUT_MS,
+  spawnWithTimeout,
+} from "../../util/spawn.js";
 import {
   BadGatewayError,
   BadRequestError,
@@ -28,6 +39,155 @@ const log = getLogger("stt-routes");
 /** Timeout for a single transcription request. */
 const TRANSCRIPTION_TIMEOUT_MS = 30_000;
 
+// ---------------------------------------------------------------------------
+// File-transcription constants and helpers (used by stt_transcribe_file)
+// ---------------------------------------------------------------------------
+
+const VIDEO_EXTENSIONS = new Set([
+  ".mp4",
+  ".mov",
+  ".avi",
+  ".mkv",
+  ".webm",
+  ".m4v",
+  ".mpeg",
+  ".mpg",
+]);
+const AUDIO_EXTENSIONS = new Set([
+  ".mp3",
+  ".wav",
+  ".m4a",
+  ".aac",
+  ".ogg",
+  ".flac",
+  ".aiff",
+  ".wma",
+]);
+
+/** Max file size for a single STT chunk request (25MB). */
+const STT_CHUNK_MAX_BYTES = 25 * 1024 * 1024;
+
+/** Duration per chunk when splitting for large files (10 minutes). */
+const CHUNK_DURATION_SECS = 600;
+
+/** Timeout for a single STT transcription request. */
+const STT_REQUEST_TIMEOUT_MS = 300_000;
+
+async function getAudioDuration(audioPath: string): Promise<number> {
+  const result = await spawnWithTimeout(
+    [
+      "ffprobe",
+      "-v",
+      "error",
+      "-show_entries",
+      "format=duration",
+      "-of",
+      "csv=p=0",
+      audioPath,
+    ],
+    FFPROBE_TIMEOUT_MS,
+  );
+  if (result.exitCode !== 0) return 0;
+  return parseFloat(result.stdout.trim()) || 0;
+}
+
+async function splitAudio(
+  audioPath: string,
+  chunkDir: string,
+  chunkDurationSecs: number,
+): Promise<string[]> {
+  const chunkPattern = join(chunkDir, "chunk-%03d.wav");
+  const result = await spawnWithTimeout(
+    [
+      "ffmpeg",
+      "-y",
+      "-i",
+      audioPath,
+      "-f",
+      "segment",
+      "-segment_time",
+      String(chunkDurationSecs),
+      "-acodec",
+      "pcm_s16le",
+      "-ar",
+      "16000",
+      "-ac",
+      "1",
+      chunkPattern,
+    ],
+    FFMPEG_TRANSCODE_TIMEOUT_MS,
+  );
+  if (result.exitCode !== 0) {
+    throw new Error(`Failed to split audio: ${result.stderr.slice(0, 300)}`);
+  }
+  const files = await readdir(chunkDir);
+  return files
+    .filter((f) => f.startsWith("chunk-") && f.endsWith(".wav"))
+    .sort()
+    .map((f) => join(chunkDir, f));
+}
+
+/** Convert source to 16kHz mono WAV for consistent processing. */
+async function toWav(inputPath: string, isVideo: boolean): Promise<string> {
+  const wavPath = join(tmpdir(), `vellum-transcribe-${randomUUID()}.wav`);
+  const args = ["ffmpeg", "-y", "-i", inputPath];
+  if (isVideo) args.push("-vn");
+  args.push("-acodec", "pcm_s16le", "-ar", "16000", "-ac", "1", wavPath);
+  const result = await spawnWithTimeout(args, FFMPEG_TRANSCODE_TIMEOUT_MS);
+  if (result.exitCode !== 0) {
+    throw new Error(`ffmpeg failed: ${result.stderr.slice(0, 500)}`);
+  }
+  return wavPath;
+}
+
+async function transcribeWithProvider(
+  audioPath: string,
+  transcriber: BatchTranscriber,
+): Promise<string> {
+  const duration = await getAudioDuration(audioPath);
+  const fileSize = Bun.file(audioPath).size;
+
+  // If small enough, send directly
+  if (fileSize <= STT_CHUNK_MAX_BYTES) {
+    const audioBuffer = await readFile(audioPath);
+    const result = await transcriber.transcribe({
+      audio: audioBuffer,
+      mimeType: "audio/wav",
+      signal: AbortSignal.timeout(STT_REQUEST_TIMEOUT_MS),
+    });
+    return result.text;
+  }
+
+  // Split into chunks for large files
+  const chunkDir = join(tmpdir(), `vellum-transcribe-chunks-${randomUUID()}`);
+  await mkdir(chunkDir, { recursive: true });
+
+  try {
+    process.stderr.write(
+      `Large file (${Math.round(duration / 60)}min) - splitting into chunks...\n`,
+    );
+    const chunks = await splitAudio(audioPath, chunkDir, CHUNK_DURATION_SECS);
+    const parts: string[] = [];
+
+    for (let i = 0; i < chunks.length; i++) {
+      process.stderr.write(
+        `  Transcribing chunk ${i + 1}/${chunks.length}...\n`,
+      );
+      const audioBuffer = await readFile(chunks[i]);
+      const result = await transcriber.transcribe({
+        audio: audioBuffer,
+        mimeType: "audio/wav",
+        signal: AbortSignal.timeout(STT_REQUEST_TIMEOUT_MS),
+      });
+      if (result.text) parts.push(result.text);
+    }
+
+    return parts.join(" ");
+  } finally {
+    await rm(chunkDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Error category → RouteError mapping
 // ---------------------------------------------------------------------------
@@ -156,6 +316,63 @@ async function handleTranscribe({ body }: RouteHandlerArgs) {
   }
 }
 
+async function handleTranscribeFile({ body }: RouteHandlerArgs) {
+  const filePath = body?.filePath;
+  if (typeof filePath !== "string" || !filePath) {
+    throw new BadRequestError("filePath is required");
+  }
+
+  try {
+    await access(filePath);
+  } catch {
+    throw new BadRequestError(`File not found: ${filePath}`);
+  }
+
+  const ext = extname(filePath).toLowerCase();
+  const isVideo = VIDEO_EXTENSIONS.has(ext);
+  const isAudio = AUDIO_EXTENSIONS.has(ext);
+  if (!isVideo && !isAudio) {
+    throw new BadRequestError(
+      `Unsupported file type: ${ext}. Only audio and video files can be transcribed.`,
+    );
+  }
+
+  let transcriber;
+  try {
+    transcriber = await resolveBatchTranscriber();
+  } catch (err) {
+    log.error({ err }, "Failed to resolve STT transcriber");
+    throw new ServiceUnavailableError("STT provider is not available");
+  }
+  if (!transcriber) {
+    throw new ServiceUnavailableError(
+      "No speech-to-text provider is configured",
+    );
+  }
+
+  const startTime = Date.now();
+  let wavPath: string | null = null;
+  try {
+    wavPath = await toWav(filePath, isVideo);
+    const text = await transcribeWithProvider(wavPath, transcriber);
+    const durationSeconds = (Date.now() - startTime) / 1000;
+    return {
+      transcript: text,
+      provider: transcriber.providerId,
+      durationSeconds,
+    };
+  } catch (err) {
+    log.error({ err, filePath }, "File transcription failed");
+    throw new BadGatewayError(
+      err instanceof Error ? err.message : "Transcription failed",
+    );
+  } finally {
+    if (wavPath) {
+      await unlink(wavPath).catch(() => {});
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Route definitions
 // ---------------------------------------------------------------------------
@@ -220,4 +437,24 @@ export const ROUTES: RouteDefinition[] = [
     }),
     handler: handleTranscribe,
   },
+  {
+    operationId: "stt_transcribe_file",
+    endpoint: "stt/transcribe-file",
+    method: "POST",
+    policyKey: "stt/transcribe-file",
+    requirePolicyEnforcement: true,
+    summary: "Transcribe audio/video file to text",
+    description:
+      "Transcribe an audio or video file to text using the configured STT provider. Handles ffmpeg conversion, large-file chunking, and sequential chunk transcription.",
+    tags: ["stt"],
+    requestBody: z.object({
+      filePath: z.string().describe("Absolute path to the audio or video file"),
+    }),
+    responseBody: z.object({
+      transcript: z.string(),
+      provider: z.string(),
+      durationSeconds: z.number(),
+    }),
+    handler: handleTranscribeFile,
+  },
 ];

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

@@ -11,6 +11,7 @@ import {
   getMessages,
   type MessageRow,
 } from "../../memory/conversation-crud.js";
+import { getConversationUsageTotals } from "../../memory/llm-usage-store.js";
 import { getSubagentManager } from "../../subagent/index.js";
 import { getLogger } from "../../util/logger.js";
 import { BadRequestError, NotFoundError } from "./errors.js";
@@ -29,6 +30,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 export interface SubagentDetailResult {
   subagentId: string;
   objective?: string;
+  usage?: { inputTokens: number; outputTokens: number; estimatedCost: number };
   events: Array<{
     type: string;
     content: string;
@@ -94,7 +96,11 @@ export function parseSubagentMessages(
         typeof block.text === "string"
       ) {
         events.push({ type: "text", content: block.text, messageId: m.id });
-      } else if (block.type === "tool_use") {
+      } else if (
+        block.type === "tool_use" ||
+        block.type === "server_tool_use" ||
+        block.type === "mcp_tool_use"
+      ) {
         const name = typeof block.name === "string" ? block.name : "unknown";
         const input = isRecord(block.input)
           ? (block.input as Record<string, unknown>)
@@ -106,7 +112,11 @@ export function parseSubagentMessages(
           toolName: name,
         });
         if (id) pendingTools.set(id, name);
-      } else if (block.type === "tool_result") {
+      } else if (
+        block.type === "tool_result" ||
+        block.type === "web_search_tool_result" ||
+        block.type === "mcp_tool_result"
+      ) {
         const toolUseId =
           typeof block.tool_use_id === "string" ? block.tool_use_id : "";
         const resultContent =
@@ -114,13 +124,18 @@ export function parseSubagentMessages(
             ? block.content
             : Array.isArray(block.content)
               ? (block.content as unknown[])
-                  .filter(
-                    (b): b is Record<string, unknown> =>
-                      isRecord(b) &&
-                      (b as Record<string, unknown>).type === "text" &&
-                      typeof (b as Record<string, unknown>).text === "string",
-                  )
-                  .map((b) => b.text as string)
+                  .filter((b): b is Record<string, unknown> => isRecord(b))
+                  .map((b) => {
+                    if (b.type === "text" && typeof b.text === "string")
+                      return b.text;
+                    if (
+                      b.type === "web_search_result" &&
+                      typeof b.title === "string"
+                    )
+                      return `${b.title}\n${typeof b.url === "string" ? b.url : ""}`;
+                    return null;
+                  })
+                  .filter((s): s is string => s != null)
                   .join("\n")
               : "";
         const isError = block.is_error === true;
@@ -142,7 +157,30 @@ function getSubagentDetail(
   subagentId: string,
   conversationId: string,
 ): SubagentDetailResult {
-  return parseSubagentMessages(subagentId, getMessages(conversationId));
+  const messages = getMessages(conversationId);
+  log.info(
+    {
+      subagentId,
+      conversationId,
+      messageCount: messages.length,
+      roles: messages.map((m) => m.role),
+    },
+    "getSubagentDetail: raw messages from DB",
+  );
+  const result = parseSubagentMessages(subagentId, messages);
+  log.info(
+    {
+      subagentId,
+      eventCount: result.events.length,
+      eventTypes: result.events.map((e) => `${e.type}:${e.toolName ?? ""}`),
+    },
+    "getSubagentDetail: parsed events",
+  );
+  const usage = getConversationUsageTotals(conversationId);
+  if (usage.inputTokens > 0 || usage.outputTokens > 0) {
+    result.usage = usage;
+  }
+  return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -168,14 +206,19 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({
       subagentId: z.string(),
       objective: z.string(),
+      usage: z
+        .object({
+          inputTokens: z.number(),
+          outputTokens: z.number(),
+          estimatedCost: z.number(),
+        })
+        .optional(),
       events: z.array(z.unknown()).describe("Subagent event objects"),
     }),
     handler: ({ pathParams, queryParams }) => {
       const conversationId = queryParams?.conversationId;
       if (!conversationId) {
-        throw new BadRequestError(
-          "conversationId query parameter is required",
-        );
+        throw new BadRequestError("conversationId query parameter is required");
       }
 
       const manager = getSubagentManager();
@@ -209,11 +252,7 @@ export const ROUTES: RouteDefinition[] = [
       }
 
       const manager = getSubagentManager();
-      const aborted = manager.abort(
-        pathParams!.id,
-        () => {},
-        conversationId,
-      );
+      const aborted = manager.abort(pathParams!.id, () => {}, conversationId);
 
       if (!aborted) {
         log.warn(

package/src/runtime/routes/surface-action-routes.ts

@@ -11,10 +11,13 @@ import { z } from "zod";
 
 import type { ChannelId } from "../../channels/types.js";
 import { isHttpAuthDisabled } from "../../config/env.js";
+import type { Conversation } from "../../daemon/conversation.js";
 import {
   findConversation,
   findConversationBySurfaceId,
+  getOrCreateConversation,
 } from "../../daemon/conversation-store.js";
+import { rawGet } from "../../memory/raw-query.js";
 import { getLogger } from "../../util/logger.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
 import { healGuardianBindingDrift } from "../guardian-vellum-migration.js";
@@ -87,6 +90,37 @@ function applyTrustContext(
   }
 }
 
+/**
+ * Resolve the conversation owning a surface, rehydrating from the DB when
+ * the in-memory lookup misses (daemon restart or LRU eviction). The DB scan
+ * is also the source of truth that the surface exists — without it,
+ * `getOrCreateConversation` would silently create a phantom conversation
+ * for any caller-supplied id.
+ */
+async function resolveSurfaceConversation(
+  conversationId: string | null | undefined,
+  surfaceId: string,
+): Promise<Conversation | undefined> {
+  const found = conversationId
+    ? findConversation(conversationId)
+    : findConversationBySurfaceId(surfaceId);
+  if (found) return found;
+
+  // Escape LIKE wildcards so a `surfaceId` like "%" or "_" can't match
+  // unrelated rows.
+  const escaped = surfaceId.replace(/[\\%_]/g, "\\$&");
+  const row = rawGet<{ conversation_id: string }>(
+    `SELECT conversation_id FROM messages
+     WHERE content LIKE ? ESCAPE '\\'
+     ORDER BY created_at DESC
+     LIMIT 1`,
+    `%"surfaceId":"${escaped}"%`,
+  );
+  if (!row) return undefined;
+  if (conversationId && conversationId !== row.conversation_id) return undefined;
+  return await getOrCreateConversation(row.conversation_id);
+}
+
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
@@ -113,9 +147,10 @@ async function handleSurfaceAction({
     throw new BadRequestError("conversationId must be a string");
   }
 
-  const conversation = conversationId
-    ? findConversation(conversationId)
-    : findConversationBySurfaceId(surfaceId);
+  const conversation = await resolveSurfaceConversation(
+    conversationId,
+    surfaceId,
+  );
 
   if (!conversation) {
     throw new NotFoundError("No active conversation found");
@@ -175,7 +210,7 @@ async function handleSurfaceAction({
   }
 }
 
-function handleSurfaceUndo({ body, pathParams }: RouteHandlerArgs) {
+async function handleSurfaceUndo({ body, pathParams }: RouteHandlerArgs) {
   const surfaceId = pathParams?.id;
   if (!surfaceId) {
     throw new BadRequestError("surfaceId path parameter is required");
@@ -186,9 +221,10 @@ function handleSurfaceUndo({ body, pathParams }: RouteHandlerArgs) {
     throw new BadRequestError("conversationId must be a string");
   }
 
-  const conversation = conversationId
-    ? findConversation(conversationId)
-    : findConversationBySurfaceId(surfaceId);
+  const conversation = await resolveSurfaceConversation(
+    conversationId,
+    surfaceId,
+  );
 
   if (!conversation) {
     throw new NotFoundError("No active conversation found");

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

@@ -7,6 +7,7 @@
 import { z } from "zod";
 
 import { recordLifecycleEvent } from "../../memory/lifecycle-events-store.js";
+import { getUsageTelemetryReporter } from "../../telemetry/usage-telemetry-reporter.js";
 import { getLogger } from "../../util/logger.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -32,6 +33,15 @@ function handleRecordLifecycleEvent({ body }: RouteHandlerArgs) {
   return { id: event.id, event_name: event.eventName };
 }
 
+async function handleTelemetryFlush() {
+  const reporter = getUsageTelemetryReporter();
+  if (!reporter) {
+    return { flushed: false, reason: "disabled" };
+  }
+  await reporter.flush();
+  return { flushed: true };
+}
+
 export const ROUTES: RouteDefinition[] = [
   {
     operationId: "telemetry_lifecycle",
@@ -58,4 +68,21 @@ export const ROUTES: RouteDefinition[] = [
     ]),
     handler: handleRecordLifecycleEvent,
   },
+  {
+    operationId: "telemetry_flush",
+    endpoint: "telemetry/flush",
+    method: "POST",
+    summary: "Flush pending telemetry events",
+    description:
+      "Force-flush all pending usage, turn, and lifecycle telemetry events to the platform.",
+    tags: ["telemetry"],
+    responseBody: z.union([
+      z.object({ flushed: z.literal(true) }),
+      z.object({
+        flushed: z.literal(false),
+        reason: z.string(),
+      }),
+    ]),
+    handler: handleTelemetryFlush,
+  },
 ];