@vellumai/assistant 0.8.0 → 0.8.2

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

@@ -20,6 +20,7 @@ import {
   TtsSynthesisError,
 } from "../../tts/synthesize-text.js";
 import { resolveTtsConfig } from "../../tts/tts-config-resolver.js";
+import type { TtsUseCase } from "../../tts/types.js";
 import { getLogger } from "../../util/logger.js";
 import {
   BadGatewayError,
@@ -93,10 +94,35 @@ async function doSynthesize(
       throw new ServiceUnavailableError("TTS provider is not configured");
     }
 
-    throw new BadGatewayError("TTS synthesis failed");
+    throw new BadGatewayError(formatTtsFailureMessage(err));
   }
 }
 
+/**
+ * Build a user-facing error message for a failed TTS synthesis, embedding the
+ * upstream provider's message when available.
+ *
+ * The provider adapters surface a clean upstream message (e.g. "Free users
+ * cannot use library voices via the API…") and `synthesize-text` already
+ * prefixes those with `"TTS synthesis failed (provider: <id>): "`. We pass
+ * pre-prefixed messages through verbatim and only add the base prefix for
+ * raw provider errors, so users never see double- or triple-prefixed
+ * messages on the desktop / channels.
+ *
+ * Exported for unit testing.
+ */
+export function formatTtsFailureMessage(err: unknown): string {
+  const base = "TTS synthesis failed";
+  if (err instanceof Error && err.message && err.message.trim()) {
+    const trimmed = err.message.trim();
+    if (/^TTS synthesis failed\b/i.test(trimmed)) {
+      return trimmed;
+    }
+    return `${base}: ${trimmed}`;
+  }
+  return base;
+}
+
 // ---------------------------------------------------------------------------
 // Response headers — shared by both routes
 // ---------------------------------------------------------------------------
@@ -155,6 +181,45 @@ async function handleSynthesizeTts({ body }: RouteHandlerArgs) {
   return doSynthesize(sanitizedText, { context: body.context });
 }
 
