@vellumai/assistant 0.5.7 → 0.5.9

package/src/providers/registry.ts

@@ -1,7 +1,6 @@
 import { getProviderKeyAsync } from "../security/secure-keys.js";
-import { ConfigError, ProviderNotConfiguredError } from "../util/errors.js";
+import { ProviderNotConfiguredError } from "../util/errors.js";
 import { AnthropicProvider } from "./anthropic/client.js";
-import { FailoverProvider, type ProviderHealthStatus } from "./failover.js";
 import { FireworksProvider } from "./fireworks/client.js";
 import { GeminiProvider } from "./gemini/client.js";
 import {
@@ -17,8 +16,6 @@ import type { Provider } from "./types.js";
 
 const providers = new Map<string, Provider>();
 const routingSources = new Map<string, "user-key" | "managed-proxy">();
-let cachedFailoverProvider: FailoverProvider | null = null;
-let cachedFailoverKey: string | null = null;
 
 export function registerProvider(name: string, provider: Provider): void {
   providers.set(name, provider);
@@ -27,95 +24,11 @@ export function registerProvider(name: string, provider: Provider): void {
 export function getProvider(name: string): Provider {
   const provider = providers.get(name);
   if (!provider) {
-    throw new ConfigError(
-      `Provider "${name}" not found. Available: ${listProviders().join(", ")}`,
-    );
+    throw new ProviderNotConfiguredError(name, listProviders());
   }
   return provider;
 }
 
-export interface ProviderSelection {
-  /** Ordered list of available provider names */
-  availableProviders: string[];
-  /** The selected (effective) primary provider name, or null if none available */
-  selectedPrimary: string | null;
-  /** Whether the effective primary differs from the requested primary */
-  usedFallbackPrimary: boolean;
-}
-
-/**
- * Resolve provider selection from requested primary and provider order.
- * Dedupes [requestedPrimary, ...providerOrder], filtered to initialized providers.
- * Returns null selectedPrimary when no providers are available.
- */
-export function resolveProviderSelection(
-  requestedPrimary: string,
-  providerOrder: string[],
-): ProviderSelection {
-  const ordered: string[] = [];
-  const seen = new Set<string>();
-
-  for (const name of [requestedPrimary, ...providerOrder]) {
-    if (seen.has(name)) continue;
-    seen.add(name);
-    if (providers.has(name)) {
-      ordered.push(name);
-    }
-  }
-
-  if (ordered.length === 0) {
-    return {
-      availableProviders: [],
-      selectedPrimary: null,
-      usedFallbackPrimary: false,
-    };
-  }
-
-  return {
-    availableProviders: ordered,
-    selectedPrimary: ordered[0],
-    usedFallbackPrimary: ordered[0] !== requestedPrimary,
-  };
-}
-
-/**
- * Build a provider that tries the effective primary provider first, then falls
- * back to others in the configured order. If the requested primary is not
- * available, automatically selects the first available provider from the
- * deduped [primaryName, ...providerOrder] list (fail-open).
- *
- * Throws ConfigError only when NO providers are available at all.
- * Caches the FailoverProvider instance so health state persists across calls.
- */
-export function getFailoverProvider(
-  primaryName: string,
-  providerOrder: string[],
-): Provider {
-  const selection = resolveProviderSelection(primaryName, providerOrder);
-
-  if (!selection.selectedPrimary) {
-    throw new ProviderNotConfiguredError(primaryName, listProviders());
-  }
-
-  const orderedProviders: Provider[] = selection.availableProviders.map(
-    (name) => providers.get(name)!,
-  );
-
-  if (orderedProviders.length === 1) {
-    return orderedProviders[0];
-  }
-
-  // Cache key from effective ordered providers (not raw input strings)
-  const cacheKey = selection.availableProviders.join(",");
-  if (cachedFailoverProvider && cachedFailoverKey === cacheKey) {
-    return cachedFailoverProvider;
-  }
-
-  cachedFailoverProvider = new FailoverProvider(orderedProviders);
-  cachedFailoverKey = cacheKey;
-  return cachedFailoverProvider;
-}
-
 export function listProviders(): string[] {
   return Array.from(providers.keys());
 }
@@ -151,7 +64,6 @@ export interface ProvidersConfig {
       provider: string;
     };
   };
-  providerOrder?: string[];
   timeouts?: { providerStreamTimeoutSec?: number };
 }
 
@@ -172,53 +84,6 @@ function resolveModel(config: ProvidersConfig, providerName: string): string {
   return getProviderDefaultModel(providerName);
 }
 
-export interface ProviderDebugStatus {
-  configuredPrimary: string;
-  activePrimary: string | null;
-  usedFallback: boolean;
-  registeredProviders: string[];
-  failoverHealth: ProviderHealthStatus[] | null;
-  overallHealth: "healthy" | "degraded" | "down";
-  routingSources: Record<string, "user-key" | "managed-proxy">;
-}
-
-export function getProviderDebugStatus(
-  configuredProvider: string,
-  providerOrder: string[],
-): ProviderDebugStatus {
-  const registered = listProviders();
-  const selection = resolveProviderSelection(configuredProvider, providerOrder);
-
-  let failoverHealth: ProviderHealthStatus[] | null = null;
-  if (cachedFailoverProvider) {
-    failoverHealth = cachedFailoverProvider.getHealthStatus();
-  }
-
-  let overallHealth: "healthy" | "degraded" | "down" = "down";
-  if (registered.length > 0 && selection.selectedPrimary) {
-    if (!failoverHealth) {
-      overallHealth = "healthy";
-    } else {
-      const healthyCount = failoverHealth.filter((h) => h.healthy).length;
-      if (healthyCount === failoverHealth.length) {
-        overallHealth = "healthy";
-      } else if (healthyCount > 0) {
-        overallHealth = "degraded";
-      }
-    }
-  }
-
-  return {
-    configuredPrimary: configuredProvider,
-    activePrimary: selection.selectedPrimary,
-    usedFallback: selection.usedFallbackPrimary,
-    registeredProviders: registered,
-    failoverHealth,
-    overallHealth,
-    routingSources: Object.fromEntries(routingSources),
-  };
-}
-
 /**
  * Resolve provider credentials using mode-aware logic.
  * In "managed" mode, routes through the platform proxy.
@@ -273,8 +138,6 @@ export async function initializeProviders(
 ): Promise<void> {
   providers.clear();
   routingSources.clear();
-  cachedFailoverProvider = null;
-  cachedFailoverKey = null;
 
   const streamTimeoutMs =
     (config.timeouts?.providerStreamTimeoutSec ?? 300) * 1000;

package/src/providers/types.ts

@@ -130,7 +130,7 @@ export type ProviderEvent =
 export interface SendMessageConfig {
   model?: string;
   modelIntent?: ModelIntent;
-  effort?: "low" | "medium" | "high";
+  effort?: "low" | "medium" | "high" | "max";
   [key: string]: unknown;
 }
 

package/src/runtime/access-request-helper.ts

@@ -55,6 +55,8 @@ export interface AccessRequestParams {
   actorDisplayName?: string;
   actorUsername?: string;
   previousMemberStatus?: Exclude<ChannelStatus, "unverified">;
+  /** Preview of the requester's original message, shown to the guardian. */
+  messagePreview?: string;
 }
 
 export type AccessRequestResult =
