@vellumai/assistant 0.6.3 → 0.6.4

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

@@ -0,0 +1,233 @@
+/**
+ * HTTP route definitions for speech-to-text transcription.
+ *
+ * POST /v1/stt/transcribe — transcribe base64-encoded audio to text
+ *
+ * Uses the globally configured STT provider via the `services.stt`
+ * abstraction. Provider selection is resolved via `resolveBatchTranscriber()`
+ * from `providers/speech-to-text/resolve.ts`.
+ */
+
+import { z } from "zod";
+
+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 { getLogger } from "../../util/logger.js";
+import { httpError } from "../http-errors.js";
+import type { RouteDefinition } from "../http-router.js";
+
+const log = getLogger("stt-routes");
+
+/** Timeout for a single transcription request. */
+const TRANSCRIPTION_TIMEOUT_MS = 30_000;
+
+// ---------------------------------------------------------------------------
+// Error category -> HTTP status / message mapping
+// ---------------------------------------------------------------------------
+
+const STT_ERROR_MAP: Record<
+  SttErrorCategory,
+  { status: number; code: string; message: string }
+> = {
+  auth: {
+    status: 401,
+    code: "UNAUTHORIZED",
+    message: "STT provider credentials are invalid or missing",
+  },
+  "rate-limit": {
+    status: 429,
+    code: "RATE_LIMITED",
+    message: "STT provider rate limit exceeded",
+  },
+  timeout: {
+    status: 504,
+    code: "INTERNAL_ERROR",
+    message: "STT transcription timed out",
+  },
+  "invalid-audio": {
+    status: 400,
+    code: "BAD_REQUEST",
+    message: "Audio payload was rejected by the STT provider",
+  },
+  "provider-error": {
+    status: 502,
+    code: "INTERNAL_ERROR",
+    message: "STT provider error",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export function sttRouteDefinitions(): RouteDefinition[] {
+  return [
+    {
+      endpoint: "stt/transcribe",
+      method: "POST",
+      policyKey: "stt/transcribe",
+      summary: "Transcribe audio to text",
+      description:
+        "Transcribe base64-encoded audio to text using the configured STT provider. " +
+        "Provider selection is resolved globally via config.",
+      tags: ["stt"],
+      requestBody: z.object({
+        audioBase64: z
+          .string()
+          .describe("Base64-encoded audio data to transcribe"),
+        mimeType: z
+          .string()
+          .describe(
+            'MIME type of the audio data (must start with "audio/", e.g. "audio/wav", "audio/ogg")',
+          ),
+        source: z
+          .string()
+          .optional()
+          .describe(
+            "Optional source identifier for analytics (e.g. 'dictation', 'voice-mode')",
+          ),
+      }),
+      handler: async ({ req }) => {
+        // -- Parse body -------------------------------------------------------
+        let body: {
+          audioBase64?: unknown;
+          mimeType?: unknown;
+          source?: unknown;
+        };
+        try {
+          body = (await req.json()) as typeof body;
+        } catch {
+          return httpError("BAD_REQUEST", "Invalid JSON body", 400);
+        }
+
+        if (!body || typeof body !== "object") {
+          return httpError("BAD_REQUEST", "Invalid JSON body", 400);
+        }
+
+        // -- Validate audioBase64 ---------------------------------------------
+        if (
+          !body.audioBase64 ||
+          typeof body.audioBase64 !== "string" ||
+          body.audioBase64.length === 0
+        ) {
+          return httpError(
+            "BAD_REQUEST",
+            "audioBase64 is required and must be a non-empty string",
+            400,
+          );
+        }
+
+        // -- Validate mimeType ------------------------------------------------
+        if (
+          !body.mimeType ||
+          typeof body.mimeType !== "string" ||
+          !body.mimeType.startsWith("audio/")
+        ) {
+          return httpError(
+            "BAD_REQUEST",
+            'mimeType is required and must start with "audio/"',
+            400,
+          );
+        }
+
+        // -- Decode audio -----------------------------------------------------
+        // Buffer.from(str, "base64") silently accepts malformed input rather
+        // than throwing, so we validate the characters explicitly first.
+        const base64Str = body.audioBase64 as string;
+        if (
+          !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+            base64Str,
+          )
+        ) {
+          return httpError(
+            "BAD_REQUEST",
+            "Invalid base64 encoding in audioBase64",
+            400,
+          );
+        }
+
+        let audioBuffer: Buffer;
+        try {
+          audioBuffer = Buffer.from(base64Str, "base64");
+        } catch {
+          return httpError(
+            "BAD_REQUEST",
+            "audioBase64 could not be decoded",
+            400,
+          );
+        }
+
+        if (audioBuffer.length === 0) {
+          return httpError(
+            "BAD_REQUEST",
+            "Decoded audio payload is empty",
+            400,
+          );
+        }
+
+        // -- Resolve transcriber ----------------------------------------------
+        let transcriber;
+        try {
+          transcriber = await resolveBatchTranscriber();
+        } catch (err) {
+          log.error({ err }, "Failed to resolve STT transcriber");
+          return httpError(
+            "SERVICE_UNAVAILABLE",
+            "STT provider is not available",
+            503,
+          );
+        }
+
+        if (!transcriber) {
+          return httpError(
+            "SERVICE_UNAVAILABLE",
+            "No speech-to-text provider is configured",
+            503,
+          );
+        }
+
+        // -- Transcribe with timeout ------------------------------------------
+        const abortController = new AbortController();
+        const timeoutId = setTimeout(
+          () => abortController.abort(),
+          TRANSCRIPTION_TIMEOUT_MS,
+        );
+
+        try {
+          const result = await transcriber.transcribe({
+            audio: audioBuffer,
+            mimeType: body.mimeType as string,
+            signal: abortController.signal,
+          });
+
+          return Response.json({
+            text: result.text,
+            providerId: transcriber.providerId,
+            boundaryId: transcriber.boundaryId,
+          });
+        } catch (err) {
+          const sttErr = normalizeSttError(err);
+          const mapped = STT_ERROR_MAP[sttErr.category];
+
+          log.warn(
+            {
+              category: sttErr.category,
+              message: sttErr.message,
+              source: body.source,
+            },
+            "STT transcription failed",
+          );
+
+          return httpError(
+            mapped.code as Parameters<typeof httpError>[0],
+            mapped.message,
+            mapped.status,
+          );
+        } finally {
+          clearTimeout(timeoutId);
+        }
+      },
+    },
+  ];
+}

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

@@ -27,7 +27,7 @@ interface SurfaceActionTarget {
     surfaceId: string,
     actionId: string,
     data?: Record<string, unknown>,
-  ): void;
+  ): void | Promise<unknown>;
   handleSurfaceUndo?(surfaceId: string): void;
   setTrustContext?(ctx: {
     trustClass: "guardian" | "trusted_contact" | "unknown";
@@ -143,11 +143,44 @@ export async function handleSurfaceAction(
   }
 
   try {
-    conversation.handleSurfaceAction(surfaceId, actionId, data);
+    // Most action paths return `void` (regular button/selection forwards);
+    // the `launch_conversation` dispatch branch returns a structured result
+    // so we can surface validation errors (e.g. missing title / seedPrompt)
+    // as 4xx responses instead of silently reporting success.
+    const raw = await conversation.handleSurfaceAction(
+      surfaceId,
+      actionId,
+      data,
+    );
+    const result =
+      raw && typeof raw === "object" && "accepted" in raw
+        ? (raw as
+            | { accepted: true; conversationId?: string }
+            | { accepted: false; error: string })
+        : undefined;
+    if (result && result.accepted === false) {
+      log.warn(
+        {
+          conversationId: conversationId ?? undefined,
+          surfaceId,
+          actionId,
+          error: result.error,
+        },
+        "Surface action rejected",
+      );
+      return httpError("BAD_REQUEST", result.error, 400);
+    }
     log.info(
       { conversationId: conversationId ?? undefined, surfaceId, actionId },
       "Surface action handled via HTTP",
     );
+    if (
+      result &&
+      result.accepted === true &&
+      typeof result.conversationId === "string"
+    ) {
+      return Response.json({ ok: true, conversationId: result.conversationId });
+    }
     return Response.json({ ok: true });
   } catch (err) {
     log.error(
@@ -239,6 +272,12 @@ export function surfaceActionRouteDefinitions(deps: {
       }),
       responseBody: z.object({
         ok: z.boolean(),
+        conversationId: z
+          .string()
+          .describe(
+            "Id of a newly launched conversation when the action dispatched one (e.g. launch_conversation). Omitted otherwise.",
+          )
+          .optional(),
       }),
       handler: async ({ req, authContext }) => {
         if (!deps.findConversation) {

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

@@ -1,17 +1,22 @@
 /**
- * HTTP route definitions for message text-to-speech synthesis.
+ * HTTP route definitions for text-to-speech synthesis.
  *
  * POST /v1/messages/:id/tts?conversationId=... — synthesize message text to audio
+ * POST /v1/tts/synthesize                      — synthesize arbitrary text to audio
  *
- * Gated behind the `message-tts` assistant feature flag.
- * Uses Fish Audio for synthesis when configured.
+ * Both endpoints use the globally configured TTS provider via the provider
+ * abstraction. The message endpoint is gated behind the `message-tts`
+ * assistant feature flag; the generic endpoint is always available when a
+ * TTS provider is configured.
  */
 
-import { synthesizeWithFishAudio } from "../../calls/fish-audio-client.js";
+import { z } from "zod";
+
 import { sanitizeForTts } from "../../calls/tts-text-sanitizer.js";
 import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import { getConfig } from "../../config/loader.js";
 import { getMessageContent } from "../../daemon/handlers/conversation-history.js";
+import { synthesizeText } from "../../tts/synthesize-text.js";
 import { getLogger } from "../../util/logger.js";
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
@@ -32,7 +37,7 @@ export function ttsRouteDefinitions(): RouteDefinition[] {
       policyKey: "messages/tts",
       summary: "Synthesize message to speech",
       description:
-        "Synthesize a message's text content to audio using Fish Audio TTS.",
+        "Synthesize a message's text content to audio using the configured TTS provider.",
       tags: ["messages"],
       queryParams: [
         {
@@ -70,35 +75,114 @@ export function ttsRouteDefinitions(): RouteDefinition[] {
           );
         }
 
-        const { fishAudio } = config;
-        if (!fishAudio?.referenceId) {
-          return httpError(
-            "SERVICE_UNAVAILABLE",
-            "Fish Audio TTS is not configured",
-            503,
-          );
+        try {
+          const { audio, contentType } = await synthesizeText({
+            text: sanitizedText,
+            useCase: "message-playback",
+          });
+
+          return new Response(new Uint8Array(audio), {
+            status: 200,
+            headers: { "Content-Type": contentType },
+          });
+        } catch (err) {
+          log.error({ err, messageId }, "TTS synthesis failed");
+
+          // Surface provider-not-configured as 503
+          if (
+            err instanceof Error &&
+            "code" in err &&
+            (err as { code: string }).code === "TTS_PROVIDER_NOT_CONFIGURED"
+          ) {
+            return httpError(
+              "SERVICE_UNAVAILABLE",
+              "TTS provider is not configured",
+              503,
+            );
+          }
+
+          return httpError("INTERNAL_ERROR", "TTS synthesis failed", 502);
         }
+      },
+    },
 
+    // -- Generic text synthesis -----------------------------------------------
+
+    {
+      endpoint: "tts/synthesize",
+      method: "POST",
+      policyKey: "tts/synthesize",
+      summary: "Synthesize text to speech",
+      description:
+        "Synthesize arbitrary text to audio using the configured TTS provider. " +
+        "Provider selection is resolved globally via config — callers do not " +
+        "specify a provider.",
+      tags: ["tts"],
+      requestBody: z.object({
+        text: z.string().describe("Text to synthesize into speech"),
+        context: z
+          .string()
+          .optional()
+          .describe(
+            "Optional context hint for output policy or capability selection (e.g. voice-mode). " +
+              "Does not affect provider selection.",
+          ),
+        conversationId: z
+          .string()
+          .optional()
+          .describe("Optional conversation ID for scoping or analytics."),
+      }),
+      handler: async ({ req }) => {
+        let body: { text?: string; context?: string; conversationId?: string };
         try {
-          const audioBuffer = await synthesizeWithFishAudio(
-            sanitizedText,
-            fishAudio,
+          body = (await req.json()) as typeof body;
+        } catch {
+          return httpError("BAD_REQUEST", "Invalid JSON body", 400);
+        }
+
+        if (!body || typeof body !== "object") {
+          return httpError("BAD_REQUEST", "Invalid JSON body", 400);
+        }
+
+        if (!body.text || typeof body.text !== "string") {
+          return httpError("BAD_REQUEST", "text is required", 400);
+        }
+
+        const sanitizedText = sanitizeForTts(body.text).trim();
+        if (!sanitizedText) {
+          return httpError(
+            "BAD_REQUEST",
+            "Text has no speakable content after sanitization",
+            400,
           );
+        }
 
-          const format = fishAudio.format ?? "mp3";
-          const contentType =
-            format === "wav"
-              ? "audio/wav"
-              : format === "opus"
-                ? "audio/opus"
-                : "audio/mpeg";
+        try {
+          const { audio, contentType } = await synthesizeText({
+            text: sanitizedText,
+            useCase: "message-playback",
+          });
 
-          return new Response(new Uint8Array(audioBuffer), {
+          return new Response(new Uint8Array(audio), {
             status: 200,
             headers: { "Content-Type": contentType },
           });
         } catch (err) {
-          log.error({ err, messageId }, "TTS synthesis failed");
+          log.error({ err, context: body.context }, "TTS synthesis failed");
+
+          // Surface provider-not-configured as 503
+          if (
+            err instanceof Error &&
+            "code" in err &&
+            (err as { code: string }).code === "TTS_PROVIDER_NOT_CONFIGURED"
+          ) {
+            return httpError(
+              "SERVICE_UNAVAILABLE",
+              "TTS provider is not configured",
+              503,
+            );
+          }
+
           return httpError("INTERNAL_ERROR", "TTS synthesis failed", 502);
         }
       },

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

@@ -14,11 +14,30 @@ import {
   getUsageHourBuckets,
   getUsageTotals,
 } from "../../memory/llm-usage-store.js";
+import { validateTimezone } from "../../memory/usage-buckets.js";
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
 
 const VALID_GROUP_BY = new Set(["actor", "provider", "model", "conversation"]);
 
+/**
+ * Resolve the optional `tz` query param to a validated IANA identifier.
+ * Returns the tz string, or an error Response if the value is not a valid tz.
+ */
+function resolveTimezone(url: URL): string | Response {
+  const tz = url.searchParams.get("tz") ?? "UTC";
+  try {
+    validateTimezone(tz);
+  } catch (err) {
+    return httpError(
+      "BAD_REQUEST",
+      (err as Error).message,
+      400,
+    );
+  }
+  return tz;
+}
+
 /**
  * Parse and validate the `from` and `to` epoch-millis query parameters.
  * Returns the parsed range or an error Response.
@@ -110,6 +129,12 @@ export function usageRouteDefinitions(): RouteDefinition[] {
           schema: { type: "string", enum: ["daily", "hourly"] },
           description: 'Bucket granularity: "daily" (default) or "hourly"',
         },
+        {
+          name: "tz",
+          schema: { type: "string" },
+          description:
+            'IANA timezone identifier (e.g. "America/Los_Angeles"). Bucket boundaries and display labels are computed in this timezone. Defaults to "UTC" for backwards compatibility.',
+        },
       ],
       responseBody: z.object({
         buckets: z.array(z.unknown()).describe("Usage bucket objects"),
@@ -125,10 +150,13 @@ export function usageRouteDefinitions(): RouteDefinition[] {
             400,
           );
         }
+        const tz = resolveTimezone(url);
+        if (tz instanceof Response) return tz;
+        // The chart wants a continuous time axis, so fill empty buckets.
         const buckets =
           granularity === "hourly"
-            ? getUsageHourBuckets(range)
-            : getUsageDayBuckets(range);
+            ? getUsageHourBuckets(range, tz, { fillEmpty: true })
+            : getUsageDayBuckets(range, tz, { fillEmpty: true });
         return Response.json({ buckets });
       },
     },

package/src/runtime/routes/user-route-dispatcher.ts

@@ -6,6 +6,11 @@
  * exports named functions for HTTP methods (GET, POST, PUT, etc.) using
  * the standard Web API Request/Response signature.
  *
+ * Handlers receive a second `context` argument with runtime singletons
+ * (event hub, assistant ID, etc.) that would otherwise be unreachable
+ * from dynamically imported modules because Bun's cache-busting import
+ * creates separate module instances.
+ *
  * Modules are lazily loaded on first request and cached by file path +
  * mtime. When a file changes on disk, the next request reloads it via
  * Bun's dynamic `import()` with a cache-busting query parameter.
@@ -16,10 +21,35 @@ import { join, resolve } from "node:path";
 
 import { getLogger } from "../../util/logger.js";
 import { getWorkspaceRoutesDir } from "../../util/platform.js";
+import type { AssistantEventHub } from "../assistant-event-hub.js";
 import { httpError } from "../http-errors.js";
 
 const log = getLogger("user-routes");
 
+// ---------------------------------------------------------------------------
+// User route context — injected into every handler as the second argument
+// ---------------------------------------------------------------------------
+
+/**
+ * Runtime context passed to user-defined route handlers.
+ *
+ * Because user route modules are loaded via dynamic `import()` with
+ * cache-busting query parameters, they get isolated module instances
+ * and cannot import process-level singletons like the event hub
+ * directly. This context bridges the gap by carrying references to
+ * the daemon's real singletons.
+ */
+export interface UserRouteContext {
+  /** The daemon's event hub singleton — use this to publish events to connected SSE clients. */
+  readonly assistantEventHub: AssistantEventHub;
+  /** The logical assistant ID used by the daemon (typically "self"). */
+  readonly assistantId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Route handler types
+// ---------------------------------------------------------------------------
+
 /** HTTP methods that can be exported from a handler module. */
 const HTTP_METHODS = [
   "GET",
@@ -33,8 +63,18 @@ const HTTP_METHODS = [
 
 type HttpMethod = (typeof HTTP_METHODS)[number];
 
-/** The function signature that user-defined route handlers must follow. */
-type RouteHandler = (request: Request) => Response | Promise<Response>;
+/**
+ * The function signature that user-defined route handlers must follow.
+ *
+ * Handlers may accept an optional second `context` argument with runtime
+ * singletons (event hub, assistant ID). Legacy handlers that only accept
+ * `request` continue to work — the context is passed positionally but
+ * ignored if the handler doesn't declare the parameter.
+ */
+type RouteHandler = (
+  request: Request,
+  context: UserRouteContext,
+) => Response | Promise<Response>;
 
 /** A loaded handler module with its cached metadata. */
 interface CachedModule {
@@ -55,10 +95,15 @@ const HANDLER_EXTENSIONS = [".ts", ".js"] as const;
 export class UserRouteDispatcher {
   private moduleCache = new Map<string, CachedModule>();
   private handlerTimeoutMs: number;
+  private context: UserRouteContext;
 
-  constructor(options?: { handlerTimeoutMs?: number }) {
+  constructor(options: {
+    handlerTimeoutMs?: number;
+    context: UserRouteContext;
+  }) {
     this.handlerTimeoutMs =
-      options?.handlerTimeoutMs ?? DEFAULT_HANDLER_TIMEOUT_MS;
+      options.handlerTimeoutMs ?? DEFAULT_HANDLER_TIMEOUT_MS;
+    this.context = Object.freeze({ ...options.context });
   }
 
   /**
@@ -192,7 +237,7 @@ export class UserRouteDispatcher {
   ): Promise<Response> {
     try {
       const result = await Promise.race([
-        Promise.resolve(handler(request)),
+        Promise.resolve(handler(request, this.context)),
         new Promise<never>((_, reject) =>
           setTimeout(
             () => reject(new Error("Handler timed out")),

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

@@ -4,12 +4,24 @@
  * Registers a single catch-all route that delegates to the
  * UserRouteDispatcher for file-based dispatch from
  * `$VELLUM_WORKSPACE_DIR/routes/`.
+ *
+ * The dispatcher injects a `UserRouteContext` into every handler so
+ * that dynamically imported route modules can access daemon singletons
+ * (event hub, assistant ID) without relying on module-level imports
+ * that would resolve to separate instances due to cache-busting.
  */
 
+import { assistantEventHub } from "../assistant-event-hub.js";
+import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
 import type { RouteDefinition } from "../http-router.js";
 import { UserRouteDispatcher } from "./user-route-dispatcher.js";
 
-const dispatcher = new UserRouteDispatcher();
+const dispatcher = new UserRouteDispatcher({
+  context: {
+    assistantEventHub,
+    assistantId: DAEMON_INTERNAL_ASSISTANT_ID,
+  },
+});
 
 /**
  * HTTP methods supported by user-defined route handlers.

package/src/runtime/routes/work-items-routes.ts

@@ -19,6 +19,7 @@ import {
   getToolDescription,
   sanitizeToolList,
 } from "../../tasks/tool-sanitizer.js";
+import { createAbortReason } from "../../util/abort-reasons.js";
 import { getLogger } from "../../util/logger.js";
 import { truncate } from "../../util/truncate.js";
 import { resolveRequiredTools } from "../../work-items/resolve-required-tools.js";
@@ -587,7 +588,13 @@ export function workItemRouteDefinitions(
           const conversation = deps.findConversation(conversationId);
           if (conversation) {
             conversation.headlessLock = false;
-            conversation.abort();
+            conversation.abort(
+              createAbortReason(
+                "work_item_aborted",
+                "work-items-routes.cancel",
+                conversationId,
+              ),
+            );
             getSubagentManager().abortAllForParent(conversationId);
           }
         }