@vellumai/assistant 0.3.4 → 0.3.6

package/src/providers/provider-send-message.ts

@@ -0,0 +1,176 @@
+/**
+ * Helper utilities for provider callsites that should stay decoupled from
+ * provider SDK details. Includes provider resolution, timeout utilities,
+ * and response extraction helpers.
+ */
+
+import type { Provider, ProviderResponse, Message, ContentBlock, ToolUseContent } from './types.js';
+import { getFailoverProvider, listProviders, initializeProviders, resolveProviderSelection } from './registry.js';
+import { getConfig } from '../config/loader.js';
+import { getLogger } from '../util/logger.js';
+
+export interface ConfiguredProviderResult {
+  provider: Provider;
+  configuredProviderName: string;
+  selectedProviderName: string;
+  usedFallbackPrimary: boolean;
+}
+
+const providerSelectionLog = getLogger('provider-selection');
+let fallbackWarningLogged = false;
+
+/**
+ * Resolve the configured provider with full selection metadata.
+ * If providers haven't been initialized yet (e.g. non-daemon code paths),
+ * performs a one-shot `initializeProviders(getConfig())`.
+ *
+ * Uses fail-open selection: if `config.provider` is unavailable but
+ * alternates from `config.providerOrder` exist, selects the first available.
+ *
+ * Returns `null` when no providers are available at all.
+ */
+export function resolveConfiguredProvider(): ConfiguredProviderResult | null {
+  const config = getConfig();
+
+  if (listProviders().length === 0) {
+    try {
+      initializeProviders(config);
+    } catch {
+      return null;
+    }
+  }
+
+  const providerOrder = Array.isArray(config.providerOrder) ? config.providerOrder : [];
+  const selection = resolveProviderSelection(config.provider, providerOrder);
+
+  if (!selection.selectedPrimary) {
+    return null;
+  }
+
+  if (selection.usedFallbackPrimary) {
+    const level = fallbackWarningLogged ? 'debug' : 'warn';
+    providerSelectionLog[level](
+      { configured: config.provider, selected: selection.selectedPrimary },
+      'Configured provider unavailable, using fallback',
+    );
+    fallbackWarningLogged = true;
+  }
+
+  try {
+    const provider = getFailoverProvider(config.provider, providerOrder);
+    return {
+      provider,
+      configuredProviderName: config.provider,
+      selectedProviderName: selection.selectedPrimary,
+      usedFallbackPrimary: selection.usedFallbackPrimary,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the configured provider through the registry/failover path.
+ * Thin wrapper around `resolveConfiguredProvider()` for callsites
+ * that only need the Provider instance.
+ *
+ * Returns `null` when no providers are available.
+ */
+export function getConfiguredProvider(): Provider | null {
+  const result = resolveConfiguredProvider();
+  return result?.provider ?? null;
+}
+
+/**
+ * Create an AbortSignal that fires after `ms` milliseconds.
+ * Returns the signal and a cleanup function to clear the timer.
+ */
+export function createTimeout(ms: number): { signal: AbortSignal; cleanup: () => void } {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  return {
+    signal: controller.signal,
+    cleanup: () => clearTimeout(timer),
+  };
+}
+
+/**
+ * Extract the first text block's text from a ProviderResponse.
+ * Returns empty string if no text block is found.
+ */
+export function extractText(response: ProviderResponse): string {
+  const block = response.content.find((b): b is Extract<ContentBlock, { type: 'text' }> => b.type === 'text');
+  return block?.text?.trim() ?? '';
+}
+
+/**
+ * Extract all text blocks from a ProviderResponse and join them.
+ */
+export function extractAllText(response: ProviderResponse): string {
+  return response.content
+    .filter((b): b is Extract<ContentBlock, { type: 'text' }> => b.type === 'text')
+    .map((b) => b.text)
+    .join('');
+}
+
+/**
+ * Find the first tool_use block in a ProviderResponse.
+ */
+export function extractToolUse(response: ProviderResponse): ToolUseContent | undefined {
+  return response.content.find((b): b is ToolUseContent => b.type === 'tool_use');
+}
+
+/**
+ * Build a single user message in the provider Message format.
+ */
+export function userMessage(text: string): Message {
+  return { role: 'user', content: [{ type: 'text', text }] };
+}
+
+/**
+ * Build a single user message with image + text content.
+ */
+export function userMessageWithImage(
+  imageBase64: string,
+  mediaType: string,
+  text: string,
+): Message {
+  return {
+    role: 'user',
+    content: [
+      {
+        type: 'image',
+        source: {
+          type: 'base64',
+          media_type: mediaType,
+          data: imageBase64,
+        },
+      },
+      { type: 'text', text },
+    ],
+  };
+}
+
+/**
+ * Build a single user message with multiple images followed by a text block.
+ * Each image becomes its own content block; the text block comes last.
+ */
+export function userMessageWithImages(
+  images: Array<{ base64: string; mediaType: string }>,
+  text: string,
+): Message {
+  return {
+    role: 'user',
+    content: [
+      ...images.map((img) => ({
+        type: 'image' as const,
+        source: {
+          type: 'base64' as const,
+          media_type: img.mediaType,
+          data: img.base64,
+        },
+      })),
+      { type: 'text' as const, text },
+    ],
+  };
+}

package/src/providers/registry.ts

@@ -9,15 +9,7 @@ import { RetryProvider } from "./retry.js";
 import { FailoverProvider } from "./failover.js";
 import { wrapWithLogfire } from "../logfire.js";
 import { ConfigError } from "../util/errors.js";
-
-const DEFAULT_MODELS: Record<string, string> = {
-  anthropic: 'claude-opus-4-6',
-  openai: 'gpt-5.2',
-  gemini: 'gemini-3-flash',
-  ollama: 'llama3.2',
-  fireworks: 'accounts/fireworks/models/kimi-k2p5',
-  openrouter: 'x-ai/grok-4',
-};
+import { getProviderDefaultModel } from "./model-intents.js";
 
 const providers = new Map<string, Provider>();
 let cachedFailoverProvider: FailoverProvider | null = null;
@@ -37,33 +29,74 @@ export function getProvider(name: string): Provider {
   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;
+}
+
 /**
- * Build a provider that tries the primary provider first, then falls back to
- * others in the configured order. If providerOrder is empty or only contains
- * the primary, returns the primary provider directly (no wrapper overhead).
+ * 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 primary = getProvider(primaryName);
-
-  // Build the ordered list: primary first, then remaining from providerOrder
-  const orderedProviders: Provider[] = [primary];
-  const seen = new Set<string>([primaryName]);
+  const selection = resolveProviderSelection(primaryName, providerOrder);
 
-  for (const name of providerOrder) {
-    if (seen.has(name)) continue;
-    const p = providers.get(name);
-    if (p) {
-      orderedProviders.push(p);
-      seen.add(name);
-    }
+  if (!selection.selectedPrimary) {
+    throw new ConfigError(
+      `No providers available. Requested: "${primaryName}". Registered: ${listProviders().join(", ") || "none"}`,
+    );
   }
 
+  const orderedProviders: Provider[] = selection.availableProviders.map(
+    (name) => providers.get(name)!,
+  );
+
   if (orderedProviders.length === 1) {
-    return primary;
+    return orderedProviders[0];
   }
 
-  const cacheKey = `${primaryName}:${providerOrder.join(',')}`;
+  // Cache key from effective ordered providers (not raw input strings)
+  const cacheKey = selection.availableProviders.join(',');
   if (cachedFailoverProvider && cachedFailoverKey === cacheKey) {
     return cachedFailoverProvider;
   }
@@ -77,6 +110,14 @@ export function listProviders(): string[] {
   return Array.from(providers.keys());
 }
 
+/**
+ * Return the default model for a given provider name.
+ * Falls back to the Anthropic default if the provider name is unknown.
+ */
+export function getDefaultModel(providerName: string): string {
+  return getProviderDefaultModel(providerName);
+}
+
 export interface ProvidersConfig {
   apiKeys: Record<string, string>;
   provider: string;
@@ -85,16 +126,16 @@ export interface ProvidersConfig {
   timeouts?: { providerStreamTimeoutSec?: number };
 }
 
-function resolveModel(config: ProvidersConfig, providerName: keyof typeof DEFAULT_MODELS): string {
+function resolveModel(config: ProvidersConfig, providerName: string): string {
   if (config.provider === providerName) {
     // If a non-Anthropic provider is selected with the untouched global default
     // model, use a provider-appropriate fallback instead.
-    if (providerName !== 'anthropic' && config.model === DEFAULT_MODELS.anthropic) {
-      return DEFAULT_MODELS[providerName];
+    if (providerName !== 'anthropic' && config.model === getProviderDefaultModel('anthropic')) {
+      return getProviderDefaultModel(providerName);
     }
     return config.model;
   }
-  return DEFAULT_MODELS[providerName];
+  return getProviderDefaultModel(providerName);
 }
 
 export function initializeProviders(config: ProvidersConfig): void {

package/src/providers/retry.ts

@@ -1,6 +1,7 @@
 import type { Provider, ProviderResponse, SendMessageOptions, Message, ToolDefinition } from './types.js';
 import { ProviderError } from '../util/errors.js';
 import { getLogger, isDebug } from '../util/logger.js';
+import { isModelIntent, resolveModelIntent } from './model-intents.js';
 import {
   computeRetryDelay,
   isRetryableNetworkError,
@@ -18,6 +19,37 @@ function isRetryableError(error: unknown): boolean {
   return isRetryableNetworkError(error);
 }
 
+function normalizeSendMessageOptions(providerName: string, options?: SendMessageOptions): SendMessageOptions | undefined {
+  const config = options?.config;
+  if (!config) return options;
+
+  const explicitModel = typeof config.model === 'string' && config.model.trim().length > 0
+    ? config.model.trim()
+    : undefined;
+  const intent = isModelIntent(config.modelIntent) ? config.modelIntent : undefined;
+  const hasIntent = config.modelIntent !== undefined;
+
+  if (!hasIntent && explicitModel === config.model) {
+    return options;
+  }
+
+  const nextConfig: Record<string, unknown> = { ...config };
+  delete nextConfig.modelIntent;
+
+  if (explicitModel) {
+    nextConfig.model = explicitModel;
+  } else if (intent) {
+    nextConfig.model = resolveModelIntent(providerName, intent);
+  } else {
+    delete nextConfig.model;
+  }
+
+  return {
+    ...options,
+    config: nextConfig,
+  };
+}
+
 export class RetryProvider implements Provider {
   public readonly name: string;
 
@@ -42,10 +74,12 @@ export class RetryProvider implements Provider {
       }, 'Provider sendMessage start');
     }
 
+    const normalizedOptions = normalizeSendMessageOptions(this.name, options);
+
     for (let attempt = 0; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
       try {
         const start = Date.now();
-        const result = await this.inner.sendMessage(messages, tools, systemPrompt, options);
+        const result = await this.inner.sendMessage(messages, tools, systemPrompt, normalizedOptions);
         if (debug) {
           log.debug({
             provider: this.name,

package/src/providers/types.ts

@@ -70,6 +70,11 @@ export interface ToolDefinition {
   input_schema: object;
 }
 
+export type ModelIntent =
+  | 'latency-optimized'
+  | 'quality-optimized'
+  | 'vision-optimized';
+
 export interface ProviderResponse {
   content: ContentBlock[];
   model: string;
@@ -92,8 +97,14 @@ export type ProviderEvent =
   | { type: 'thinking_delta'; thinking: string }
   | { type: 'input_json_delta'; toolName: string; accumulatedJson: string };
 
+export interface SendMessageConfig {
+  model?: string;
+  modelIntent?: ModelIntent;
+  [key: string]: unknown;
+}
+
 export interface SendMessageOptions {
-  config?: object;
+  config?: SendMessageConfig;
   onEvent?: (event: ProviderEvent) => void;
   signal?: AbortSignal;
 }

package/src/runtime/approval-conversation-turn.ts

@@ -0,0 +1,97 @@
+/**
+ * Approval conversation turn engine.
+ *
+ * Processes a single turn of the conversational approval flow by delegating
+ * to a generator function (typically backed by a language model) and
+ * validating the structured result. Fails closed on any error — returning
+ * a safe keep_pending disposition — so that a broken model call never
+ * silently approves or rejects a request.
+ */
+
+// Hook point: a deterministic classifier could be inserted here as an
+// alternative to model-based inference
+
+import type {
+  ApprovalConversationContext,
+  ApprovalConversationGenerator,
+  ApprovalConversationResult,
+  ApprovalConversationDisposition,
+} from './http-types.js';
+
+const VALID_DISPOSITIONS: ReadonlySet<ApprovalConversationDisposition> = new Set([
+  'keep_pending',
+  'approve_once',
+  'approve_always',
+  'reject',
+]);
+
+/** Dispositions that represent an actual decision (not just "keep waiting"). */
+const DECISION_BEARING_DISPOSITIONS: ReadonlySet<ApprovalConversationDisposition> = new Set([
+  'approve_once',
+  'approve_always',
+  'reject',
+]);
+
+const FAIL_CLOSED_REPLY =
+  "I couldn't process that. Please reply with approve, deny, or cancel to decide on the pending request.";
+
+function failClosed(): ApprovalConversationResult {
+  return { disposition: 'keep_pending', replyText: FAIL_CLOSED_REPLY };
+}
+
+function isValidResult(value: unknown): value is ApprovalConversationResult {
+  if (!value || typeof value !== 'object') return false;
+  const obj = value as Record<string, unknown>;
+  if (typeof obj.disposition !== 'string') return false;
+  if (!VALID_DISPOSITIONS.has(obj.disposition as ApprovalConversationDisposition)) return false;
+  if (typeof obj.replyText !== 'string' || obj.replyText.trim().length === 0) return false;
+  if (obj.targetRunId !== undefined && typeof obj.targetRunId !== 'string') return false;
+  return true;
+}
+
+/**
+ * Run one turn of the approval conversation engine.
+ *
+ * Calls the provided generator, validates the result, and returns a
+ * structured decision. On ANY failure (timeout, malformed output,
+ * exception) the function returns a safe keep_pending fallback.
+ */
+export async function runApprovalConversationTurn(
+  context: ApprovalConversationContext,
+  generator: ApprovalConversationGenerator,
+): Promise<ApprovalConversationResult> {
+  let result: ApprovalConversationResult;
+
+  try {
+    result = await generator(context);
+  } catch {
+    return failClosed();
+  }
+
+  if (!isValidResult(result)) {
+    return failClosed();
+  }
+
+  // Enforce allowed-actions policy: the model must not return a disposition
+  // that the caller did not offer (keep_pending is always acceptable).
+  if (
+    result.disposition !== 'keep_pending'
+    && !context.allowedActions.includes(result.disposition)
+  ) {
+    return failClosed();
+  }
+
+  // Validate targetRunId for decision-bearing dispositions:
+  // 1. When multiple approvals are pending, targetRunId is required.
+  // 2. When targetRunId is present, it must match a known pending approval
+  //    regardless of how many approvals are pending.
+  if (DECISION_BEARING_DISPOSITIONS.has(result.disposition)) {
+    if (context.pendingApprovals.length > 1 && !result.targetRunId) return failClosed();
+    if (result.targetRunId) {
+      const validRunIds = new Set(context.pendingApprovals.map((p) => p.runId));
+      if (!validRunIds.has(result.targetRunId)) return failClosed();
+    }
+  }
+
+  return result;
+}