@vellumai/plugin-api 0.10.2 → 0.10.3-dev.202606252046.9075fd5

package/index.d.ts

@@ -575,6 +575,27 @@ declare const CardSurfaceDataSchema: z.ZodObject<{
     templateData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 
+/**
+ * Canonical channel-id vocabulary shared between the assistant daemon and the
+ * gateway.
+ *
+ * A "channel" is an external messaging surface an actor can reach the
+ * assistant through (Slack, Telegram, WhatsApp, phone, …) plus a couple of
+ * internal ids (`vellum` for native app conversations, `platform` for the
+ * internal control plane). This is the single source of truth for that set:
+ * the assistant adopts it wholesale as its `ChannelId`, and the gateway
+ * asserts its own (narrower) inbound list is a subset of it so the two sides
+ * cannot silently drift.
+ *
+ * Both packages depend on `@vellumai/service-contracts`, so hoisting the set
+ * here (rather than maintaining a copy on each side) means adding or renaming
+ * a channel happens in exactly one place.
+ *
+ * Note that a consumer may legitimately handle only a *subset* of these — the
+ * gateway, for example, never ingresses `platform`. Use a local list guarded
+ * by `satisfies readonly ChannelId[]` for those cases rather than redefining
+ * the union.
+ */
 declare const CHANNEL_IDS: readonly ["telegram", "phone", "vellum", "whatsapp", "slack", "email", "platform", "a2a"];
 
 /** Channel binding metadata exposed in conversation list APIs. */
@@ -1035,6 +1056,40 @@ declare interface ConversationListResponse {
     hasMore?: boolean;
 }
 
+declare type ConversationNoticeEvent = z.infer<typeof ConversationNoticeEventSchema>;
+
+declare const ConversationNoticeEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"conversation_notice">;
+    conversationId: z.ZodString;
+    source: z.ZodEnum<{
+        memory_v3: "memory_v3";
+    }>;
+    code: z.ZodEnum<{
+        PROVIDER_NETWORK: "PROVIDER_NETWORK";
+        PROVIDER_RATE_LIMIT: "PROVIDER_RATE_LIMIT";
+        MANAGED_USAGE_LIMIT: "MANAGED_USAGE_LIMIT";
+        PROVIDER_OVERLOADED: "PROVIDER_OVERLOADED";
+        PROVIDER_API: "PROVIDER_API";
+        IMAGE_TOO_LARGE: "IMAGE_TOO_LARGE";
+        PROVIDER_BILLING: "PROVIDER_BILLING";
+        PROVIDER_ORDERING: "PROVIDER_ORDERING";
+        PROVIDER_WEB_SEARCH: "PROVIDER_WEB_SEARCH";
+        PROVIDER_NOT_CONFIGURED: "PROVIDER_NOT_CONFIGURED";
+        PROVIDER_INVALID_KEY: "PROVIDER_INVALID_KEY";
+        MANAGED_KEY_INVALID: "MANAGED_KEY_INVALID";
+        CONTEXT_TOO_LARGE: "CONTEXT_TOO_LARGE";
+        BUDGET_YIELD_UNRECOVERED: "BUDGET_YIELD_UNRECOVERED";
+        MAX_TOKENS_REACHED: "MAX_TOKENS_REACHED";
+        CONVERSATION_ABORTED: "CONVERSATION_ABORTED";
+        CONVERSATION_PROCESSING_FAILED: "CONVERSATION_PROCESSING_FAILED";
+        DISK_SPACE_CRITICAL: "DISK_SPACE_CRITICAL";
+        REGENERATE_FAILED: "REGENERATE_FAILED";
+        UNKNOWN: "UNKNOWN";
+    }>;
+    userMessage: z.ZodString;
+    errorCategory: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+
 declare interface ConversationsClearResponse {
     type: "conversations_clear_response";
     cleared: number;
@@ -1061,7 +1116,7 @@ declare interface ConversationSearchResultItem {
     matchingMessages: ConversationSearchMatchingMessage[];
 }
 
-declare type _ConversationsServerMessages = AuthResult | PongMessage | AssistantStatusMessage | GenerationCancelledEvent | GenerationHandoffEvent | ModelInfo | HistoryResponse | UndoComplete | UsageUpdateEvent | UsageProgressEvent | UsageResponse | ContextCompacted | CompactionCircuitOpenEvent | CompactionCircuitClosedEvent | ConversationErrorEvent | ConversationInfo | ConversationTitleUpdatedEvent | ConversationListResponse | ConversationsClearResponse | ConversationSearchResponse | MessageContentResponse | ConversationListInvalidatedEvent | ScheduleConversationCreated | OpenConversation;
+declare type _ConversationsServerMessages = AuthResult | PongMessage | AssistantStatusMessage | GenerationCancelledEvent | GenerationHandoffEvent | ModelInfo | HistoryResponse | UndoComplete | UsageUpdateEvent | UsageProgressEvent | UsageResponse | ContextCompacted | CompactionCircuitOpenEvent | CompactionCircuitClosedEvent | ConversationErrorEvent | ConversationNoticeEvent | ConversationInfo | ConversationTitleUpdatedEvent | ConversationListResponse | ConversationsClearResponse | ConversationSearchResponse | MessageContentResponse | ConversationListInvalidatedEvent | ScheduleConversationCreated | OpenConversation;
 
 declare type ConversationTitleUpdatedEvent = z.infer<typeof ConversationTitleUpdatedEventSchema>;
 
@@ -1245,21 +1300,13 @@ declare interface DocumentSaveResponse {
 declare type _DocumentsServerMessages = DocumentEditorShow | DocumentEditorUpdateEvent | DocumentSaveResponse | DocumentLoadResponse | DocumentListResponse;
 
 /**
- * Whether a profile's resolved model can process image input.
+ * Whether the given model or profile can process image input.
  *
- * Resolution mirrors the host's call-site resolver:
- * - The profile's `(provider, model)` fields are merged over `llm.default` so
- *   a profile that only sets `model` (or only `provider`) inherits the other
- *   from the workspace default.
- * - When `provider` is still missing but `model` is a known catalog model,
- *   the provider is inferred via `getCatalogProviderForModel` (same logic as
- *   the resolver's `withImpliedProviderForKnownModel`).
- * - For a mix profile, returns `true` if any constituent arm supports vision
- *   (the mix can route to it) and `false` only if every arm is text-only.
- * - Unknown `(provider, model)` pairs default to `true` (fail-open), matching
- *   the config GET route's `enrichProfilesWithVisionFlag`.
+ * `modelOrProfile` may be a concrete model id, a profile key, or a
+ * {@link ModelProfileInfo}. A bare string is resolved as a model id first and,
+ * failing that, as a profile key. Returns `false` when nothing resolves.
  */
-export declare function doesSupportVision(profile: ModelProfileInfo): boolean;
+export declare function doesSupportVision(modelOrProfile: ModelProfileInfo | string): boolean;
 
 declare interface DynamicPagePreview {
     title: string;
@@ -1378,12 +1425,14 @@ export declare interface FileContent {
     _attachmentId?: string;
 }
 
-declare interface FileUploadSurfaceData {
-    prompt: string;
-    acceptedTypes?: string[];
-    maxFiles?: number;
-    maxSizeBytes?: number;
-}
+declare type FileUploadSurfaceData = z.infer<typeof FileUploadSurfaceDataSchema>;
+
+declare const FileUploadSurfaceDataSchema: z.ZodObject<{
+    prompt: z.ZodOptional<z.ZodCoercedString<unknown>>;
+    acceptedTypes: z.ZodPipe<z.ZodTransform<string[] | undefined, unknown>, z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    maxFiles: z.ZodCatch<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+    maxSizeBytes: z.ZodCatch<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+}, z.core.$strip>;
 
 declare interface FilingConfigResponse {
     type: "filing_config_response";
@@ -1740,6 +1789,32 @@ declare const HomeFeedUpdatedEventSchema: z.ZodObject<{
 
 declare type _HomeServerMessages = RelationshipStateUpdatedEvent | HomeFeedUpdatedEvent;
 
+/**
+ * A plugin lifecycle hook. Receives a per-lifecycle context shape and may
+ * either mutate `ctx` in place (returning `void`) or return a *partial*
+ * context whose fields are merged onto the threaded context — only the keys
+ * it returns are overwritten, every other field is preserved. Returning a
+ * partial lets a hook edit just the subset of fields it cares about without
+ * having to re-specify the rest. The merged context is threaded to the next
+ * hook in the chain (e.g. `user-prompt-submit`).
+ *
+ * Because an omitted key means "keep the existing value", every field on a
+ * context shape is required (no `?`-optional or `| undefined` members): a
+ * present key always carries a concrete value, so "absent from the returned
+ * partial" is never ambiguous with "explicitly cleared". Fields that can be
+ * empty model that with `| null`, not `| undefined`.
+ *
+ * Each known hook key has a documented context shape:
+ *   - `init` — {@link InitContext}
+ *   - `shutdown` — {@link ShutdownContext}
+ *   - `user-prompt-submit` — {@link UserPromptSubmitContext}
+ *   - `pre-model-call` — {@link PreModelCallContext}
+ *   - `post-tool-use` — {@link PostToolUseContext}
+ *   - `stop` — {@link StopContext}
+ *   - `post-model-call` — {@link PostModelCallContext}
+ */
+export declare type HookFunction<TCtx = unknown> = (ctx: TCtx) => Promise<Partial<TCtx> | void>;
+
 /** Union of every hook name declared in {@link HOOKS}. */
 export declare type HookName = (typeof HOOKS)[keyof typeof HOOKS];
 
@@ -2090,6 +2165,27 @@ declare interface IngressConfigResponse {
     error?: string;
 }
 
+/**
+ * Context passed to `Plugin.init()` during bootstrap. Carries the resolved
+ * config, a pino-compatible logger scoped to the plugin, a per-plugin
+ * writable data directory, and the assistant's version metadata.
+ */
+export declare interface InitContext {
+    /** Parsed config for this plugin (may be `unknown` until the manifest validates). */
+    config: unknown;
+    /** Pino-compatible child logger bound to `{ plugin: <name> }`. */
+    logger: PluginLogger;
+    /** Absolute path to `<workspaceDir>/plugins-data/<plugin>/` (created by bootstrap). */
+    pluginStorageDir: string;
+    /**
+     * Assistant semver. Plugins can compare against this for defensive
+     * runtime checks — but the canonical compat contract is the host
+     * version against the plugin's `peerDependencies["@vellumai/plugin-api"]`
+     * semver range, enforced at load time by the external-plugin loader.
+     */
+    assistantVersion: string;
+}
+
 declare interface IntegrationConnectResult {
     type: "integration_connect_result";
     integrationId: string;
@@ -2195,7 +2291,6 @@ declare const LLMCallSiteEnum: z.ZodEnum<{
     meetConsentMonitor: "meetConsentMonitor";
     meetChatOpportunity: "meetChatOpportunity";
     inference: "inference";
-    advisor: "advisor";
     vision: "vision";
     trustRuleSuggestion: "trustRuleSuggestion";
     homeGreeting: "homeGreeting";
@@ -2675,55 +2770,6 @@ declare interface PlatformDisconnected {
     type: "platform_disconnected";
 }
 
-/**
- * A plugin lifecycle hook. Receives a per-lifecycle context shape and may
- * either mutate `ctx` in place (returning `void`) or return a *partial*
- * context whose fields are merged onto the threaded context — only the keys
- * it returns are overwritten, every other field is preserved. Returning a
- * partial lets a hook edit just the subset of fields it cares about without
- * having to re-specify the rest. The merged context is threaded to the next
- * hook in the chain (e.g. `user-prompt-submit`).
- *
- * Because an omitted key means "keep the existing value", every field on a
- * context shape is required (no `?`-optional or `| undefined` members): a
- * present key always carries a concrete value, so "absent from the returned
- * partial" is never ambiguous with "explicitly cleared". Fields that can be
- * empty model that with `| null`, not `| undefined`.
- *
- * Each known hook key has a documented context shape:
- *   - `init` — {@link PluginInitContext}
- *   - `shutdown` — {@link PluginShutdownContext}
- *   - `user-prompt-submit` — {@link UserPromptSubmitContext}
- *   - `pre-model-call` — {@link PreModelCallContext}
- *   - `post-tool-use` — {@link PostToolUseContext}
- *   - `stop` — {@link StopContext}
- *   - `post-model-call` — {@link PostModelCallContext}
- */
-export declare type PluginHookFn<TCtx = unknown> = (ctx: TCtx) => Promise<Partial<TCtx> | void>;
-
-/**
- * Context passed to `Plugin.init()` during bootstrap. Carries resolved
- * config/credentials, a pino-compatible logger scoped to the plugin, a
- * per-plugin writable data directory, and the assistant's version metadata.
- */
-export declare interface PluginInitContext {
-    /** Parsed config for this plugin (may be `unknown` until the manifest validates). */
-    config: unknown;
-    /** Resolved credential values keyed by the entries of `manifest.requiresCredential`. */
-    credentials: Record<string, string>;
-    /** Pino-compatible child logger bound to `{ plugin: <name> }`. */
-    logger: PluginLogger;
-    /** Absolute path to `<workspaceDir>/plugins-data/<plugin>/` (created by bootstrap). */
-    pluginStorageDir: string;
-    /**
-     * Assistant semver. Plugins can compare against this for defensive
-     * runtime checks — but the canonical compat contract is the host
-     * version against the plugin's `peerDependencies["@vellumai/plugin-api"]`
-     * semver range, enforced at load time by the external-plugin loader.
-     */
-    assistantVersion: string;
-}
-
 /**
  * Minimal pino-compatible logger surface handed to plugin hooks. The host
  * supplies a pino child logger bound to `{ plugin: <name> }`; this
@@ -2743,23 +2789,6 @@ export declare interface PluginLogger {
     debug(obj: Record<string, unknown>, msg?: string): void;
 }
 
-/**
- * Context passed to the `shutdown` hook during daemon teardown. Kept
- * intentionally narrower than {@link PluginInitContext} — most teardown
- * paths only need to know which assistant version they're shutting
- * down against (e.g. for version-conditional cleanup of state files
- * written by a previous boot).
- *
- * Additional fields may be added as concrete plugin needs surface; the
- * `assistantVersion` field mirrors the init context's so plugins that
- * stash a version stamp at init can compare against the same name on
- * tear-down without keeping their own copy.
- */
-export declare interface PluginShutdownContext {
-    /** Assistant semver for compatibility checks inside the plugin. */
-    assistantVersion: string;
-}
-
 declare interface PongMessage {
     type: "pong";
 }
@@ -2778,7 +2807,7 @@ declare interface PongMessage {
  * their own injected context the same way.
  *
  * The hook re-injects by mutating `history` in place (or returning a new
- * context with a replacement `history`) — see {@link PluginHookFn}'s
+ * context with a replacement `history`) — see {@link HookFunction}'s
  * polymorphic return shape. The agent loop reads the settled `history` back off
  * the context and resumes the turn from it. Multiple plugins' hooks chain in
  * registration order, each seeing the previous plugin's edits.
@@ -2925,7 +2954,7 @@ export declare type PostModelCallDecision = "continue" | "stop";
  *
  * The hook may transform the result either by mutating `toolResponse` in
  * place (e.g. reassigning `toolResponse.content`) or by returning a new
- * context with a fresh `toolResponse` — see {@link PluginHookFn}'s
+ * context with a fresh `toolResponse` — see {@link HookFunction}'s
  * polymorphic return shape. The daemon threads the final `toolResponse`
  * into the provider-bound history.
  *
@@ -3057,6 +3086,28 @@ export declare interface Provider {
      * Falls back to `name` when unset.
      */
     tokenEstimationProvider?: string;
+    /**
+     * True when this provider instance was constructed to run web search
+     * server-side (provider-native). The native search only activates when a
+     * `web_search`-named tool is passed in the request, so callers that want to
+     * enable web search on a one-shot completion (e.g. the advisor consult) check
+     * this first — passing the tool to a non-native instance would surface an
+     * unexecutable client tool call. Absent/false on providers without it.
+     */
+    supportsNativeWebSearch?: boolean;
+    /**
+     * Per-call native web-search capability for the provider/model this specific
+     * request will route to. Unlike the static {@link supportsNativeWebSearch}
+     * flag — fixed to the DEFAULT provider/model at construction — this consults
+     * the resolved call-site (`options.config.callSite` + `overrideProfile`) so a
+     * routing wrapper reports the ROUTED target's capability. Callers that gate a
+     * `web_search` server tool on a possibly-routed call (e.g. the advisor
+     * consult, whose `advisorProfile` may point at a different provider/model)
+     * must use this rather than the construction-time snapshot. Optional: wrappers
+     * forward it to their inner provider; leaf providers may omit it, in which
+     * case callers fall back to {@link supportsNativeWebSearch}.
+     */
+    supportsNativeWebSearchFor?(options?: SendMessageOptions): boolean;
     sendMessage(messages: Message[], options?: SendMessageOptions): Promise<ProviderResponse>;
     /**
      * Exact prompt-token count from the provider's own tokenizer, for the
@@ -3512,6 +3563,23 @@ declare interface ShowPlatformLogin {
     type: "show_platform_login";
 }
 
+/**
+ * Context passed to the `shutdown` hook during daemon teardown. Kept
+ * intentionally narrower than {@link InitContext} — most teardown
+ * paths only need to know which assistant version they're shutting
+ * down against (e.g. for version-conditional cleanup of state files
+ * written by a previous boot).
+ *
+ * Additional fields may be added as concrete plugin needs surface; the
+ * `assistantVersion` field mirrors the init context's so plugins that
+ * stash a version stamp at init can compare against the same name on
+ * tear-down without keeping their own copy.
+ */
+export declare interface ShutdownContext {
+    /** Assistant semver for compatibility checks inside the plugin. */
+    assistantVersion: string;
+}
+
 declare interface SignBundlePayloadRequest {
     type: "sign_bundle_payload";
     requestId: string;
@@ -3839,6 +3907,26 @@ declare interface ToolActivityMetadata {
     webFetch?: WebFetchMetadata;
 }
 
+/**
+ * Runtime context passed as the second argument to every tool's `execute`.
+ *
+ * The fields fall into two groups:
+ *
+ * - A small, stable core that we are comfortable exposing to any tool —
+ *   including workspace- and plugin-authored tools via `@vellumai/plugin-api`:
+ *   `conversationId`, `workingDir`, `requestId`, `signal`, `onOutput`,
+ *   `assistantId`, `isInteractive`.
+ * - Everything tagged `@legacy` below: host-internal routing, permission,
+ *   trust, requester-identity, proxy, and telemetry metadata that historically
+ *   accreted on this single context. These are NOT a surface we want third-party
+ *   tools to depend on; we are triaging them post-launch with the goal of
+ *   moving them off the public context (or removing them) over time. Grep for
+ *   `@legacy` to enumerate the set. Do not add new fields here — extend the
+ *   stable core only when a field is genuinely safe and stable to expose.
+ *
+ * The daemon constructs and passes the full object to every tool at runtime; a
+ * tool that only reads the stable core is unaffected by the eventual cleanup.
+ */
 export declare interface ToolContext {
     /** Identifier of the conversation this tool invocation belongs to. */
     conversationId: string;
@@ -3852,23 +3940,44 @@ export declare interface ToolContext {
     onOutput?: (chunk: string) => void;
     /** Logical assistant scope for multi-assistant routing. */
     assistantId?: string;
-    /** When set, the tool execution is part of a task run. Used to retrieve ephemeral permission rules. */
+    /** True when an interactive client is connected (not just a no-op callback). */
+    isInteractive?: boolean;
+    /**
+     * When set, the tool execution is part of a task run. Used to retrieve ephemeral permission rules.
+     * @legacy
+     */
     taskRunId?: string;
     /**
      * Model attribution snapshot for the conversation at invocation time
      * (provider/model/profile that issued this tool call). Used by tool
      * telemetry; never sent to the tool itself.
+     * @legacy
      */
     attribution?: UsageAttributionSnapshot | null;
-    /** Optional callback for tool lifecycle events (start/prompt/deny/execute/error). */
+    /**
+     * Optional callback for tool lifecycle events (start/prompt/deny/execute/error).
+     * @legacy
+     */
     onToolLifecycleEvent?: ToolLifecycleEventHandler;
-    /** Optional resolver for proxy tools - delegates execution to an external client. */
+    /**
+     * Optional resolver for proxy tools - delegates execution to an external client.
+     * @legacy
+     */
     proxyToolResolver?: ProxyToolResolver;
-    /** When set, only tools in this set may execute. Tools outside the set are blocked with an error. */
+    /**
+     * When set, only tools in this set may execute. Tools outside the set are blocked with an error.
+     * @legacy
+     */
     allowedToolNames?: Set<string>;
-    /** True when this turn is restricted to storage cleanup-safe tools. */
+    /**
+     * True when this turn is restricted to storage cleanup-safe tools.
+     * @legacy
+     */
     diskPressureCleanupModeActive?: boolean;
-    /** Prompt the user for a secret value via native SecureField UI. */
+    /**
+     * Prompt the user for a secret value via native SecureField UI.
+     * @legacy
+     */
     requestSecret?: (params: {
         service: string;
         field: string;
@@ -3879,14 +3988,18 @@ export declare interface ToolContext {
         allowedTools?: string[];
         allowedDomains?: string[];
     }) => Promise<SecretPromptResult>;
-    /** Optional callback to send a message to the connected client (e.g. open_url). */
+    /**
+     * Optional callback to send a message to the connected client (e.g. open_url).
+     * @legacy
+     */
     sendToClient?: (msg: {
         type: string;
         [key: string]: unknown;
     }) => void;
-    /** True when an interactive client is connected (not just a no-op callback). */
-    isInteractive?: boolean;
-    /** When true, tools with side effects should always prompt for confirmation. */
+    /**
+     * When true, tools with side effects should always prompt for confirmation.
+     * @legacy
+     */
     forcePromptSideEffects?: boolean;
     /**
      * When true, the tool requires a fresh interactive approval for every
@@ -3897,26 +4010,46 @@ export declare interface ToolContext {
      * temporary override options in the prompt UI. Used by
      * `manage_secure_command_tool` to ensure a human reviews each secure
      * bundle installation.
+     * @legacy
      */
     requireFreshApproval?: boolean;
-    /** Approval callback for proxy policy decisions that require user confirmation. */
+    /**
+     * Approval callback for proxy policy decisions that require user confirmation.
+     * @legacy
+     */
     proxyApprovalCallback?: ProxyApprovalCallback;
-    /** Optional principal identifier propagated to sub-tool confirmation flows. */
+    /**
+     * Optional principal identifier propagated to sub-tool confirmation flows.
+     * @legacy
+     */
     principal?: string;
     /**
      * Trust classification of the actor who initiated this tool invocation.
      * Determines permission level: guardians self-approve, trusted contacts
      * may escalate to guardian for approval, unknown actors are fail-closed.
      * See {@link TrustClass} in actor-trust-resolver.ts for value semantics.
+     * @legacy
      */
     trustClass: TrustClass;
-    /** Channel through which the tool invocation originates (e.g. 'telegram', 'phone'). Used for scoped grant consumption. */
+    /**
+     * Channel through which the tool invocation originates (e.g. 'telegram', 'phone'). Used for scoped grant consumption.
+     * @legacy
+     */
     executionChannel?: string;
-    /** Voice/call session ID, if the invocation originates from a call. Used for scoped grant consumption. */
+    /**
+     * Voice/call session ID, if the invocation originates from a call. Used for scoped grant consumption.
+     * @legacy
+     */
     callSessionId?: string;
-    /** True when the tool invocation was triggered by a user clicking a surface action button (not a regular message). */
+    /**
+     * True when the tool invocation was triggered by a user clicking a surface action button (not a regular message).
+     * @legacy
+     */
     triggeredBySurfaceAction?: boolean;
-    /** True when the user explicitly approved this tool invocation via the interactive permission prompt (not auto-approved by trust rules or temporary overrides). */
+    /**
+     * True when the user explicitly approved this tool invocation via the interactive permission prompt (not auto-approved by trust rules or temporary overrides).
+     * @legacy
+     */
     approvedViaPrompt?: boolean;
     /**
      * True when the invocation is inside a scheduled task run whose
@@ -3924,21 +4057,43 @@ export declare interface ToolContext {
      * Tools that normally require a surface-action click (e.g. bulk archive,
      * unsubscribe) may treat this as equivalent consent, since the user
      * already reviewed the tool list when the task was saved.
+     * @legacy
      */
     batchAuthorizedByTask?: boolean;
-    /** External user ID of the requester (non-guardian actor). Used for scoped grant consumption. */
+    /**
+     * External user ID of the requester (non-guardian actor). Used for scoped grant consumption.
+     * @legacy
+     */
     requesterExternalUserId?: string;
-    /** Chat ID of the requester (non-guardian actor). Used for tool grant request escalation notifications. */
+    /**
+     * Chat ID of the requester (non-guardian actor). Used for tool grant request escalation notifications.
+     * @legacy
+     */
     requesterChatId?: string;
-    /** Human-readable identifier for the requester (e.g., @username). */
+    /**
+     * Human-readable identifier for the requester (e.g., @username).
+     * @legacy
+     */
     requesterIdentifier?: string;
-    /** Preferred display name for the requester. */
+    /**
+     * Preferred display name for the requester.
+     * @legacy
+     */
     requesterDisplayName?: string;
-    /** Slack channel ID for channel-scoped permission enforcement. When set, tools are checked against the channel's permission profile. */
+    /**
+     * Slack channel ID for channel-scoped permission enforcement. When set, tools are checked against the channel's permission profile.
+     * @legacy
+     */
     channelPermissionChannelId?: string;
-    /** The tool_use block ID from the LLM response, used to correlate confirmation prompts with specific tool invocations. */
+    /**
+     * The tool_use block ID from the LLM response, used to correlate confirmation prompts with specific tool invocations.
+     * @legacy
+     */
     toolUseId?: string;
-    /** True when the assistant is running as a platform-managed remote instance. Used to auto-approve sandboxed bash tools. */
+    /**
+     * True when the assistant is running as a platform-managed remote instance. Used to auto-approve sandboxed bash tools.
+     * @legacy
+     */
     isPlatformHosted?: boolean;
     /**
      * The interface ID of the connected client driving the current turn (e.g.
@@ -3946,6 +4101,7 @@ export declare interface ToolContext {
      * transport preference — for example, macOS-originated turns prefer the
      * user's real Chrome session via the paired extension before falling back
      * to cdp-inspect or local Playwright.
+     * @legacy
      */
     transportInterface?: InterfaceId;
     /**
@@ -3956,6 +4112,7 @@ export declare interface ToolContext {
      * has `inferenceProfile` set — the override only flows through the
      * in-memory `SubagentConfig.overrideProfile` chain. See
      * `executeSubagentSpawn` in tools/subagent/spawn.ts.
+     * @legacy
      */
     overrideProfile?: string;
     /**
@@ -3964,6 +4121,7 @@ export declare interface ToolContext {
      * 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.
+     * @legacy
      */
     invokingCallSite?: LLMCallSite;
     /**
@@ -3972,6 +4130,7 @@ export declare interface ToolContext {
      * Used by host proxies to bind cross-client targeted execution to the same
      * authenticated user identity. May be undefined for legacy/internal flows
      * with no resolved actor identity.
+     * @legacy
      */
     sourceActorPrincipalId?: string;
 }
@@ -4024,6 +4183,7 @@ declare const ToolDefinitionSchema: z.ZodObject<{
         host: "host";
     }>>;
     execute: z.ZodOptional<z.ZodCustom<(input: Record<string, unknown>, context: ToolContext) => Promise<ToolExecutionResult>, (input: Record<string, unknown>, context: ToolContext) => Promise<ToolExecutionResult>>>;
+    exclusive: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 
 /**
@@ -4687,7 +4847,7 @@ declare const UserMessageEchoEventSchema: z.ZodObject<{
  *
  * The hook may transform `latestMessages` either by mutating it in place
  * (`push` / `splice` / `length = 0`) or by returning a new context with
- * a fresh `latestMessages` array — see {@link PluginHookFn}'s polymorphic
+ * a fresh `latestMessages` array — see {@link HookFunction}'s polymorphic
  * return shape. The daemon threads the final `latestMessages` value into
  * `agentLoop.run()` as the run-messages argument.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.10.2",
+  "version": "0.10.3-dev.202606252046.9075fd5",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",