+async function handleSynthesizeCliTts({ body }: RouteHandlerArgs) {
+  if (!body?.text || typeof body.text !== "string") {
+    throw new BadRequestError("text is required");
+  }
+
+  const sanitizedText = sanitizeForTts(body.text).trim();
+  if (!sanitizedText) {
+    throw new BadRequestError(
+      "Text has no speakable content after sanitization",
+    );
+  }
+
+  const useCase: TtsUseCase =
+    (body.useCase as TtsUseCase | undefined) ?? "message-playback";
+  const voiceId =
+    body.voiceId && typeof body.voiceId === "string"
+      ? body.voiceId
+      : undefined;
+
+  try {
+    const result = await synthesizeText({ text: sanitizedText, useCase, voiceId });
+    return {
+      audioBase64: Buffer.from(result.audio).toString("base64"),
+      contentType: result.contentType,
+    };
+  } catch (err) {
+    log.error({ err }, "TTS CLI synthesis failed");
+
+    if (
+      err instanceof TtsSynthesisError &&
+      err.code === "TTS_PROVIDER_NOT_CONFIGURED"
+    ) {
+      throw new ServiceUnavailableError("TTS provider is not configured");
+    }
+
+    throw new BadGatewayError(formatTtsFailureMessage(err));
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Route definitions
 // ---------------------------------------------------------------------------
@@ -206,4 +271,31 @@ export const ROUTES: RouteDefinition[] = [
     responseHeaders: ttsResponseHeaders,
     handler: handleSynthesizeTts,
   },
+  {
+    operationId: "tts_synthesize_cli",
+    endpoint: "tts/synthesize-cli",
+    method: "POST",
+    policyKey: "tts/synthesize-cli",
+    requirePolicyEnforcement: true,
+    summary: "Synthesize text to speech (CLI)",
+    description:
+      "Synthesize arbitrary text to audio. Returns base64-encoded audio + content type for CLI consumption.",
+    tags: ["tts"],
+    requestBody: z.object({
+      text: z.string().describe("Text to synthesize into speech"),
+      useCase: z
+        .enum(["message-playback", "phone-call"])
+        .optional()
+        .default("message-playback"),
+      voiceId: z
+        .string()
+        .optional()
+        .describe("Provider-specific voice identifier override"),
+    }),
+    responseBody: z.object({
+      audioBase64: z.string().describe("Base64-encoded audio bytes"),
+      contentType: z.string().describe("MIME type of the audio (e.g. audio/mpeg)"),
+    }),
+    handler: handleSynthesizeCliTts,
+  },
 ];

package/src/runtime/routes/types.ts

@@ -136,4 +136,36 @@ export interface RouteDefinition {
    * RouteError subclasses rather than explicit Response objects.
    */
   additionalResponses?: Record<string, { description: string }>;
+  /**
+   * When true, the route expects a raw binary body (e.g. file uploads).
+   * The HTTP adapter already reads `rawBody` for non-JSON content types;
+   * this flag is a declarative signal for documentation and tooling.
+   */
+  rawBody?: boolean;
+  /**
+   * Per-route request-log control. Routes that opt in can suppress the
+   * per-request INFO log line after a confirmed run of successful
+   * responses — useful for high-frequency probes like `/v1/health` where
+   * the first few responses confirm the route works and every line after
+   * that is just noise. Non-success responses (status >= 400) always log.
+   */
+  logging?: RouteLoggingConfig;
+}
+
+/**
+ * Logging behavior for a single route. Currently only the success-suppression
+ * counter is supported; new knobs (sampling, periodic summary lines) can be
+ * added here as separate fields without changing call sites.
+ */
+export interface RouteLoggingConfig {
+  /**
+   * After this many successful (status < 400) responses, suppress the
+   * per-request INFO log line for further successful responses on the
+   * same route (keyed by `operationId`, so all path-param variants
+   * share a single counter).
+   *
+   * Counters are process-local and reset on restart. Warning (4xx) and
+   * error (5xx) log lines are always emitted regardless of this setting.
+   */
+  silenceSuccessAfter?: number;
 }

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

@@ -0,0 +1,243 @@
+/**
+ * Transport-agnostic routes for inspecting user-defined route handlers.
+ *
+ * These complement the dispatch routes in user-routes.ts by exposing
+ * discovery and inspection endpoints for CLI consumption. The filesystem
+ * scanning logic that was previously in the CLI command is now here.
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+import { z } from "zod";
+
+import { getConfig } from "../../config/loader.js";
+import { getPublicBaseUrl } from "../../inbound/public-ingress-urls.js";
+import { getWorkspaceRoutesDir } from "../../util/platform.js";
+import { NotFoundError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+// ── Constants ───────────────────────────────────────────────────────
+
+const HTTP_METHODS = [
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "HEAD",
+  "OPTIONS",
+] as const;
+
+type HttpMethod = (typeof HTTP_METHODS)[number];
+
+const HANDLER_EXTENSIONS = [".ts", ".js"] as const;
+
+type HandlerExtension = (typeof HANDLER_EXTENSIONS)[number];
+
+// ── Schemas ─────────────────────────────────────────────────────────
+
+const InspectParams = z
+  .object({
+    path: z.string().min(1),
+  })
+  .strict();
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+interface DiscoveredRoute {
+  routePath: string;
+  filePath: string;
+  methods: HttpMethod[];
+  description?: string;
+  fileSize: number;
+  modifiedAt: string;
+}
+
+async function inspectModule(
+  filePath: string,
+): Promise<{ methods: HttpMethod[]; description?: string }> {
+  const stat = statSync(filePath);
+  const mod = (await import(`${filePath}?t=${stat.mtimeMs}`)) as Record<
+    string,
+    unknown
+  >;
+
+  const methods: HttpMethod[] = [];
+  for (const method of HTTP_METHODS) {
+    if (typeof mod[method] === "function") {
+      methods.push(method);
+    }
+  }
+
+  const description =
+    typeof mod.description === "string" ? mod.description : undefined;
+
+  return { methods, description };
+}
+
+async function discoverRoutes(routesDir: string): Promise<DiscoveredRoute[]> {
+  if (!existsSync(routesDir)) {
+    return [];
+  }
+
+  const routes: DiscoveredRoute[] = [];
+
+  function scanDir(dir: string): void {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        scanDir(fullPath);
+      } else if (entry.isFile()) {
+        const ext = HANDLER_EXTENSIONS.find((e) => entry.name.endsWith(e)) as
+          | HandlerExtension
+          | undefined;
+        if (!ext) continue;
+
+        const relativePath = relative(routesDir, fullPath);
+        const withoutExt = relativePath.slice(0, -ext.length);
+
+        let routePath = withoutExt.replace(/\\/g, "/");
+        if (routePath.endsWith("/index")) {
+          routePath = routePath.slice(0, -"/index".length);
+        } else if (routePath === "index") {
+          routePath = "";
+        }
+
+        routes.push({
+          routePath,
+          filePath: fullPath,
+          methods: [],
+          description: undefined,
+          fileSize: 0,
+          modifiedAt: "",
+        });
+      }
+    }
+  }
+
+  scanDir(routesDir);
+
+  for (const route of routes) {
+    try {
+      const stat = statSync(route.filePath);
+      route.fileSize = stat.size;
+      route.modifiedAt = stat.mtime.toISOString();
+
+      const { methods, description } = await inspectModule(route.filePath);
+      route.methods = methods;
+      route.description = description;
+    } catch {
+      // If a module fails to load, keep it with empty methods
+    }
+  }
+
+  return routes.sort((a, b) => a.routePath.localeCompare(b.routePath));
+}
+
+function tryGetPublicBaseUrl(): string | null {
+  try {
+    const config = getConfig();
+    return getPublicBaseUrl(config);
+  } catch {
+    return null;
+  }
+}
+
+function resolveHandlerFile(
+  routesDir: string,
+  routePath: string,
+): string | null {
+  const basePath = join(routesDir, routePath);
+
+  for (const ext of HANDLER_EXTENSIONS) {
+    const candidate = `${basePath}${ext}`;
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  for (const ext of HANDLER_EXTENSIONS) {
+    const candidate = join(basePath, `index${ext}`);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+// ── Handlers ────────────────────────────────────────────────────────
+
+async function handleUserRoutesList() {
+  const routesDir = getWorkspaceRoutesDir();
+  const discovered = await discoverRoutes(routesDir);
+  const publicBase = tryGetPublicBaseUrl();
+
+  const routes = discovered.map((r) => ({
+    routePath: `/x/${r.routePath}`,
+    methods: r.methods,
+    description: r.description ?? null,
+    filePath: relative(routesDir, r.filePath),
+    publicUrl: publicBase ? `${publicBase}/x/${r.routePath}` : null,
+  }));
+
+  return { ok: true, routes };
+}
+
+async function handleUserRoutesInspect({ body = {} }: RouteHandlerArgs) {
+  const { path: routePath } = InspectParams.parse(body);
+  const routesDir = getWorkspaceRoutesDir();
+  const filePath = resolveHandlerFile(routesDir, routePath);
+
+  if (!filePath) {
+    throw new NotFoundError(
+      `No handler file found for route path "${routePath}". Run 'assistant routes list' to see available routes.`,
+    );
+  }
+
+  const stat = statSync(filePath);
+  const { methods, description } = await inspectModule(filePath);
+  const publicBase = tryGetPublicBaseUrl();
+  const publicUrl = publicBase ? `${publicBase}/x/${routePath}` : null;
+
+  return {
+    ok: true,
+    route: {
+      routePath: `/x/${routePath}`,
+      methods,
+      description: description ?? null,
+      filePath,
+      publicUrl,
+      fileSize: stat.size,
+      modifiedAt: stat.mtime.toISOString(),
+    },
+  };
+}
+
+// ── Route definitions ───────────────────────────────────────────────
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "user_routes_list",
+    method: "GET",
+    endpoint: "user-routes/list",
+    handler: handleUserRoutesList,
+    summary: "List user-defined route handlers",
+    description:
+      "Scan workspace routes directory for handler files and return discovered routes with methods and public URLs.",
+    tags: ["user-routes"],
+  },
+  {
+    operationId: "user_routes_inspect",
+    method: "POST",
+    endpoint: "user-routes/inspect",
+    handler: handleUserRoutesInspect,
+    summary: "Inspect a user-defined route handler",
+    description:
+      "Load a specific handler file and return its exported methods, description, file path, public URL, and metadata.",
+    tags: ["user-routes"],
+    requestBody: InspectParams,
+  },
+];

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

@@ -0,0 +1,165 @@
+/**
+ * Webhook route handlers for the shared HTTP/IPC route table.
+ *
+ * Serves two operations:
+ *   - webhooks_register (POST webhooks/register): Resolve a stable callback URL
+ *     for a webhook type, registering with the platform gateway on
+ *     platform-managed assistants or using the configured ingress.publicBaseUrl
+ *     on self-hosted assistants.
+ *   - webhooks_list (GET webhooks): List all webhook callback routes registered
+ *     with the platform for this assistant.
+ */
+
+import { getIsPlatform } from "../../config/env-registry.js";
+import { getConfig } from "../../config/loader.js";
+import {
+  registerCallbackRoute,
+  resolvePlatformCallbackRegistrationContext,
+} from "../../inbound/platform-callback-registration.js";
+import { getPublicBaseUrl } from "../../inbound/public-ingress-urls.js";
+import {
+  BadRequestError,
+  InternalError,
+  UnprocessableEntityError,
+} from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive the webhook path from the type name.
+ *
+ * Convention: underscores become path separators, prefixed with `webhooks/`.
+ *   telegram       → webhooks/telegram
+ *   twilio_voice   → webhooks/twilio/voice
+ *   twilio_status  → webhooks/twilio/status
+ *   resend         → webhooks/resend
+ *   oauth_callback → webhooks/oauth/callback
+ */
+function deriveWebhookPath(type: string): string {
+  return `webhooks/${type.replace(/_/g, "/")}`;
+}
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+async function handleWebhooksRegister(
+  args: RouteHandlerArgs,
+): Promise<unknown> {
+  const { type, path: pathOverride, source } = args.body ?? {};
+
+  if (!type || typeof type !== "string") {
+    throw new BadRequestError("type is required");
+  }
+
+  const webhookPath =
+    (pathOverride as string | undefined) ?? deriveWebhookPath(type as string);
+
+  if (getIsPlatform()) {
+    let callbackUrl: string;
+    try {
+      callbackUrl = await registerCallbackRoute(
+        webhookPath,
+        type as string,
+        source as string | undefined,
+      );
+    } catch (err) {
+      const msg = (err as Error).message;
+      if (msg.includes("missing platform registration context")) {
+        throw new UnprocessableEntityError(msg);
+      }
+      throw new InternalError(`Failed to register callback route: ${msg}`);
+    }
+    return { callbackUrl, type, path: webhookPath, mode: "platform" };
+  }
+
+  // Self-hosted: use ingress.publicBaseUrl
+  const config = getConfig();
+  let baseUrl: string;
+  try {
+    baseUrl = getPublicBaseUrl(config);
+  } catch (err) {
+    throw new UnprocessableEntityError((err as Error).message);
+  }
+  return {
+    callbackUrl: `${baseUrl}/${webhookPath}`,
+    type,
+    path: webhookPath,
+    mode: "self-hosted",
+  };
+}
+
+async function handleWebhooksList(_args: RouteHandlerArgs): Promise<unknown> {
+  const context = await resolvePlatformCallbackRegistrationContext();
+
+  if (!context.platformBaseUrl || !context.authHeader) {
+    throw new UnprocessableEntityError(
+      "Self-hosted webhook listing is not available. Use 'assistant webhooks register <type>' to resolve URLs on demand.",
+    );
+  }
+
+  const url = `${context.platformBaseUrl}/v1/internal/gateway/callback-routes/`;
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: context.authHeader,
+        Accept: "application/json",
+      },
+      signal: AbortSignal.timeout(10_000),
+    });
+  } catch (err) {
+    throw new InternalError(
+      `Failed to list webhook routes: ${(err as Error).message}`,
+    );
+  }
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new InternalError(
+      `Failed to list webhook routes (HTTP ${response.status}): ${detail}`,
+    );
+  }
+
+  const routes = (await response.json()) as Array<{
+    id: string;
+    assistant_id: string;
+    type: string;
+    callback_path: string;
+    callback_url: string;
+    source_identifier: string | null;
+  }>;
+
+  return { routes };
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "webhooks_register",
+    endpoint: "webhooks/register",
+    method: "POST",
+    summary: "Register a webhook callback URL",
+    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"],
+    handler: handleWebhooksRegister,
+  },
+  {
+    operationId: "webhooks_list",
+    endpoint: "webhooks",
+    method: "GET",
+    summary: "List registered webhook callback routes",
+    description:
+      "Lists all webhook callback routes registered with the platform for this assistant.",
+    tags: ["webhooks"],
+    handler: handleWebhooksList,
+  },
+];

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

