@vellumai/plugin-api 0.9.0-dev.202606171417.d2192ab → 0.9.0-dev.202606171903.06eea08

package/index.d.ts

@@ -1470,6 +1470,18 @@ declare const GenerationHandoffEventSchema: z.ZodObject<{
     attachmentWarnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 
+/**
+ * Resolve the configured provider through the registry.
+ * Thin wrapper around `resolveConfiguredProvider()` for callsites
+ * that only need the Provider instance.
+ *
+ * `callSite` is required — see `resolveConfiguredProvider`. Returns `null`
+ * when no providers are available.
+ */
+export declare function getConfiguredProvider(callSite: LLMCallSite, opts?: {
+    overrideProfile?: string;
+}): Promise<Provider | null>;
+
 /**
  * List the workspace inference profiles a plugin can route to, in the order the
  * `/model` picker presents them (`llm.profileOrder` first, then the rest
@@ -2124,7 +2136,7 @@ declare interface ListSurfaceData {
     selectionMode: "single" | "multiple" | "none";
 }
 
-declare type LLMCallSite = z.infer<typeof LLMCallSiteEnum>;
+export declare type LLMCallSite = z.infer<typeof LLMCallSiteEnum>;
 
 /**
  * The complete set of LLM call-site identifiers the assistant emits.
@@ -3021,6 +3033,83 @@ declare interface ProcessEntry extends BaseSubscriberEntry {
     type: "process";
 }
 
+export declare interface Provider {
+    name: string;
+    /**
+     * Provider key used by the local token estimator to select model-family
+     * specific rules (e.g. Anthropic's `width * height / 750` image sizing).
+     * Wrapper providers that route to another provider's API — e.g. OpenRouter
+     * calling Anthropic's Messages endpoint for `anthropic/*` models — override
+     * this so the estimator matches what the upstream API will actually charge.
+     * Falls back to `name` when unset.
+     */
+    tokenEstimationProvider?: string;
+    sendMessage(messages: Message[], options?: SendMessageOptions): Promise<ProviderResponse>;
+}
+
+export declare type ProviderEvent = {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "thinking_delta";
+    thinking: string;
+} | {
+    type: "tool_use_preview_start";
+    toolUseId: string;
+    toolName: string;
+} | {
+    type: "input_json_delta";
+    toolName: string;
+    toolUseId: string;
+    accumulatedJson: string;
+} | {
+    type: "server_tool_start";
+    name: string;
+    toolUseId: string;
+    input: Record<string, unknown>;
+} | {
+    type: "server_tool_complete";
+    toolUseId: string;
+    isError: boolean;
+    content?: unknown[];
+    /**
+     * Finalized input for the server tool call (e.g. the actual query).
+     * Anthropic streams `server_tool_use` block input via `input_json_delta`
+     * events, so consumers reading the input at `server_tool_start` see `{}`.
+     * The provider accumulates the JSON and surfaces it here once the block
+     * stops, so downstream handlers can build accurate activity metadata.
+     */
+    resolvedInput?: Record<string, unknown>;
+    /**
+     * Provider-specific error code when `isError` is true (e.g. Anthropic's
+     * `max_uses_exceeded`, `query_too_long`). Surfaced so user-facing
+     * messages can be specific instead of a generic "Search failed".
+     */
+    errorCode?: string;
+    /** Optional human-readable error message from the provider. */
+    errorMessage?: string;
+};
+
+export declare interface ProviderResponse {
+    content: ContentBlock[];
+    model: string;
+    /** Provider that actually produced this response, which may differ from a wrapper provider name. */
+    actualProvider?: string;
+    usage: {
+        /** Total input tokens (input_tokens + cache_creation + cache_read). */
+        inputTokens: number;
+        outputTokens: number;
+        cacheCreationInputTokens?: number;
+        cacheReadInputTokens?: number;
+        reasoningTokens?: number;
+    };
+    stopReason: string;
+    /** Raw JSON request body sent to the provider (for diagnostics logging). */
+    rawRequest?: unknown;
+    /** Raw JSON response body received from the provider (for diagnostics logging). */
+    rawResponse?: unknown;
+}
+
 /** Callback for proxy policy decisions requiring user confirmation. Returns true if approved. */
 declare type ProxyApprovalCallback = (request: ProxyApprovalRequest) => Promise<boolean>;
 