@@ -90,6 +92,7 @@ export function notifyGuardianOfAccessRequest(
     actorDisplayName,
     actorUsername,
     previousMemberStatus,
+    messagePreview,
   } = params;
 
   if (!actorExternalId) {
@@ -244,6 +247,7 @@ export function notifyGuardianOfAccessRequest(
       guardianBindingChannel,
       guardianResolutionSource,
       previousMemberStatus: previousMemberStatus ?? null,
+      messagePreview: messagePreview ?? null,
     },
     dedupeKey: `access-request:${canonicalRequest.id}`,
     onConversationCreated: (info) => {

package/src/runtime/auth/__tests__/guard-tests.test.ts

@@ -16,6 +16,10 @@ import { readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { describe, expect, test } from "bun:test";
 
+// Cross-package import: gateway duplicates the epoch constant and both must
+// stay in sync. Importing directly is more reliable than regex-extracting.
+import { CURRENT_POLICY_EPOCH as GATEWAY_POLICY_EPOCH } from "../../../../../gateway/src/auth/policy.js";
+import { CURRENT_POLICY_EPOCH } from "../policy.js";
 import { resolveScopeProfile } from "../scopes.js";
 import type { Scope, ScopeProfile } from "../types.js";
 
@@ -337,56 +341,11 @@ describe("scope profile contract", () => {
 // ---------------------------------------------------------------------------
 
 describe("CURRENT_POLICY_EPOCH sync", () => {
-  /**
-   * The policy epoch constant is duplicated in assistant, gateway, and cli
-   * packages. This test reads the exported value from each source file and
-   * asserts they are all equal.
-   */
-
-  const EPOCH_FILES = [
-    {
-      label: "assistant",
-      path: resolve(PROJECT_ROOT, "assistant/src/runtime/auth/policy.ts"),
-    },
-    {
-      label: "gateway",
-      path: resolve(PROJECT_ROOT, "gateway/src/auth/policy.ts"),
-    },
-  ];
-
-  function extractEpoch(filePath: string): number {
-    const src = readFileSync(filePath, "utf-8");
-    const match = src.match(
-      /export\s+const\s+CURRENT_POLICY_EPOCH\s*=\s*(\d+)/,
-    );
-    if (!match) {
-      throw new Error(`Could not find CURRENT_POLICY_EPOCH in ${filePath}`);
-    }
-    return parseInt(match[1], 10);
-  }
-
-  test("all non-skill packages export the same CURRENT_POLICY_EPOCH value", () => {
-    const values = EPOCH_FILES.map((f) => ({
-      label: f.label,
-      epoch: extractEpoch(f.path),
-    }));
-
-    const canonical = values[0];
-    const mismatches = values.filter((v) => v.epoch !== canonical.epoch);
-
-    if (mismatches.length > 0) {
-      const summary = values
-        .map((v) => `  - ${v.label}: ${v.epoch}`)
-        .join("\n");
-      const message = [
-        "CURRENT_POLICY_EPOCH is out of sync across packages:",
-        "",
-        summary,
-        "",
-        "All locations must have the same value.",
+  test("assistant and gateway export the same CURRENT_POLICY_EPOCH value", () => {
+    expect(
+      CURRENT_POLICY_EPOCH,
+      `CURRENT_POLICY_EPOCH mismatch: assistant=${CURRENT_POLICY_EPOCH}, gateway=${GATEWAY_POLICY_EPOCH}. ` +
         "The canonical source is assistant/src/runtime/auth/policy.ts.",
-      ].join("\n");
-      expect(mismatches, message).toEqual([]);
-    }
+    ).toBe(GATEWAY_POLICY_EPOCH);
   });
 });

package/src/runtime/auth/route-policy.ts

@@ -259,6 +259,8 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
 
   // Secrets
   { endpoint: "secrets", scopes: ["settings.write"] },
+  { endpoint: "secrets:GET", scopes: ["settings.read"] },
+  { endpoint: "secrets/read", scopes: ["settings.write"] },
 
   // Pairing (authenticated)
   { endpoint: "pairing/register", scopes: ["settings.write"] },

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

@@ -145,8 +145,11 @@ 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, handleReadyz } 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";

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>`;
             }