@@ -9,6 +9,10 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { beforeAll, describe, expect, test } from "bun:test";
 
+import { SYNC_TAGS } from "../../daemon/message-types/sync.js";
+import type { AssistantEvent } from "../assistant-event.js";
+import { assistantEventHub } from "../assistant-event-hub.js";
+
 // ---------------------------------------------------------------------------
 // Create a temp workspace directory for isolation
 // ---------------------------------------------------------------------------
@@ -59,6 +63,15 @@ function getRoute(operationId: string): RouteDefinition {
   return route;
 }
 
+async function waitFor(predicate: () => boolean): Promise<void> {
+  const deadline = Date.now() + 500;
+  while (Date.now() < deadline) {
+    if (predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+  throw new Error("Timed out waiting for workspace route event");
+}
+
 // ===========================================================================
 // resolveWorkspacePath
 // ===========================================================================
@@ -492,6 +505,36 @@ describe("POST /v1/workspace/write", () => {
       handler({ body: { path: "subdir", content: "should fail" } }),
     ).toThrow(ConflictError);
   });
+
+  test("publishes sounds sync events when writing sounds config", async () => {
+    const received: AssistantEvent[] = [];
+    const subscription = assistantEventHub.subscribe({
+      type: "process",
+      callback: (event) => {
+        received.push(event);
+      },
+    });
+
+    try {
+      handler({
+        body: {
+          path: "data/sounds/config.json",
+          content: "{}",
+        },
+      });
+      await waitFor(() => received.length === 2);
+      expect(received.map((event) => event.message.type)).toEqual([
+        "sounds_config_updated",
+        "sync_changed",
+      ]);
+      expect(received[1]!.message).toEqual({
+        type: "sync_changed",
+        tags: [SYNC_TAGS.assistantSounds],
+      });
+    } finally {
+      subscription.dispose();
+    }
+  });
 });
 
 // ===========================================================================

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

