@vellumai/plugin-api 0.9.0 → 0.10.0-dev.202606192226.8ed8a6a

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/index.d.ts +369 -14
  2. package/index.js +2 -0
  3. package/package.json +1 -1
package/index.d.ts CHANGED
@@ -524,8 +524,7 @@ declare type _BookmarksServerMessages = BookmarkCreated | BookmarkDeleted;
524
524
 
525
525
  /**
526
526
  * Wire-shape representation of a bookmark, joined with the bookmarked
527
- * message and its parent conversation. Mirrors
528
- * `clients/shared/Network/BookmarkSummary.swift` — dates are emitted as
527
+ * message and its parent conversation. Dates are emitted as
529
528
  * unix-millisecond integers, and the message preview is capped to keep
530
529
  * the list payload bounded.
531
530
  */
@@ -809,7 +808,6 @@ declare interface ContactChannelPayload {
809
808
  type: string;
810
809
  address: string;
811
810
  isPrimary: boolean;
812
- externalUserId?: string;
813
811
  status: string;
814
812
  policy: string;
815
813
  verifiedAt?: number;
@@ -920,9 +918,9 @@ declare interface ContextCompacted {
920
918
  * - `summaryCharCount`: length of the produced summary text.
921
919
  * - `summaryHeaderCount`: number of `## ` section headers in the summary.
922
920
  * - `summaryHadMemoryEcho`: `true` if the summary contains any runtime
923
- * injection tag (e.g. `<memory`, `<turn_context>`, `<workspace>`).
924
- * Should always be `false` `true` indicates the compaction strip
925
- * logic failed to remove an injected block from the summarizer input.
921
+ * injection tag (e.g. `<memory`, `<turn_context>`, `<workspace>`). The
922
+ * durable summary should be clean prose, so `true` flags an echoed or
923
+ * invented tag worth investigating.
926
924
  */
927
925
  summaryCharCount?: number;
928
926
  summaryHeaderCount?: number;
@@ -1471,6 +1469,32 @@ declare const GenerationHandoffEventSchema: z.ZodObject<{
1471
1469
  attachmentWarnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
1472
1470
  }, z.core.$strip>;
1473
1471
 
1472
+ /**
1473
+ * Resolve the configured provider through the registry.
1474
+ * Thin wrapper around `resolveConfiguredProvider()` for callsites
1475
+ * that only need the Provider instance.
1476
+ *
1477
+ * `callSite` is required — see `resolveConfiguredProvider`. Returns `null`
1478
+ * when no providers are available.
1479
+ */
1480
+ export declare function getConfiguredProvider(callSite: LLMCallSite, opts?: {
1481
+ overrideProfile?: string;
1482
+ forceOverrideProfile?: boolean;
1483
+ }): Promise<Provider | null>;
1484
+
1485
+ /**
1486
+ * List the workspace inference profiles a plugin can route to, in the order the
1487
+ * `/model` picker presents them (`llm.profileOrder` first, then the rest
1488
+ * alphabetically). Disabled profiles are included and flagged via
1489
+ * {@link ModelProfileInfo.isDisabled}; weighted "mix" profiles are included and
1490
+ * flagged via {@link ModelProfileInfo.isMix}, since a mix is itself a valid
1491
+ * routing target (it resolves to one constituent per conversation).
1492
+ *
1493
+ * Reads the live in-memory config, so the result reflects the current profile
1494
+ * set each time it is called.
1495
+ */
1496
+ export declare function getModelProfiles(): ModelProfileInfo[];
1497
+
1474
1498
  /**
1475
1499
  * Retrieve a secret from secure storage. Convenience wrapper over
1476
1500
  * `getSecureKeyResultAsync` that returns only the value.
@@ -1729,7 +1753,7 @@ export declare const HOOKS: {
1729
1753
  readonly SHUTDOWN: "shutdown";
1730
1754
  /** Fires once per user turn, immediately before the agent loop receives `runMessages`. */
1731
1755
  readonly USER_PROMPT_SUBMIT: "user-prompt-submit";
1732
- /** 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. */
1756
+ /** 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. */
1733
1757
  readonly PRE_MODEL_CALL: "pre-model-call";
1734
1758
  /** Fires once per tool result, after the tool returns and before the result is sent to the provider. */
1735
1759
  readonly POST_TOOL_USE: "post-tool-use";
@@ -2112,7 +2136,7 @@ declare interface ListSurfaceData {
2112
2136
  selectionMode: "single" | "multiple" | "none";
2113
2137
  }
2114
2138
 
2115
- declare type LLMCallSite = z.infer<typeof LLMCallSiteEnum>;
2139
+ export declare type LLMCallSite = z.infer<typeof LLMCallSiteEnum>;
2116
2140
 
2117
2141
  /**
2118
2142
  * The complete set of LLM call-site identifiers the assistant emits.
@@ -2160,6 +2184,7 @@ declare const LLMCallSiteEnum: z.ZodEnum<{
2160
2184
  meetConsentMonitor: "meetConsentMonitor";
2161
2185
  meetChatOpportunity: "meetChatOpportunity";
2162
2186
  inference: "inference";
2187
+ advisor: "advisor";
2163
2188
  trustRuleSuggestion: "trustRuleSuggestion";
2164
2189
  homeGreeting: "homeGreeting";
2165
2190
  homeSuggestedPrompts: "homeSuggestedPrompts";
@@ -2453,6 +2478,33 @@ declare interface ModelInfo {
2453
2478
  }>;
2454
2479
  }
2455
2480
 
2481
+ /**
2482
+ * A workspace inference profile a plugin can route to. Returned by
2483
+ * {@link getModelProfiles}; {@link key} is the value a `pre-model-call` hook
2484
+ * assigns to `PreModelCallContext.modelProfile` to route a call. A model router
2485
+ * reads this list (typically at `init`) to learn which profiles exist before
2486
+ * mapping a classified message onto one.
2487
+ */
2488
+ export declare interface ModelProfileInfo {
2489
+ /** Profile key in `llm.profiles`; assignable to `PreModelCallContext.modelProfile`. */
2490
+ readonly key: string;
2491
+ /** Human-readable label, falling back to {@link key} when none is set. */
2492
+ readonly label: string;
2493
+ /** Author-supplied description, or `null` when none is set. */
2494
+ readonly description: string | null;
2495
+ /** Whether this is the workspace's active profile. */
2496
+ readonly isActive: boolean;
2497
+ /** Whether the profile is disabled; routing to it is rejected by the resolver. */
2498
+ readonly isDisabled: boolean;
2499
+ /**
2500
+ * Whether this is a weighted "mix" profile — an A/B blend that resolves to one
2501
+ * of its constituent profiles per conversation via a seeded weighted pick.
2502
+ * Routing to its {@link key} is valid; it directs the call into the blend
2503
+ * rather than at a single fixed model.
2504
+ */
2505
+ readonly isMix: boolean;
2506
+ }
2507
+
2456
2508
  declare type NavigateSettingsEvent = z.infer<typeof NavigateSettingsEventSchema>;
2457
2509
 
2458
2510
  declare const NavigateSettingsEventSchema: z.ZodObject<{
@@ -2929,8 +2981,9 @@ export declare interface PostToolUseContext {
2929
2981
  * and compaction work can share a conversation), hooks MUST self-gate on
2930
2982
  * {@link callSite} / {@link conversationId} before acting.
2931
2983
  *
2932
- * A hook may edit the outbound request by replacing {@link systemPrompt}, and may
2933
- * opt this turn into deferred output streaming via {@link deferAssistantOutput}.
2984
+ * A hook may edit the outbound request by replacing {@link systemPrompt}, route
2985
+ * the call to a different inference profile via {@link modelProfile}, and opt
2986
+ * this turn into deferred output streaming via {@link deferAssistantOutput}.
2934
2987
  * Mutate the context in place or return a new one; throwing is contained by the
2935
2988
  * loop (the call proceeds with the original request).
2936
2989
  */
@@ -2947,6 +3000,24 @@ export declare interface PreModelCallContext {
2947
3000
  * append a section); the loop sends the resulting value.
2948
3001
  */
2949
3002
  systemPrompt: string | null;
3003
+ /**
3004
+ * Inference profile to route THIS provider call to, named by its key in the
3005
+ * workspace `llm.profiles`. Seeded with the call's already-resolved override
3006
+ * profile, or `null` when none applies. A hook may replace it to select a
3007
+ * different profile per call — the lever a model router uses to map a
3008
+ * classified message onto a profile (model + provider connection + sampling
3009
+ * settings). For the user-facing `mainAgent` call the resolver layers the
3010
+ * named profile at the top of precedence (above the workspace active
3011
+ * profile), so the hook's choice wins; a key with no matching profile falls
3012
+ * through unchanged (no throw). Honored only when {@link callSite} is set.
3013
+ * Set to `null` to apply no override.
3014
+ *
3015
+ * Context-window sizing and overflow recovery for this call are computed from
3016
+ * the profile resolved before the hook runs. Routing a near-budget
3017
+ * conversation to a profile with a smaller context window relies on the loop's
3018
+ * overflow recovery (compact and retry) rather than proactive compaction.
3019
+ */
3020
+ modelProfile: string | null;
2950
3021
  /**
2951
3022
  * Seeded `false`. When a hook sets it `true`, the loop suppresses this turn's
2952
3023
  * live assistant `text_delta` stream; a `post-model-call` hook is then
@@ -2963,6 +3034,95 @@ declare interface ProcessEntry extends BaseSubscriberEntry {
2963
3034
  type: "process";
2964
3035
  }
2965
3036
 
3037
+ export declare interface Provider {
3038
+ name: string;
3039
+ /**
3040
+ * Provider key used by the local token estimator to select model-family
3041
+ * specific rules (e.g. Anthropic's `width * height / 750` image sizing).
3042
+ * Wrapper providers that route to another provider's API — e.g. OpenRouter
3043
+ * calling Anthropic's Messages endpoint for `anthropic/*` models — override
3044
+ * this so the estimator matches what the upstream API will actually charge.
3045
+ * Falls back to `name` when unset.
3046
+ */
3047
+ tokenEstimationProvider?: string;
3048
+ sendMessage(messages: Message[], options?: SendMessageOptions): Promise<ProviderResponse>;
3049
+ /**
3050
+ * Exact prompt-token count from the provider's own tokenizer, for the
3051
+ * `messages` + `systemPrompt` + `tools` composition the next call would
3052
+ * send. Optional: providers without a token-counting endpoint omit it, and
3053
+ * callers must fall back to the local estimator (`estimatePromptTokens`).
3054
+ *
3055
+ * This runs a dedicated counting request (no inference), so it carries a
3056
+ * network round-trip and the provider's own rate limit — use it for
3057
+ * user-initiated, occasional actions (e.g. `/compact`), never on the
3058
+ * per-turn hot path.
3059
+ */
3060
+ countInputTokens?(messages: Message[], systemPrompt: string, tools?: ToolDefinition_2[]): Promise<number>;
3061
+ }
3062
+
3063
+ export declare type ProviderEvent = {
3064
+ type: "text_delta";
3065
+ text: string;
3066
+ } | {
3067
+ type: "thinking_delta";
3068
+ thinking: string;
3069
+ } | {
3070
+ type: "tool_use_preview_start";
3071
+ toolUseId: string;
3072
+ toolName: string;
3073
+ } | {
3074
+ type: "input_json_delta";
3075
+ toolName: string;
3076
+ toolUseId: string;
3077
+ accumulatedJson: string;
3078
+ } | {
3079
+ type: "server_tool_start";
3080
+ name: string;
3081
+ toolUseId: string;
3082
+ input: Record<string, unknown>;
3083
+ } | {
3084
+ type: "server_tool_complete";
3085
+ toolUseId: string;
3086
+ isError: boolean;
3087
+ content?: unknown[];
3088
+ /**
3089
+ * Finalized input for the server tool call (e.g. the actual query).
3090
+ * Anthropic streams `server_tool_use` block input via `input_json_delta`
3091
+ * events, so consumers reading the input at `server_tool_start` see `{}`.
3092
+ * The provider accumulates the JSON and surfaces it here once the block
3093
+ * stops, so downstream handlers can build accurate activity metadata.
3094
+ */
3095
+ resolvedInput?: Record<string, unknown>;
3096
+ /**
3097
+ * Provider-specific error code when `isError` is true (e.g. Anthropic's
3098
+ * `max_uses_exceeded`, `query_too_long`). Surfaced so user-facing
3099
+ * messages can be specific instead of a generic "Search failed".
3100
+ */
3101
+ errorCode?: string;
3102
+ /** Optional human-readable error message from the provider. */
3103
+ errorMessage?: string;
3104
+ };
3105
+
3106
+ export declare interface ProviderResponse {
3107
+ content: ContentBlock[];
3108
+ model: string;
3109
+ /** Provider that actually produced this response, which may differ from a wrapper provider name. */
3110
+ actualProvider?: string;
3111
+ usage: {
3112
+ /** Total input tokens (input_tokens + cache_creation + cache_read). */
3113
+ inputTokens: number;
3114
+ outputTokens: number;
3115
+ cacheCreationInputTokens?: number;
3116
+ cacheReadInputTokens?: number;
3117
+ reasoningTokens?: number;
3118
+ };
3119
+ stopReason: string;
3120
+ /** Raw JSON request body sent to the provider (for diagnostics logging). */
3121
+ rawRequest?: unknown;
3122
+ /** Raw JSON response body received from the provider (for diagnostics logging). */
3123
+ rawResponse?: unknown;
3124
+ }
3125
+
2966
3126
  /** Callback for proxy policy decisions requiring user confirmation. Returns true if approved. */
2967
3127
  declare type ProxyApprovalCallback = (request: ProxyApprovalRequest) => Promise<boolean>;
2968
3128
 
@@ -3168,6 +3328,96 @@ declare const SecretRequestEventSchema: z.ZodObject<{
3168
3328
  allowOneTimeSend: z.ZodOptional<z.ZodBoolean>;
3169
3329
  }, z.core.$strip>;
3170
3330
 
3331
+ export declare interface SendMessageConfig {
3332
+ model?: string;
3333
+ /**
3334
+ * LLM call-site identifier. `RetryProvider` resolves
3335
+ * provider/model/maxTokens/effort/speed/verbosity/temperature/thinking/
3336
+ * contextWindow via `resolveCallSiteConfig(callSite, config.llm)`, falling
3337
+ * back to `llm.default` when no callSite-specific entry is present.
3338
+ */
3339
+ callSite?: LLMCallSite;
3340
+ /**
3341
+ * Optional ad-hoc profile override applied per request. When set, the
3342
+ * resolver layers `llm.profiles[overrideProfile]` between the workspace's
3343
+ * `activeProfile` and the call-site's named profile (see
3344
+ * `resolveCallSiteConfig`). Used by per-conversation pinned profiles to
3345
+ * override the workspace default for a single send. Missing profile names
3346
+ * silently fall through.
3347
+ */
3348
+ overrideProfile?: string;
3349
+ /**
3350
+ * When true, the resolver floats `overrideProfile` above the call-site
3351
+ * layers (named site profile + call-site override) for non-main-agent call
3352
+ * sites — see `ResolveCallSiteOpts.forceOverrideProfile`. Used by callers
3353
+ * that must run a background call site under a specific conversation's
3354
+ * inference profile (e.g. fork-based memory retrospectives). A
3355
+ * resolution/routing-time concern only; stripped before any provider wire
3356
+ * request.
3357
+ */
3358
+ forceOverrideProfile?: boolean;
3359
+ /**
3360
+ * Per-conversation seed for deterministic `mix`-profile expansion. The agent
3361
+ * loop sets this to the conversation id so every resolver call this send
3362
+ * triggers — provider/transport selection, wire-param normalization, usage
3363
+ * attribution — picks the same mix constituent, stable across the
3364
+ * conversation's turns and retries. A resolution/routing-time concern only;
3365
+ * stripped before any provider wire request.
3366
+ */
3367
+ selectionSeed?: string;
3368
+ /**
3369
+ * Internal per-request HTTP headers for managed-proxy usage attribution.
3370
+ * Provider clients may pass these through SDK request options only when the
3371
+ * transport is Vellum-managed, and must never include this object in provider
3372
+ * JSON request bodies.
3373
+ */
3374
+ usageAttributionHeaders?: Record<string, string>;
3375
+ /**
3376
+ * Controls local usage-ledger writes for attributed provider calls.
3377
+ * Defaults to `auto`; conversation paths that aggregate usage separately
3378
+ * set `manual` to avoid double-counting.
3379
+ */
3380
+ usageTracking?: "auto" | "manual";
3381
+ effort?: "none" | "low" | "medium" | "high" | "xhigh" | "max";
3382
+ speed?: "standard" | "fast";
3383
+ verbosity?: "low" | "medium" | "high";
3384
+ /**
3385
+ * Wire-format `logit_bias` map (`{ "<tokenId>": bias }`). Set by
3386
+ * `RetryProvider` from a profile's `logitBias` preset and forwarded only on
3387
+ * the OpenAI-compatible (Fireworks) path; other providers ignore it.
3388
+ */
3389
+ logit_bias?: Record<string, number>;
3390
+ /**
3391
+ * When true, the most recent user message's content varies across
3392
+ * otherwise-identical turns (e.g. a per-turn memory block was injected into
3393
+ * it). The provider places the primary long-TTL cache breakpoint on the most
3394
+ * recent *stable* user message instead of the volatile latest one, so the
3395
+ * cached prefix stays reusable across turns. Default false — existing
3396
+ * behavior.
3397
+ */
3398
+ mutableLatestUserMessage?: boolean;
3399
+ /**
3400
+ * When true, the provider sends no prompt-cache breakpoints at all (and
3401
+ * strips any block-level `cache_control` markers callers stamped on
3402
+ * messages). For one-shot call sites whose prompts are unique per call or
3403
+ * whose call cadence exceeds the cache TTL, every breakpoint is a paid
3404
+ * cache write that will never be read — opting out saves the write
3405
+ * premium. Resolved per call site via `resolveCallSiteConfig` (see
3406
+ * `disableCache` in the LLM config schema); a per-call explicit value
3407
+ * wins. Default false — existing behavior.
3408
+ */
3409
+ disableCache?: boolean;
3410
+ [key: string]: unknown;
3411
+ }
3412
+
3413
+ export declare interface SendMessageOptions {
3414
+ tools?: ToolDefinition_2[];
3415
+ systemPrompt?: string;
3416
+ config?: SendMessageConfig;
3417
+ onEvent?: (event: ProviderEvent) => void;
3418
+ signal?: AbortSignal;
3419
+ }
3420
+
3171
3421
  declare interface SensitiveOutputBinding {
3172
3422
  kind: SensitiveOutputKind;
3173
3423
  placeholder: string;
@@ -3696,6 +3946,14 @@ export declare interface ToolContext {
3696
3946
  * `executeSubagentSpawn` in tools/subagent/spawn.ts.
3697
3947
  */
3698
3948
  overrideProfile?: string;
3949
+ /**
3950
+ * The LLM call site of the turn currently executing this tool (`mainAgent`,
3951
+ * `heartbeatAgent`, scheduled work, etc.). `subagent_spawn` reads it to
3952
+ * default a spawned subagent's inference profile to the profile the invoking
3953
+ * turn resolved to, so subagents match whatever agent invoked them rather
3954
+ * than always falling back to the static `subagentSpawn` call-site default.
3955
+ */
3956
+ invokingCallSite?: LLMCallSite;
3699
3957
  /**
3700
3958
  * Canonical principal ID of the actor on whose behalf this tool invocation
3701
3959
  * is running. Sourced from `conversation.trustContext.guardianPrincipalId`.
@@ -3715,6 +3973,12 @@ export declare interface ToolContext {
3715
3973
  */
3716
3974
  export declare type ToolDefinition = z.infer<typeof ToolDefinitionSchema>;
3717
3975
 
3976
+ declare interface ToolDefinition_2 {
3977
+ name: string;
3978
+ description: string;
3979
+ input_schema: object;
3980
+ }
3981
+
3718
3982
  /**
3719
3983
  * Schema describing the shape of a {@link ToolDefinition}. All fields are
3720
3984
  * optional — loaders fill documented defaults for omitted fields via
@@ -4060,6 +4324,7 @@ declare const ToolResultEventSchema: z.ZodObject<{
4060
4324
  brave: "brave";
4061
4325
  perplexity: "perplexity";
4062
4326
  tavily: "tavily";
4327
+ firecrawl: "firecrawl";
4063
4328
  }>;
4064
4329
  resultCount: z.ZodNumber;
4065
4330
  durationMs: z.ZodNumber;
@@ -4078,6 +4343,10 @@ declare const ToolResultEventSchema: z.ZodObject<{
4078
4343
  webFetch: z.ZodOptional<z.ZodObject<{
4079
4344
  url: z.ZodString;
4080
4345
  finalUrl: z.ZodString;
4346
+ provider: z.ZodOptional<z.ZodEnum<{
4347
+ default: "default";
4348
+ firecrawl: "firecrawl";
4349
+ }>>;
4081
4350
  status: z.ZodNumber;
4082
4351
  contentType: z.ZodOptional<z.ZodString>;
4083
4352
  byteCount: z.ZodNumber;
@@ -4175,11 +4444,15 @@ declare const TraceEventSchema: z.ZodObject<{
4175
4444
  * - `'trusted_contact'`: The sender is an active contact with a channel
4176
4445
  * (not the guardian). Trusted contacts can invoke tools but require
4177
4446
  * guardian approval for sensitive operations.
4447
+ * - `'unverified_contact'`: The sender matches a contact channel whose
4448
+ * status is `pending` or `unverified` — known to the guardian but not yet
4449
+ * verified. Treated identically to `trusted_contact` for every downstream
4450
+ * capability/tool/approval decision; the distinction is admission-only.
4178
4451
  * - `'unknown'`: The sender has no contact record, no identity could be
4179
- * established, or the sender is an inactive/revoked contact. Unknown
4452
+ * established, or the sender is a blocked/revoked contact. Unknown
4180
4453
  * actors are fail-closed with no escalation path.
4181
4454
  */
4182
- declare type TrustClass = "guardian" | "trusted_contact" | "unknown";
4455
+ declare type TrustClass = "guardian" | "trusted_contact" | "unverified_contact" | "unknown";
4183
4456
 
4184
4457
  declare type TurnProfileAutoRoutedEvent = z.infer<typeof TurnProfileAutoRoutedEventSchema>;
4185
4458
 
@@ -4502,6 +4775,8 @@ declare interface VercelApiConfigResponse {
4502
4775
  declare interface WebFetchMetadata {
4503
4776
  url: string;
4504
4777
  finalUrl: string;
4778
+ /** Provider that served the fetch. Defaults to the built-in fetcher. */
4779
+ provider?: WebFetchProviderId;
4505
4780
  status: number;
4506
4781
  contentType?: string;
4507
4782
  byteCount: number;
@@ -4517,6 +4792,9 @@ declare interface WebFetchMetadata {
4517
4792
  mayRequireJavaScript?: boolean;
4518
4793
  }
4519
4794
 
4795
+ /** Provider that backed a `web_fetch` call. `default` is the built-in fetcher. */
4796
+ declare type WebFetchProviderId = "default" | "firecrawl";
4797
+
4520
4798
  declare interface WebSearchMetadata {
4521
4799
  query: string;
4522
4800
  provider: WebSearchProviderId;
@@ -4527,7 +4805,7 @@ declare interface WebSearchMetadata {
4527
4805
  errorMessage?: string;
4528
4806
  }
4529
4807
 
4530
- declare type WebSearchProviderId = "anthropic-native" | "brave" | "perplexity" | "tavily";
4808
+ declare type WebSearchProviderId = "anthropic-native" | "brave" | "perplexity" | "tavily" | "firecrawl";
4531
4809
 
4532
4810
  declare interface WebSearchResultItem {
4533
4811
  rank: number;
@@ -4554,6 +4832,13 @@ export declare interface WebSearchToolResultContent {
4554
4832
  declare interface WorkflowCompleted {
4555
4833
  type: "workflow_completed";
4556
4834
  runId: string;
4835
+ /**
4836
+ * Originating conversation id, when launched from one; lets `broadcastMessage`
4837
+ * auto-scope + seq-stamp the event to that conversation's SSE stream. Omitted
4838
+ * for a conversationless run (e.g. a scheduled workflow), which broadcasts
4839
+ * unscoped for raw SSE listeners and the DB record.
4840
+ */
4841
+ conversationId?: string;
4557
4842
  status: WorkflowRunStatus;
4558
4843
  agentsSpawned: number;
4559
4844
  inputTokens: number;
@@ -4562,6 +4847,49 @@ declare interface WorkflowCompleted {
4562
4847
  summary?: string;
4563
4848
  }
4564
4849
 
4850
+ /**
4851
+ * A leaf agent within a workflow run has finished. `seq` matches the
4852
+ * corresponding `workflow_leaf_started` event.
4853
+ */
4854
+ declare interface WorkflowLeafFinished {
4855
+ type: "workflow_leaf_finished";
4856
+ runId: string;
4857
+ /**
4858
+ * Originating conversation id; lets `broadcastMessage` auto-scope +
4859
+ * seq-stamp the event to the conversation's SSE stream.
4860
+ */
4861
+ conversationId: string;
4862
+ seq: number;
4863
+ status: "completed" | "failed";
4864
+ /** Leaf label, for client display. */
4865
+ label?: string;
4866
+ inputTokens?: number;
4867
+ outputTokens?: number;
4868
+ /** Short summary of the leaf's result, for client display. */
4869
+ resultSummary?: string;
4870
+ }
4871
+
4872
+ /**
4873
+ * A leaf agent within a workflow run has started. `seq` orders leaves within
4874
+ * the run for stable client-side tree placement.
4875
+ */
4876
+ declare interface WorkflowLeafStarted {
4877
+ type: "workflow_leaf_started";
4878
+ runId: string;
4879
+ /**
4880
+ * Originating conversation id; lets `broadcastMessage` auto-scope +
4881
+ * seq-stamp the event to the conversation's SSE stream.
4882
+ */
4883
+ conversationId: string;
4884
+ seq: number;
4885
+ /** Leaf label, for client display. */
4886
+ label?: string;
4887
+ /** Phase the leaf belongs to, when the workflow declares phases. */
4888
+ phase?: string;
4889
+ /** Short summary of the leaf's prompt, for client display. */
4890
+ promptSummary?: string;
4891
+ }
4892
+
4565
4893
  /**
4566
4894
  * Progress push for an in-flight workflow run. Maps the engine's
4567
4895
  * `onProgress` (`phase`/`log`) callback plus the current usage snapshot into a
@@ -4571,6 +4899,13 @@ declare interface WorkflowCompleted {
4571
4899
  declare interface WorkflowProgress {
4572
4900
  type: "workflow_progress";
4573
4901
  runId: string;
4902
+ /**
4903
+ * Originating conversation id, when launched from one; lets `broadcastMessage`
4904
+ * auto-scope + seq-stamp the event to that conversation's SSE stream. Omitted
4905
+ * for a conversationless run (e.g. a scheduled workflow), which broadcasts
4906
+ * unscoped for raw SSE listeners and the DB record.
4907
+ */
4908
+ conversationId?: string;
4574
4909
  /** Latest phase title, when this emission came from a `phase(...)` call. */
4575
4910
  phase?: string;
4576
4911
  /** Run label (the workflow's `meta.name`), for client display. */
@@ -4598,7 +4933,27 @@ declare interface WorkflowProgress {
4598
4933
  */
4599
4934
  declare type WorkflowRunStatus = "running" | "completed" | "failed" | "aborted" | "cap_exceeded" | "interrupted";
4600
4935
 
4601
- declare type _WorkflowsServerMessages = WorkflowProgress | WorkflowCompleted;
4936
+ declare type _WorkflowsServerMessages = WorkflowProgress | WorkflowCompleted | WorkflowStarted | WorkflowLeafStarted | WorkflowLeafFinished;
4937
+
4938
+ /**
4939
+ * A workflow run has started. Emitted once at launch, before any leaf events.
4940
+ */
4941
+ declare interface WorkflowStarted {
4942
+ type: "workflow_started";
4943
+ runId: string;
4944
+ /**
4945
+ * Originating conversation id; lets `broadcastMessage` auto-scope +
4946
+ * seq-stamp the event to the conversation's SSE stream.
4947
+ */
4948
+ conversationId: string;
4949
+ /**
4950
+ * Tool-use id of the `skill_execute` block that launched this run, for
4951
+ * anchoring the inline workflow card to the exact spawn tool call.
4952
+ */
4953
+ toolUseId?: string;
4954
+ /** Run label (the workflow's `meta.name`), for client display. */
4955
+ label?: string;
4956
+ }
4602
4957
 
4603
4958
  declare interface WorkItemApprovePermissionsResponse {
4604
4959
  type: "work_item_approve_permissions_response";
package/index.js CHANGED
@@ -3,4 +3,6 @@ const api = globalThis[Symbol.for("vellum.plugin-api")] ?? {};
3
3
  export const HOOKS = api.HOOKS;
4
4
  export const RiskLevel = api.RiskLevel;
5
5
  export const assistantEventHub = api.assistantEventHub;
6
+ export const getConfiguredProvider = api.getConfiguredProvider;
7
+ export const getModelProfiles = api.getModelProfiles;
6
8
  export const getSecureKeyAsync = api.getSecureKeyAsync;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vellumai/plugin-api",
3
- "version": "0.9.0",
3
+ "version": "0.10.0-dev.202606192226.8ed8a6a",
4
4
  "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
5
5
  "license": "MIT",
6
6
  "type": "module",