@vellumai/plugin-api 0.9.0 → 0.10.0-staging.1

package/index.d.ts

@@ -524,8 +524,7 @@ declare type _BookmarksServerMessages = BookmarkCreated | BookmarkDeleted;
 
 /**
  * Wire-shape representation of a bookmark, joined with the bookmarked
- * message and its parent conversation. Mirrors
- * `clients/shared/Network/BookmarkSummary.swift` — dates are emitted as
+ * message and its parent conversation. Dates are emitted as
  * unix-millisecond integers, and the message preview is capped to keep
  * the list payload bounded.
  */
@@ -809,7 +808,6 @@ declare interface ContactChannelPayload {
     type: string;
     address: string;
     isPrimary: boolean;
-    externalUserId?: string;
     status: string;
     policy: string;
     verifiedAt?: number;
@@ -920,9 +918,9 @@ declare interface ContextCompacted {
      * - `summaryCharCount`: length of the produced summary text.
      * - `summaryHeaderCount`: number of `## ` section headers in the summary.
      * - `summaryHadMemoryEcho`: `true` if the summary contains any runtime
-     *   injection tag (e.g. `<memory`, `<turn_context>`, `<workspace>`).
-     *   Should always be `false` — `true` indicates the compaction strip
-     *   logic failed to remove an injected block from the summarizer input.
+     *   injection tag (e.g. `<memory`, `<turn_context>`, `<workspace>`). The
+     *   durable summary should be clean prose, so `true` flags an echoed or
+     *   invented tag worth investigating.
      */
     summaryCharCount?: number;
     summaryHeaderCount?: number;
@@ -1471,6 +1469,32 @@ 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
+ * alphabetically). Disabled profiles are included and flagged via
+ * {@link ModelProfileInfo.isDisabled}; weighted "mix" profiles are included and
+ * flagged via {@link ModelProfileInfo.isMix}, since a mix is itself a valid
+ * routing target (it resolves to one constituent per conversation).
+ *
+ * Reads the live in-memory config, so the result reflects the current profile
+ * set each time it is called.
+ */
+export declare function getModelProfiles(): ModelProfileInfo[];
+
 /**
  * Retrieve a secret from secure storage. Convenience wrapper over
  * `getSecureKeyResultAsync` that returns only the value.
@@ -1729,7 +1753,7 @@ export declare const HOOKS: {
     readonly SHUTDOWN: "shutdown";
     /** Fires once per user turn, immediately before the agent loop receives `runMessages`. */
     readonly USER_PROMPT_SUBMIT: "user-prompt-submit";
-    /** Fires immediately before each provider call. A hook may edit the outbound request (e.g. the system prompt) and opt the turn into deferred output streaming. */
+    /** Fires immediately before each provider call. A hook may edit the outbound request (e.g. the system prompt), route the call to a different inference profile, and opt the turn into deferred output streaming. */
     readonly PRE_MODEL_CALL: "pre-model-call";
     /** Fires once per tool result, after the tool returns and before the result is sent to the provider. */
     readonly POST_TOOL_USE: "post-tool-use";
@@ -2112,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.
@@ -2160,6 +2184,7 @@ declare const LLMCallSiteEnum: z.ZodEnum<{
     meetConsentMonitor: "meetConsentMonitor";
     meetChatOpportunity: "meetChatOpportunity";
     inference: "inference";
+    advisor: "advisor";
     trustRuleSuggestion: "trustRuleSuggestion";
     homeGreeting: "homeGreeting";
     homeSuggestedPrompts: "homeSuggestedPrompts";
@@ -2453,6 +2478,33 @@ declare interface ModelInfo {
     }>;
 }
 
+/**
+ * A workspace inference profile a plugin can route to. Returned by
+ * {@link getModelProfiles}; {@link key} is the value a `pre-model-call` hook
+ * assigns to `PreModelCallContext.modelProfile` to route a call. A model router
+ * reads this list (typically at `init`) to learn which profiles exist before
+ * mapping a classified message onto one.
+ */
+export declare interface ModelProfileInfo {
+    /** Profile key in `llm.profiles`; assignable to `PreModelCallContext.modelProfile`. */
+    readonly key: string;
+    /** Human-readable label, falling back to {@link key} when none is set. */
+    readonly label: string;
+    /** Author-supplied description, or `null` when none is set. */
+    readonly description: string | null;
+    /** Whether this is the workspace's active profile. */
+    readonly isActive: boolean;
+    /** Whether the profile is disabled; routing to it is rejected by the resolver. */
+    readonly isDisabled: boolean;
+    /**
+     * Whether this is a weighted "mix" profile — an A/B blend that resolves to one
+     * of its constituent profiles per conversation via a seeded weighted pick.
+     * Routing to its {@link key} is valid; it directs the call into the blend
+     * rather than at a single fixed model.
+     */
+    readonly isMix: boolean;
+}
+
 declare type NavigateSettingsEvent = z.infer<typeof NavigateSettingsEventSchema>;
 
 declare const NavigateSettingsEventSchema: z.ZodObject<{
@@ -2929,8 +2981,9 @@ export declare interface PostToolUseContext {
  * and compaction work can share a conversation), hooks MUST self-gate on
  * {@link callSite} / {@link conversationId} before acting.
  *
- * A hook may edit the outbound request by replacing {@link systemPrompt}, and may
- * opt this turn into deferred output streaming via {@link deferAssistantOutput}.
+ * A hook may edit the outbound request by replacing {@link systemPrompt}, route
+ * the call to a different inference profile via {@link modelProfile}, and opt
+ * this turn into deferred output streaming via {@link deferAssistantOutput}.
  * Mutate the context in place or return a new one; throwing is contained by the
  * loop (the call proceeds with the original request).
  */
@@ -2947,6 +3000,24 @@ export declare interface PreModelCallContext {
      * append a section); the loop sends the resulting value.
      */
     systemPrompt: string | null;
+    /**
+     * Inference profile to route THIS provider call to, named by its key in the
+     * workspace `llm.profiles`. Seeded with the call's already-resolved override
+     * profile, or `null` when none applies. A hook may replace it to select a
+     * different profile per call — the lever a model router uses to map a
+     * classified message onto a profile (model + provider connection + sampling
+     * settings). For the user-facing `mainAgent` call the resolver layers the
+     * named profile at the top of precedence (above the workspace active
+     * profile), so the hook's choice wins; a key with no matching profile falls
+     * through unchanged (no throw). Honored only when {@link callSite} is set.
+     * Set to `null` to apply no override.
+     *
+     * Context-window sizing and overflow recovery for this call are computed from
+     * the profile resolved before the hook runs. Routing a near-budget
+     * conversation to a profile with a smaller context window relies on the loop's
+     * overflow recovery (compact and retry) rather than proactive compaction.
+     */
+    modelProfile: string | null;
     /**
      * Seeded `false`. When a hook sets it `true`, the loop suppresses this turn's
      * live assistant `text_delta` stream; a `post-model-call` hook is then
@@ -2963,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>;
 
@@ -3168,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;
@@ -3715,6 +3953,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
@@ -4060,6 +4304,7 @@ declare const ToolResultEventSchema: z.ZodObject<{
                 brave: "brave";
                 perplexity: "perplexity";
                 tavily: "tavily";
+                firecrawl: "firecrawl";
             }>;
             resultCount: z.ZodNumber;
             durationMs: z.ZodNumber;
@@ -4078,6 +4323,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;
@@ -4175,11 +4424,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>;
 
@@ -4502,6 +4755,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;
@@ -4517,6 +4772,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;
@@ -4527,7 +4785,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;
@@ -4554,6 +4812,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;
@@ -4562,6 +4827,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
@@ -4571,6 +4879,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. */
@@ -4598,7 +4913,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,4 +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",
+  "version": "0.10.0-staging.1",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",