@@ -3226,6 +3315,96 @@ declare const SecretRequestEventSchema: z.ZodObject<{
     allowOneTimeSend: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 
+export declare interface SendMessageConfig {
+    model?: string;
+    /**
+     * LLM call-site identifier. `RetryProvider` resolves
+     * provider/model/maxTokens/effort/speed/verbosity/temperature/thinking/
+     * contextWindow via `resolveCallSiteConfig(callSite, config.llm)`, falling
+     * back to `llm.default` when no callSite-specific entry is present.
+     */
+    callSite?: LLMCallSite;
+    /**
+     * Optional ad-hoc profile override applied per request. When set, the
+     * resolver layers `llm.profiles[overrideProfile]` between the workspace's
+     * `activeProfile` and the call-site's named profile (see
+     * `resolveCallSiteConfig`). Used by per-conversation pinned profiles to
+     * override the workspace default for a single send. Missing profile names
+     * silently fall through.
+     */
+    overrideProfile?: string;
+    /**
+     * When true, the resolver floats `overrideProfile` above the call-site
+     * layers (named site profile + call-site override) for non-main-agent call
+     * sites — see `ResolveCallSiteOpts.forceOverrideProfile`. Used by callers
+     * that must run a background call site under a specific conversation's
+     * inference profile (e.g. fork-based memory retrospectives). A
+     * resolution/routing-time concern only; stripped before any provider wire
+     * request.
+     */
+    forceOverrideProfile?: boolean;
+    /**
+     * Per-conversation seed for deterministic `mix`-profile expansion. The agent
+     * loop sets this to the conversation id so every resolver call this send
+     * triggers — provider/transport selection, wire-param normalization, usage
+     * attribution — picks the same mix constituent, stable across the
+     * conversation's turns and retries. A resolution/routing-time concern only;
+     * stripped before any provider wire request.
+     */
+    selectionSeed?: string;
+    /**
+     * Internal per-request HTTP headers for managed-proxy usage attribution.
+     * Provider clients may pass these through SDK request options only when the
+     * transport is Vellum-managed, and must never include this object in provider
+     * JSON request bodies.
+     */
+    usageAttributionHeaders?: Record<string, string>;
+    /**
+     * Controls local usage-ledger writes for attributed provider calls.
+     * Defaults to `auto`; conversation paths that aggregate usage separately
+     * set `manual` to avoid double-counting.
+     */
+    usageTracking?: "auto" | "manual";
+    effort?: "none" | "low" | "medium" | "high" | "xhigh" | "max";
+    speed?: "standard" | "fast";
+    verbosity?: "low" | "medium" | "high";
+    /**
+     * Wire-format `logit_bias` map (`{ "<tokenId>": bias }`). Set by
+     * `RetryProvider` from a profile's `logitBias` preset and forwarded only on
+     * the OpenAI-compatible (Fireworks) path; other providers ignore it.
+     */
+    logit_bias?: Record<string, number>;
+    /**
+     * When true, the most recent user message's content varies across
+     * otherwise-identical turns (e.g. a per-turn memory block was injected into
+     * it). The provider places the primary long-TTL cache breakpoint on the most
+     * recent *stable* user message instead of the volatile latest one, so the
+     * cached prefix stays reusable across turns. Default false — existing
+     * behavior.
+     */
+    mutableLatestUserMessage?: boolean;
+    /**
+     * When true, the provider sends no prompt-cache breakpoints at all (and
+     * strips any block-level `cache_control` markers callers stamped on
+     * messages). For one-shot call sites whose prompts are unique per call or
+     * whose call cadence exceeds the cache TTL, every breakpoint is a paid
+     * cache write that will never be read — opting out saves the write
+     * premium. Resolved per call site via `resolveCallSiteConfig` (see
+     * `disableCache` in the LLM config schema); a per-call explicit value
+     * wins. Default false — existing behavior.
+     */
+    disableCache?: boolean;
+    [key: string]: unknown;
+}
+
+export declare interface SendMessageOptions {
+    tools?: ToolDefinition_2[];
+    systemPrompt?: string;
+    config?: SendMessageConfig;
+    onEvent?: (event: ProviderEvent) => void;
+    signal?: AbortSignal;
+}
+
 declare interface SensitiveOutputBinding {
     kind: SensitiveOutputKind;
     placeholder: string;
@@ -3773,6 +3952,12 @@ export declare interface ToolContext {
  */
 export declare type ToolDefinition = z.infer<typeof ToolDefinitionSchema>;
 
+declare interface ToolDefinition_2 {
+    name: string;
+    description: string;
+    input_schema: object;
+}
+
 /**
  * Schema describing the shape of a {@link ToolDefinition}. All fields are
  * optional — loaders fill documented defaults for omitted fields via

package/index.js

@@ -3,5 +3,6 @@ const api = globalThis[Symbol.for("vellum.plugin-api")] ?? {};
 export const HOOKS = api.HOOKS;
 export const RiskLevel = api.RiskLevel;
 export const assistantEventHub = api.assistantEventHub;
+export const getConfiguredProvider = api.getConfiguredProvider;
 export const getModelProfiles = api.getModelProfiles;
 export const getSecureKeyAsync = api.getSecureKeyAsync;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.9.0-dev.202606171417.d2192ab",
+  "version": "0.9.0-dev.202606171903.06eea08",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",