@vellumai/plugin-api 0.9.1-staging.1 → 0.10.0-staging.2

package/index.d.ts

@@ -808,7 +808,6 @@ declare interface ContactChannelPayload {
     type: string;
     address: string;
     isPrimary: boolean;
-    externalUserId?: string;
     status: string;
     policy: string;
     verifiedAt?: number;
@@ -1470,6 +1469,19 @@ 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;
+    forceOverrideProfile?: boolean;
+}): 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.
@@ -2172,6 +2184,7 @@ declare const LLMCallSiteEnum: z.ZodEnum<{
     meetConsentMonitor: "meetConsentMonitor";
     meetChatOpportunity: "meetChatOpportunity";
     inference: "inference";
+    advisor: "advisor";
     trustRuleSuggestion: "trustRuleSuggestion";
     homeGreeting: "homeGreeting";
     homeSuggestedPrompts: "homeSuggestedPrompts";
@@ -3021,6 +3034,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 +3316,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;
@@ -3754,6 +3934,14 @@ export declare interface ToolContext {
      * `executeSubagentSpawn` in tools/subagent/spawn.ts.
      */
     overrideProfile?: string;
+    /**
+     * The LLM call site of the turn currently executing this tool (`mainAgent`,
+     * `heartbeatAgent`, scheduled work, etc.). `subagent_spawn` reads it to
+     * default a spawned subagent's inference profile to the profile the invoking
+     * turn resolved to, so subagents match whatever agent invoked them rather
+     * than always falling back to the static `subagentSpawn` call-site default.
+     */
+    invokingCallSite?: LLMCallSite;
     /**
      * Canonical principal ID of the actor on whose behalf this tool invocation
      * is running. Sourced from `conversation.trustContext.guardianPrincipalId`.
@@ -3773,6 +3961,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
@@ -4118,6 +4312,7 @@ declare const ToolResultEventSchema: z.ZodObject<{
                 brave: "brave";
                 perplexity: "perplexity";
                 tavily: "tavily";
+                firecrawl: "firecrawl";
             }>;
             resultCount: z.ZodNumber;
             durationMs: z.ZodNumber;
@@ -4136,6 +4331,10 @@ declare const ToolResultEventSchema: z.ZodObject<{
         webFetch: z.ZodOptional<z.ZodObject<{
             url: z.ZodString;
             finalUrl: z.ZodString;
+            provider: z.ZodOptional<z.ZodEnum<{
+                default: "default";
+                firecrawl: "firecrawl";
+            }>>;
             status: z.ZodNumber;
             contentType: z.ZodOptional<z.ZodString>;
             byteCount: z.ZodNumber;
@@ -4233,11 +4432,15 @@ declare const TraceEventSchema: z.ZodObject<{
  * - `'trusted_contact'`: The sender is an active contact with a channel
  *   (not the guardian). Trusted contacts can invoke tools but require
  *   guardian approval for sensitive operations.
+ * - `'unverified_contact'`: The sender matches a contact channel whose
+ *   status is `pending` or `unverified` — known to the guardian but not yet
+ *   verified. Treated identically to `trusted_contact` for every downstream
+ *   capability/tool/approval decision; the distinction is admission-only.
  * - `'unknown'`: The sender has no contact record, no identity could be
- *   established, or the sender is an inactive/revoked contact. Unknown
+ *   established, or the sender is a blocked/revoked contact. Unknown
  *   actors are fail-closed with no escalation path.
  */
-declare type TrustClass = "guardian" | "trusted_contact" | "unknown";
+declare type TrustClass = "guardian" | "trusted_contact" | "unverified_contact" | "unknown";
 
 declare type TurnProfileAutoRoutedEvent = z.infer<typeof TurnProfileAutoRoutedEventSchema>;
 
@@ -4560,6 +4763,8 @@ declare interface VercelApiConfigResponse {
 declare interface WebFetchMetadata {
     url: string;
     finalUrl: string;
+    /** Provider that served the fetch. Defaults to the built-in fetcher. */
+    provider?: WebFetchProviderId;
     status: number;
     contentType?: string;
     byteCount: number;
@@ -4575,6 +4780,9 @@ declare interface WebFetchMetadata {
     mayRequireJavaScript?: boolean;
 }
 
+/** Provider that backed a `web_fetch` call. `default` is the built-in fetcher. */
+declare type WebFetchProviderId = "default" | "firecrawl";
+
 declare interface WebSearchMetadata {
     query: string;
     provider: WebSearchProviderId;
@@ -4585,7 +4793,7 @@ declare interface WebSearchMetadata {
     errorMessage?: string;
 }
 
-declare type WebSearchProviderId = "anthropic-native" | "brave" | "perplexity" | "tavily";
+declare type WebSearchProviderId = "anthropic-native" | "brave" | "perplexity" | "tavily" | "firecrawl";
 
 declare interface WebSearchResultItem {
     rank: number;
@@ -4612,6 +4820,13 @@ export declare interface WebSearchToolResultContent {
 declare interface WorkflowCompleted {
     type: "workflow_completed";
     runId: string;
+    /**
+     * Originating conversation id, when launched from one; lets `broadcastMessage`
+     * auto-scope + seq-stamp the event to that conversation's SSE stream. Omitted
+     * for a conversationless run (e.g. a scheduled workflow), which broadcasts
+     * unscoped for raw SSE listeners and the DB record.
+     */
+    conversationId?: string;
     status: WorkflowRunStatus;
     agentsSpawned: number;
     inputTokens: number;
@@ -4620,6 +4835,49 @@ declare interface WorkflowCompleted {
     summary?: string;
 }
 
+/**
+ * A leaf agent within a workflow run has finished. `seq` matches the
+ * corresponding `workflow_leaf_started` event.
+ */
+declare interface WorkflowLeafFinished {
+    type: "workflow_leaf_finished";
+    runId: string;
+    /**
+     * Originating conversation id; lets `broadcastMessage` auto-scope +
+     * seq-stamp the event to the conversation's SSE stream.
+     */
+    conversationId: string;
+    seq: number;
+    status: "completed" | "failed";
+    /** Leaf label, for client display. */
+    label?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    /** Short summary of the leaf's result, for client display. */
+    resultSummary?: string;
+}
+
+/**
+ * A leaf agent within a workflow run has started. `seq` orders leaves within
+ * the run for stable client-side tree placement.
+ */
+declare interface WorkflowLeafStarted {
+    type: "workflow_leaf_started";
+    runId: string;
+    /**
+     * Originating conversation id; lets `broadcastMessage` auto-scope +
+     * seq-stamp the event to the conversation's SSE stream.
+     */
+    conversationId: string;
+    seq: number;
+    /** Leaf label, for client display. */
+    label?: string;
+    /** Phase the leaf belongs to, when the workflow declares phases. */
+    phase?: string;
+    /** Short summary of the leaf's prompt, for client display. */
+    promptSummary?: string;
+}
+
 /**
  * Progress push for an in-flight workflow run. Maps the engine's
  * `onProgress` (`phase`/`log`) callback plus the current usage snapshot into a
@@ -4629,6 +4887,13 @@ declare interface WorkflowCompleted {
 declare interface WorkflowProgress {
     type: "workflow_progress";
     runId: string;
+    /**
+     * Originating conversation id, when launched from one; lets `broadcastMessage`
+     * auto-scope + seq-stamp the event to that conversation's SSE stream. Omitted
+     * for a conversationless run (e.g. a scheduled workflow), which broadcasts
+     * unscoped for raw SSE listeners and the DB record.
+     */
+    conversationId?: string;
     /** Latest phase title, when this emission came from a `phase(...)` call. */
     phase?: string;
     /** Run label (the workflow's `meta.name`), for client display. */
@@ -4656,7 +4921,27 @@ declare interface WorkflowProgress {
  */
 declare type WorkflowRunStatus = "running" | "completed" | "failed" | "aborted" | "cap_exceeded" | "interrupted";
 
-declare type _WorkflowsServerMessages = WorkflowProgress | WorkflowCompleted;
+declare type _WorkflowsServerMessages = WorkflowProgress | WorkflowCompleted | WorkflowStarted | WorkflowLeafStarted | WorkflowLeafFinished;
+
+/**
+ * A workflow run has started. Emitted once at launch, before any leaf events.
+ */
+declare interface WorkflowStarted {
+    type: "workflow_started";
+    runId: string;
+    /**
+     * Originating conversation id; lets `broadcastMessage` auto-scope +
+     * seq-stamp the event to the conversation's SSE stream.
+     */
+    conversationId: string;
+    /**
+     * Tool-use id of the `skill_execute` block that launched this run, for
+     * anchoring the inline workflow card to the exact spawn tool call.
+     */
+    toolUseId?: string;
+    /** Run label (the workflow's `meta.name`), for client display. */
+    label?: string;
+}
 
 declare interface WorkItemApprovePermissionsResponse {
     type: "work_item_approve_permissions_response";

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.1-staging.1",
+  "version": "0.10.0-staging.2",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",