@vellumai/assistant 0.5.6 → 0.5.8

package/src/runtime/auth/token-service.ts

@@ -28,22 +28,6 @@ import type { ScopeProfile, TokenAudience, TokenClaims } from "./types.js";
 
 const log = getLogger("token-service");
 
-// ---------------------------------------------------------------------------
-// Bootstrap sentinel error
-// ---------------------------------------------------------------------------
-
-/**
- * Thrown when the gateway's signing-key bootstrap endpoint returns 403,
- * indicating that bootstrap has already completed (daemon restart case).
- * The caller should fall back to loading the key from disk.
- */
-export class BootstrapAlreadyCompleted extends Error {
-  constructor() {
-    super("Gateway signing key bootstrap already completed");
-    this.name = "BootstrapAlreadyCompleted";
-  }
-}
-
 // ---------------------------------------------------------------------------
 // Signing key management
 // ---------------------------------------------------------------------------
@@ -58,28 +42,44 @@ function getSigningKeyPath(): string {
   return join(getRootDir(), "protected", "actor-token-signing-key");
 }
 
+/**
+ * Load a signing key from disk. Returns the key buffer if found and valid,
+ * or undefined if the file does not exist or is invalid.
+ *
+ * Used in the Docker 403-fallback path where generating a new key would
+ * create a mismatch with the gateway's already-bootstrapped key.
+ */
+export function loadSigningKey(): Buffer | undefined {
+  const keyPath = getSigningKeyPath();
+  if (!existsSync(keyPath)) {
+    return undefined;
+  }
+  try {
+    const raw = readFileSync(keyPath);
+    if (raw.length === 32) {
+      log.info("Auth signing key loaded from disk");
+      return raw;
+    }
+    log.warn("Signing key file has unexpected length");
+    return undefined;
+  } catch (err) {
+    log.warn({ err }, "Failed to read signing key file");
+    return undefined;
+  }
+}
+
 /**
  * Load a signing key from disk or generate and persist a new one.
  * Uses atomic-write + chmod 0o600 for safe persistence.
  */
 export function loadOrCreateSigningKey(): Buffer {
-  const keyPath = getSigningKeyPath();
-
-  // Try to load existing key
-  if (existsSync(keyPath)) {
-    try {
-      const raw = readFileSync(keyPath);
-      if (raw.length === 32) {
-        log.info("Auth signing key loaded from disk");
-        return raw;
-      }
-      log.warn("Signing key file has unexpected length, regenerating");
-    } catch (err) {
-      log.warn({ err }, "Failed to read signing key file, regenerating");
-    }
+  const existing = loadSigningKey();
+  if (existing) {
+    return existing;
   }
 
   // Generate and persist a new key
+  const keyPath = getSigningKeyPath();
   const newKey = randomBytes(32);
   const dir = dirname(keyPath);
   if (!existsSync(dir)) {
@@ -94,120 +94,25 @@ export function loadOrCreateSigningKey(): Buffer {
   return newKey;
 }
 
-/**
- * Fetch the shared signing key from the gateway's bootstrap endpoint.
- *
- * Used in Docker mode where the gateway owns the signing key and the daemon
- * must fetch it at startup. Retries up to 30 times with 1s intervals to
- * tolerate gateway startup delays.
- *
- * @returns A 32-byte Buffer containing the signing key.
- * @throws {BootstrapAlreadyCompleted} If the gateway returns 403 (bootstrap
- *   already completed — daemon restart case). Caller should fall back to
- *   loading the key from disk.
- * @throws {Error} If the gateway is unreachable after all retry attempts.
- */
-export async function fetchSigningKeyFromGateway(): Promise<Buffer> {
-  const gatewayUrl = process.env.GATEWAY_INTERNAL_URL;
-  if (!gatewayUrl) {
-    throw new Error("GATEWAY_INTERNAL_URL not set — cannot fetch signing key");
-  }
-
-  const maxAttempts = 30;
-  const intervalMs = 1000;
-
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    let resp: Response | undefined;
-    try {
-      resp = await fetch(`${gatewayUrl}/internal/signing-key-bootstrap`, {
-        signal: AbortSignal.timeout(5000),
-      });
-    } catch (err) {
-      log.warn(
-        { err, attempt },
-        "Signing key bootstrap: connection failed, retrying",
-      );
-      await Bun.sleep(intervalMs);
-      continue;
-    }
-
-    if (resp.ok) {
-      const body = (await resp.json()) as { key: string };
-      const keyBuf = Buffer.from(body.key, "hex");
-      if (keyBuf.length !== 32) {
-        throw new Error(`Invalid signing key length: ${keyBuf.length}`);
-      }
-      log.info("Signing key fetched from gateway bootstrap endpoint");
-      return keyBuf;
-    }
-
-    if (resp.status === 403) {
-      // Bootstrap already completed — fall through to file-based load.
-      // This happens on daemon restart when the gateway lockfile persists.
-      log.info(
-        "Gateway signing key bootstrap already completed — loading from disk",
-      );
-      throw new BootstrapAlreadyCompleted();
-    }
-
-    log.warn(
-      { status: resp.status, attempt },
-      "Signing key bootstrap: gateway not ready, retrying",
-    );
-
-    await Bun.sleep(intervalMs);
-  }
-
-  throw new Error("Signing key bootstrap: timed out waiting for gateway");
-}
-
-/**
- * Persist a signing key to disk using an atomic-write pattern.
- * Used after fetching the key from the gateway so daemon restarts can
- * load it from disk when the gateway returns 403.
- */
-function persistSigningKey(key: Buffer): void {
-  const keyPath = getSigningKeyPath();
-  const dir = dirname(keyPath);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-  const tmpPath = keyPath + ".tmp." + process.pid;
-  writeFileSync(tmpPath, key, { mode: 0o600 });
-  renameSync(tmpPath, keyPath);
-  chmodSync(keyPath, 0o600);
-}
-
 /**
  * Resolve the signing key for the current environment.
  *
- * In Docker mode (IS_CONTAINERIZED=true + GATEWAY_INTERNAL_URL set), fetches
- * the key from the gateway's bootstrap endpoint and persists it locally for
- * restart resilience. On daemon restart (gateway returns 403), falls back to
- * loading the key from disk.
- *
- * In local mode, delegates to the existing file-based loadOrCreateSigningKey().
+ * Resolution order:
+ *   1. ACTOR_TOKEN_SIGNING_KEY env var (hex-encoded, set by CLI for Docker)
+ *   2. File-based load/create (~/.vellum/protected/actor-token-signing-key)
  */
-export async function resolveSigningKey(): Promise<Buffer> {
-  const isContainerized = process.env.IS_CONTAINERIZED === "true";
-  const gatewayUrl = process.env.GATEWAY_INTERNAL_URL;
-
-  if (isContainerized && gatewayUrl) {
-    try {
-      const key = await fetchSigningKeyFromGateway();
-      // Persist locally so daemon restarts (where gateway returns 403) load from disk.
-      persistSigningKey(key);
-      return key;
-    } catch (err) {
-      if (err instanceof BootstrapAlreadyCompleted) {
-        // Gateway already bootstrapped (daemon restart) — load from disk.
-        return loadOrCreateSigningKey();
-      }
-      throw err;
+export function resolveSigningKey(): Buffer {
+  const envKey = process.env.ACTOR_TOKEN_SIGNING_KEY;
+  if (envKey) {
+    if (!/^[0-9a-f]{64}$/i.test(envKey)) {
+      throw new Error(
+        `Invalid ACTOR_TOKEN_SIGNING_KEY: expected 64 hex characters, got ${envKey.length} chars`,
+      );
     }
+    log.info("Signing key loaded from ACTOR_TOKEN_SIGNING_KEY env var");
+    return Buffer.from(envKey, "hex");
   }
 
-  // Local mode: use file-based load/create (unchanged behavior).
   return loadOrCreateSigningKey();
 }
 
@@ -246,7 +151,7 @@ export function isSigningKeyInitialized(): boolean {
 
 /**
  * Returns a short hex fingerprint of the current signing key.
- * Used by daemon_status to let clients detect instance switches.
+ * Used by assistant_status to let clients detect instance switches.
  */
 export function getSigningKeyFingerprint(): string {
   return createHash("sha256")

package/src/runtime/channel-readiness-service.ts

@@ -15,7 +15,6 @@ import type {
   ReadinessCheckResult,
   SetupStatus,
 } from "./channel-readiness-types.js";
-import { probeLocalGatewayHealth } from "./local-gateway-health.js";
 
 /** Remote check results are cached for 5 minutes before being considered stale. */
 export const REMOTE_TTL_MS = 5 * 60 * 1000;
@@ -82,7 +81,7 @@ const voiceProbe: ChannelProbe = {
     const hasPhone = !!resolveTwilioPhoneNumber();
     const ingress = checkIngress();
 
-    const checks: ReadinessCheckResult[] = [
+    return [
       check(
         "twilio_credentials",
         hasCreds,
@@ -97,20 +96,6 @@ const voiceProbe: ChannelProbe = {
       ),
       ingress,
     ];
-
-    if (ingress.passed) {
-      const gw = await probeLocalGatewayHealth();
-      checks.push(
-        check(
-          "gateway_health",
-          gw.healthy,
-          `Local gateway is serving requests at ${gw.target}`,
-          `Local gateway is not serving requests at ${gw.target}${gw.error ? `: ${gw.error}` : ""}`,
-        ),
-      );
-    }
-
-    return checks;
   },
 };
 

package/src/runtime/gateway-client.ts

@@ -6,6 +6,24 @@ import type { RuntimeAttachmentMetadata } from "./http-types.js";
 
 const log = getLogger("gateway-client");
 
+/**
+ * Error thrown when the gateway returns a non-OK response for channel delivery.
+ * Carries the optional `userMessage` field from the gateway so callers can
+ * surface actionable error text to end-users.
+ */
+export class ChannelDeliveryError extends Error {
+  readonly statusCode: number;
+  /** A user-facing error message from the gateway, if available. */
+  readonly userMessage?: string;
+
+  constructor(statusCode: number, body: string, userMessage?: string) {
+    super(`Channel reply delivery failed (${statusCode}): ${body}`);
+    this.name = "ChannelDeliveryError";
+    this.statusCode = statusCode;
+    this.userMessage = userMessage;
+  }
+}
+
 const DELIVERY_TIMEOUT_MS = 30_000;
 const MANAGED_OUTBOUND_SEND_PATH =
   "/v1/internal/managed-gateway/outbound-send/";
@@ -37,6 +55,8 @@ export interface ChannelReplyPayload {
   useBlocks?: boolean;
   /** When provided, add or remove an emoji reaction on a message. */
   reaction?: { action: "add" | "remove"; name: string; messageTs: string };
+  /** When provided, set or clear the Slack Assistants API thread status. */
+  assistantThreadStatus?: { channel: string; threadTs: string; status: string };
 }
 
 export interface ChannelDeliveryResult {
@@ -81,13 +101,36 @@ export async function deliverChannelReply(
 
   if (!response.ok) {
     const body = await response.text().catch(() => "<unreadable>");
+
+    // Try to extract userMessage from JSON error responses (e.g. from the
+    // Slack delivery endpoint) so callers can surface actionable errors.
+    let userMessage: string | undefined;
+    try {
+      const parsed = JSON.parse(body) as { userMessage?: string };
+      if (typeof parsed.userMessage === "string") {
+        userMessage = parsed.userMessage;
+      }
+    } catch {
+      // Body wasn't JSON — that's fine, userMessage stays undefined.
+    }
+
     log.error(
-      { status: response.status, body, callbackUrl, chatId: payload.chatId },
+      {
+        status: response.status,
+        body,
+        callbackUrl,
+        chatId: payload.chatId,
+        ...(userMessage && { userMessage }),
+      },
       "Channel reply delivery failed",
     );
-    throw new Error(
-      `Channel reply delivery failed (${response.status}): ${body}`,
-    );
+    if (userMessage) {
+      log.warn(
+        { chatId: payload.chatId, userMessage },
+        "Gateway returned actionable error for user",
+      );
+    }
+    throw new ChannelDeliveryError(response.status, body, userMessage);
   }
 
   const result: ChannelDeliveryResult = { ok: true };

package/src/runtime/guardian-decision-types.ts

@@ -38,6 +38,8 @@ export interface GuardianDecisionAction {
   action: string;
   /** Human-readable label for the action. */
   label: string;
+  /** Short explanation shown in rich-UI legends (Telegram, Slack). */
+  description?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -46,14 +48,27 @@ export interface GuardianDecisionAction {
 
 /** Canonical set of all guardian decision actions with their labels. */
 export const GUARDIAN_DECISION_ACTIONS = {
-  approve_once: { action: "approve_once", label: "Approve once" },
-  approve_10m: { action: "approve_10m", label: "Allow 10 min" },
+  approve_once: {
+    action: "approve_once",
+    label: "Approve once",
+    description: "This tool, this call only",
+  },
+  approve_10m: {
+    action: "approve_10m",
+    label: "Allow 10 min",
+    description: "All tools for 10 minutes",
+  },
   approve_conversation: {
     action: "approve_conversation",
     label: "Allow conversation",
+    description: "All tools for this conversation",
+  },
+  approve_always: {
+    action: "approve_always",
+    label: "Approve always",
+    description: "This tool, permanently",
   },
-  approve_always: { action: "approve_always", label: "Approve always" },
-  reject: { action: "reject", label: "Reject" },
+  reject: { action: "reject", label: "Reject", description: "Deny this call" },
 } as const satisfies Record<string, GuardianDecisionAction>;
 
 /**
@@ -89,6 +104,32 @@ export function buildDecisionActions(opts?: {
   ];
 }
 
+/**
+ * Build a compact legend string explaining each action, for rich-UI channels
+ * (Telegram, Slack) where buttons are shown but their scope isn't obvious.
+ *
+ * Accepts either `GuardianDecisionAction[]` or action ID strings and looks up
+ * descriptions from the canonical constants.
+ */
+export function buildActionLegend(
+  actionIds: readonly (string | { action?: string; id?: string })[],
+): string {
+  const lookup = GUARDIAN_DECISION_ACTIONS as Record<
+    string,
+    GuardianDecisionAction | undefined
+  >;
+  const lines = actionIds
+    .map((a) => {
+      const id = typeof a === "string" ? a : (a.action ?? a.id ?? "");
+      const canonical = lookup[id];
+      return canonical?.description
+        ? `• *${canonical.label}* — ${canonical.description}`
+        : null;
+    })
+    .filter(Boolean);
+  return lines.length > 0 ? lines.join("\n") : "";
+}
+
 /**
  * Build the plain-text fallback instruction string that matches the given
  * set of decision actions. Ensures the text always includes parser-compatible

package/src/runtime/http-server.ts

@@ -106,6 +106,7 @@ import { handleServePage } from "./routes/app-routes.js";
 import { appRouteDefinitions } from "./routes/app-routes.js";
 import { approvalRouteDefinitions } from "./routes/approval-routes.js";
 import { attachmentRouteDefinitions } from "./routes/attachment-routes.js";
+import { handleGetAudio } from "./routes/audio-routes.js";
 import { avatarRouteDefinitions } from "./routes/avatar-routes.js";
 import { brainGraphRouteDefinitions } from "./routes/brain-graph-routes.js";
 import { btwRouteDefinitions } from "./routes/btw-routes.js";
@@ -144,16 +145,22 @@ import { handleGuardianRefresh } from "./routes/guardian-refresh-routes.js";
 import { hostBashRouteDefinitions } from "./routes/host-bash-routes.js";
 import { hostCuRouteDefinitions } from "./routes/host-cu-routes.js";
 import { hostFileRouteDefinitions } from "./routes/host-file-routes.js";
-import { handleHealth } from "./routes/identity-routes.js";
-import { identityRouteDefinitions } from "./routes/identity-routes.js";
+import {
+  handleHealth,
+  handleReadyz,
+  identityRouteDefinitions,
+} from "./routes/identity-routes.js";
 import { slackChannelRouteDefinitions } from "./routes/integrations/slack/channel.js";
 import { slackShareRouteDefinitions } from "./routes/integrations/slack/share.js";
 import { telegramRouteDefinitions } from "./routes/integrations/telegram.js";
 import { twilioRouteDefinitions } from "./routes/integrations/twilio.js";
+import { vercelRouteDefinitions } from "./routes/integrations/vercel.js";
 import { inviteRouteDefinitions } from "./routes/invite-routes.js";
 import { logExportRouteDefinitions } from "./routes/log-export-routes.js";
 import { memoryItemRouteDefinitions } from "./routes/memory-item-routes.js";
+import { migrationRollbackRouteDefinitions } from "./routes/migration-rollback-routes.js";
 import { migrationRouteDefinitions } from "./routes/migration-routes.js";
+import { notificationRouteDefinitions } from "./routes/notification-routes.js";
 import { oauthAppsRouteDefinitions } from "./routes/oauth-apps.js";
 import type { PairingHandlerContext } from "./routes/pairing-routes.js";
 import {
@@ -172,10 +179,12 @@ import { surfaceContentRouteDefinitions } from "./routes/surface-content-routes.
 import { telemetryRouteDefinitions } from "./routes/telemetry-routes.js";
 import { traceEventRouteDefinitions } from "./routes/trace-event-routes.js";
 import { trustRulesRouteDefinitions } from "./routes/trust-rules-routes.js";
+import { ttsRouteDefinitions } from "./routes/tts-routes.js";
 import { upgradeBroadcastRouteDefinitions } from "./routes/upgrade-broadcast-routes.js";
 import { usageRouteDefinitions } from "./routes/usage-routes.js";
 import { watchRouteDefinitions } from "./routes/watch-routes.js";
 import { workItemRouteDefinitions } from "./routes/work-items-routes.js";
+import { workspaceCommitRouteDefinitions } from "./routes/workspace-commit-routes.js";
 import { workspaceRouteDefinitions } from "./routes/workspace-routes.js";
 
 // Re-export for consumers
@@ -464,7 +473,10 @@ export class RuntimeHttpServer {
     server.timeout(req, 1800);
     // Skip request logging for health-check probes to reduce log noise.
     const url = new URL(req.url);
-    if (url.pathname === "/healthz" && req.method === "GET") {
+    if (
+      (url.pathname === "/healthz" || url.pathname === "/readyz") &&
+      req.method === "GET"
+    ) {
       return this.routeRequest(req, server);
     }
     return withRequestLogging(req, () => this.routeRequest(req, server));
@@ -481,6 +493,10 @@ export class RuntimeHttpServer {
       return handleHealth();
     }
 
+    if (path === "/readyz" && req.method === "GET") {
+      return handleReadyz();
+    }
+
     // WebSocket upgrade for the Chrome extension browser relay.
     if (
       path === "/v1/browser-relay" &&
@@ -503,6 +519,13 @@ export class RuntimeHttpServer {
     const twilioResponse = await this.handleTwilioWebhook(req, path);
     if (twilioResponse) return twilioResponse;
 
+    // Audio serving endpoint — before auth check because Twilio
+    // fetches these URLs directly. The audioId is an unguessable UUID.
+    const audioMatch = path.match(/^\/v1\/audio\/([^/]+)$/);
+    if (audioMatch && req.method === "GET") {
+      return handleGetAudio(audioMatch[1]);
+    }
+
     // Pairing endpoints (unauthenticated, secret-gated)
     if (path === "/v1/pairing/request" && req.method === "POST") {
       return await handlePairingRequest(req, this.pairingContext);
@@ -920,6 +943,8 @@ export class RuntimeHttpServer {
       }),
       ...identityRouteDefinitions(),
       ...upgradeBroadcastRouteDefinitions(),
+      ...workspaceCommitRouteDefinitions(),
+      ...migrationRollbackRouteDefinitions(),
       ...debugRouteDefinitions(),
       ...usageRouteDefinitions(),
       ...telemetryRouteDefinitions(),
@@ -931,6 +956,7 @@ export class RuntimeHttpServer {
       ...scheduleRouteDefinitions({
         sendMessageDeps: this.sendMessageDeps,
       }),
+      ...notificationRouteDefinitions(),
       ...diagnosticsRouteDefinitions(),
       ...logExportRouteDefinitions(),
       ...documentRouteDefinitions(),
@@ -961,6 +987,7 @@ export class RuntimeHttpServer {
             }
           : undefined,
       }),
+      ...ttsRouteDefinitions(),
 
       // Browser relay — not extracted into a domain module because
       // these two routes depend on the in-process extensionRelayServer
@@ -1165,6 +1192,7 @@ export class RuntimeHttpServer {
       ...slackChannelRouteDefinitions(),
       ...slackShareRouteDefinitions(),
       ...twilioRouteDefinitions(),
+      ...vercelRouteDefinitions(),
       ...channelReadinessRouteDefinitions(),
       ...oauthAppsRouteDefinitions(),
       ...attachmentRouteDefinitions(),

package/src/runtime/middleware/error-handler.ts

@@ -4,7 +4,6 @@
 
 import {
   ConfigError,
-  IngressBlockedError,
   ProviderNotConfiguredError,
 } from "../../util/errors.js";
 import { getLogger } from "../../util/logger.js";
@@ -14,7 +13,7 @@ const log = getLogger("runtime-http");
 
 /**
  * Wrap an async endpoint handler with standard error handling.
- * Catches IngressBlockedError (422), ConfigError (422), and generic errors (500).
+ * Catches ConfigError (422) and generic errors (500).
  */
 export async function withErrorHandling(
   endpoint: string,
@@ -23,13 +22,6 @@ export async function withErrorHandling(
   try {
     return await handler();
   } catch (err) {
-    if (err instanceof IngressBlockedError) {
-      log.warn(
-        { endpoint, detectedTypes: err.detectedTypes },
-        "Blocked HTTP request containing secrets",
-      );
-      return httpError("UNPROCESSABLE_ENTITY", err.message, 422);
-    }
     if (err instanceof ProviderNotConfiguredError) {
       log.warn({ err, endpoint }, "No LLM provider configured");
       return httpError(

package/src/runtime/routes/access-request-decision.ts

@@ -116,7 +116,7 @@ export async function deliverVerificationCodeToGuardian(params: {
 }): Promise<DeliveryResult> {
   const text =
     `You approved access for ${params.requesterIdentifier}. ` +
-    `Give them this verification code: ${params.verificationCode}. ` +
+    `Give them this verification code: \`${params.verificationCode}\`. ` +
     `The code expires in 10 minutes.`;
 
   try {
@@ -189,7 +189,7 @@ export async function deliverVerificationCodeToRequester(params: {
 }): Promise<DeliveryResult> {
   const text =
     `Great news — your access request was approved! ` +
-    `Your verification code is: ${params.verificationCode}. ` +
+    `Your verification code is: \`${params.verificationCode}\`. ` +
     `Reply with it here to complete verification. The code expires in 10 minutes.`;
 
   const target = resolveRequesterTarget(params);

package/src/runtime/routes/app-management-routes.ts

@@ -36,6 +36,7 @@ import {
   getApp,
   getAppDirPath,
   getAppPreview,
+  inlineDistAssets,
   isMultifileApp,
   listApps,
   queryAppRecords,
@@ -684,7 +685,7 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
               }
             }
             if (existsSync(distIndex)) {
-              html = readFileSync(distIndex, "utf-8");
+              html = inlineDistAssets(appDir, readFileSync(distIndex, "utf-8"));
             } else {
               html = `<p>App compilation failed. Edit a source file to trigger a rebuild.</p>`;
             }