@@ -18,6 +18,7 @@ import { basename, dirname, join } from "node:path";
 import { z } from "zod";
 
 import { getWorkspaceDir } from "../../util/platform.js";
+import { publishSoundsConfigUpdated } from "../sync/resource-sync-events.js";
 import {
   BadRequestError,
   ConflictError,
@@ -41,6 +42,29 @@ interface TreeEntry {
   modifiedAt: string;
 }
 
+const SOUNDS_WORKSPACE_PATH = "data/sounds";
+
+function normaliseWorkspacePathForSync(path: string): string {
+  return path
+    .split(/[\\/]+/)
+    .filter((part) => part.length > 0)
+    .join("/");
+}
+
+function isSoundsWorkspacePath(path: string): boolean {
+  const normalized = normaliseWorkspacePathForSync(path);
+  return (
+    normalized === SOUNDS_WORKSPACE_PATH ||
+    normalized.startsWith(`${SOUNDS_WORKSPACE_PATH}/`)
+  );
+}
+
+function publishSoundsConfigUpdatedForPaths(paths: string[]): void {
+  if (paths.some(isSoundsWorkspacePath)) {
+    publishSoundsConfigUpdated();
+  }
+}
+
 // ---------------------------------------------------------------------------
 // GET /v1/workspace/tree — list directory contents
 // ---------------------------------------------------------------------------
@@ -268,6 +292,7 @@ function handleWorkspaceWrite({ body }: RouteHandlerArgs) {
 
   mkdirSync(dirname(resolved), { recursive: true });
   writeFileSync(resolved, buffer);
+  publishSoundsConfigUpdatedForPaths([path]);
 
   return { path, size: buffer.byteLength };
 }
@@ -295,6 +320,7 @@ function handleWorkspaceMkdir({ body }: RouteHandlerArgs) {
   }
 
   mkdirSync(resolved, { recursive: true });
+  publishSoundsConfigUpdatedForPaths([path]);
   return { path };
 }
 
@@ -334,6 +360,7 @@ function handleWorkspaceRename({ body }: RouteHandlerArgs) {
 
   mkdirSync(dirname(resolvedNew), { recursive: true });
   renameSync(resolvedOld, resolvedNew);
+  publishSoundsConfigUpdatedForPaths([oldPath, newPath]);
   return { oldPath, newPath };
 }
 
@@ -361,6 +388,7 @@ function handleWorkspaceDelete({ body }: RouteHandlerArgs) {
   }
 
   rmSync(resolved, { recursive: true, force: true });
+  publishSoundsConfigUpdatedForPaths([path]);
   return { success: true };
 }