@vellumai/plugin-api 0.10.10-dev.202607201843.29886ee → 0.10.10-dev.202607201935.4faac34

package/index.d.ts

@@ -1936,6 +1936,8 @@ declare interface ConfigChanged {
     type: "config_changed";
 }
 
+declare type ConfiguredProviderOptions = Pick<ResolveCallSiteOpts, "overrideProfile" | "forceOverrideProfile" | "selectionSeed">;
+
 declare type ConfirmationRequestEvent = z.infer<typeof ConfirmationRequestEventSchema>;
 
 declare const ConfirmationRequestEventSchema: z.ZodObject<{
@@ -2804,10 +2806,7 @@ export declare function getAssistantName(): string | null;
  * `callSite` is required — see `resolveConfiguredProvider`. Returns `null`
  * when no providers are available.
  */
-export declare function getConfiguredProvider(callSite: LLMCallSite, opts?: {
-    overrideProfile?: string;
-    forceOverrideProfile?: boolean;
-}): Promise<Provider | null>;
+export declare function getConfiguredProvider(callSite: LLMCallSite, opts?: ConfiguredProviderOptions): Promise<Provider | null>;
 
 /** Look up a conversation row by id. */
 export declare function getConversation(id: string): Promise<ConversationRow | null>;
@@ -4877,6 +4876,99 @@ declare const RelationshipStateUpdatedEventSchema: z.ZodObject<{
     updatedAt: z.ZodString;
 }, z.core.$strip>;
 
+declare type ResolutionFallbackReason = "missing" | "disabled" | "incomplete";
+
+/**
+ * Resolves a fully-specified `LLMConfigBase` for a given call site.
+ *
+ * Selection is a single-winner chain (see `selectWinningProfile`): the
+ * highest-precedence rung that names a usable, complete profile wins, and the
+ * resolved config is composed as code-owned schema defaults + the winning
+ * profile's fragment + the call site's own tuning tweak. No profile ever
+ * contributes a field to another profile — `deepMerge` here only lets nested
+ * tweaks (e.g. `thinking.enabled`) combine leaf-wise with the winner rather
+ * than wholesale-replacing sibling fields.
+ *
+ * Precedence of the selection chain (high → low):
+ *   1. `opts.overrideProfile` (per-turn / per-conversation pin)
+ *   2. `llm.activeProfile` — `mainAgent` only, since it IS that call site's
+ *      user-facing chat-model selection
+ *   3. `llm.callSites[callSite].profile` (the call site's named profile)
+ *   4. `CALL_SITE_DEFAULTS[callSite].profile` intent resolved through
+ *      `llm.defaultProvider`
+ *   5. balanced intent through `llm.defaultProvider` — the code-owned anchor
+ *      for profileless call sites, or when nothing above is usable
+ *
+ * A winner must carry its own `provider` AND `model`: the base layer's schema
+ * default identity never stands in for a selected profile. The anchor is
+ * code-owned and resolved through `llm.defaultProvider`, never through
+ * user-mutable state.
+ *
+ * `temperature`/`top_p` come only from the winner (or an explicit call-site
+ * tweak); `logitBias` only ever from the winner. These are provider-coupled, so
+ * a shadowed profile can never leak its sampling onto a different provider.
+ *
+ * `opts.forceOverrideProfile` is a no-op here: the override profile already
+ * sits at the top of the chain for every call site.
+ *
+ * Profile names are resolved against the effective profile catalog
+ * (code-defined defaults + workspace `llm.profiles`; see `getEffectiveProfile`).
+ * A "mix" profile is expanded to one of its arms by a seeded weighted pick (see
+ * `resolveProfileFragment` and `opts.selectionSeed`), uniformly wherever a name
+ * is dereferenced. Missing references silently fall through (no throw) so the
+ * resolver stays pure; schema validation catches unknown static references at
+ * config-load time.
+ *
+ * Nested objects (`thinking`, `contextWindow`, and
+ * `contextWindow.overflowRecovery`) are deep-merged so partial tweaks at any
+ * nesting level merge into — rather than replace — the corresponding base
+ * value.
+ *
+ * Pure & synchronous: no I/O, no async work. (Random selection only occurs for
+ * mix profiles when no `selectionSeed` is supplied; with a seed the pick is
+ * deterministic.)
+ */
+declare interface ResolveCallSiteOpts {
+    overrideProfile?: string;
+    /**
+     * Float `overrideProfile` above the call-site layers for non-main-agent call
+     * sites. Retained for API compatibility; under single-winner selection the
+     * override already sits at the top of the chain, so this is effectively a
+     * no-op. Inert when `overrideProfile` is absent or references a missing
+     * profile.
+     */
+    forceOverrideProfile?: boolean;
+    /**
+     * Per-conversation seed for expanding `mix` profiles. The chosen constituent
+     * is a deterministic function of `selectionSeed` + the mix profile's own
+     * name, so every `resolveCallSiteConfig` call for the same conversation picks
+     * the SAME arm (stable across turns, retries, and restarts). Pass the
+     * conversation id. When absent, the resolver falls back to a fresh random
+     * pick per call — acceptable only for one-shot/background call sites that
+     * resolve config exactly once per invocation.
+     */
+    selectionSeed?: string;
+    /**
+     * Invoked once for each mix profile the resolver expands, reporting which
+     * constituent was chosen. Used by A/B-eval recording (usage attribution).
+     */
+    onMixSelected?: (info: {
+        mixProfile: string;
+        chosenProfile: string;
+    }) => void;
+    /**
+     * Invoked once per chain rung that named a profile the resolver could not
+     * use, before resolution continues to the next rung. Fallback is silent to
+     * the call but must be visible in logs — callers on user-facing paths should
+     * log at warn.
+     */
+    onResolutionFallback?: (info: {
+        callSite: LLMCallSite;
+        requested: string;
+        reason: ResolutionFallbackReason;
+    }) => void;
+}
+
 /**
  * Resolve a credential reference to its plaintext value.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.10.10-dev.202607201843.29886ee",
+  "version": "0.10.10-dev.202607201935.4faac34",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",