@vellumai/plugin-api 0.11.0-staging.3 → 0.11.1-dev.202608010027.2cfe358

package/index.d.ts

@@ -120,6 +120,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
                 "openai-whisper": "openai-whisper";
                 xai: "xai";
             }>>;
+            language: z.ZodOptional<z.ZodString>;
             providers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
         }, z.core.$strip>>;
         tts: z.ZodDefault<z.ZodObject<{
@@ -498,6 +499,9 @@ declare const AssistantConfigSchema: z.ZodObject<{
         ringBufferSize: z.ZodDefault<z.ZodNumber>;
         highMemThresholdRatio: z.ZodDefault<z.ZodNumber>;
         snapshotCooldownMs: z.ZodDefault<z.ZodNumber>;
+        fdPollIntervalMs: z.ZodDefault<z.ZodNumber>;
+        highFdThresholdRatio: z.ZodDefault<z.ZodNumber>;
+        fdWarnCooldownMs: z.ZodDefault<z.ZodNumber>;
         pluginSourceScanIntervalMs: z.ZodDefault<z.ZodNumber>;
         baselineSnapshotIntervalMs: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
@@ -770,8 +774,18 @@ declare const AssistantConfigSchema: z.ZodObject<{
                 anthropic: "anthropic";
                 gemini: "gemini";
                 fireworks: "fireworks";
+                together: "together";
+                poolside: "poolside";
                 openrouter: "openrouter";
+                "vercel-ai-gateway": "vercel-ai-gateway";
+                ollama: "ollama";
+                "openai-compatible": "openai-compatible";
+                litellm: "litellm";
+                minimax: "minimax";
+                atlascloud: "atlascloud";
+                baseten: "baseten";
                 vellum: "vellum";
+                chatgpt: "chatgpt";
             }>;
             connectionName: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
@@ -1402,6 +1416,7 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         requestId: z.ZodString;
         channel: z.ZodOptional<z.ZodString>;
         placeholder: z.ZodOptional<z.ZodString>;
+        defaultValue: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
         role: z.ZodOptional<z.ZodString>;
@@ -1889,20 +1904,29 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         type: z.ZodLiteral<"message_dequeued">;
         conversationId: z.ZodString;
         requestId: z.ZodString;
+        clientMessageId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"message_queued">;
         conversationId: z.ZodString;
         requestId: z.ZodString;
         position: z.ZodNumber;
+        clientMessageId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"message_queued_deleted">;
         conversationId: z.ZodString;
         requestId: z.ZodString;
+        clientMessageId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"message_request_complete">;
         conversationId: z.ZodString;
         requestId: z.ZodString;
         runStillActive: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"message_requeued">;
+        conversationId: z.ZodString;
+        requestId: z.ZodString;
+        position: z.ZodNumber;
+        clientMessageId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"message_steered">;
         conversationId: z.ZodString;
@@ -1949,6 +1973,7 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         deepLinkMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         targetGuardianPrincipalId: z.ZodOptional<z.ZodString>;
         silent: z.ZodOptional<z.ZodBoolean>;
+        remotePushDispatched: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"oauth_connect_result">;
         success: z.ZodBoolean;
@@ -2181,6 +2206,7 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
                     brave: "brave";
                     perplexity: "perplexity";
                     tavily: "tavily";
+                    keenable: "keenable";
                     firecrawl: "firecrawl";
                 }>;
                 resultCount: z.ZodNumber;
@@ -2246,6 +2272,12 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         type: z.ZodLiteral<"ui_surface_dismiss">;
         conversationId: z.ZodString;
         surfaceId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"ui_surface_pending">;
+        conversationId: z.ZodString;
+        surfaceType: z.ZodLiteral<"visual">;
+        toolUseId: z.ZodString;
+        messageId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"ui_surface_show">;
         conversationId: z.ZodString;
@@ -2762,6 +2794,7 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     requestId: z.ZodString;
     channel: z.ZodOptional<z.ZodString>;
     placeholder: z.ZodOptional<z.ZodString>;
+    defaultValue: z.ZodOptional<z.ZodString>;
     label: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     role: z.ZodOptional<z.ZodString>;
@@ -3249,20 +3282,29 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"message_dequeued">;
     conversationId: z.ZodString;
     requestId: z.ZodString;
+    clientMessageId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"message_queued">;
     conversationId: z.ZodString;
     requestId: z.ZodString;
     position: z.ZodNumber;
+    clientMessageId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"message_queued_deleted">;
     conversationId: z.ZodString;
     requestId: z.ZodString;
+    clientMessageId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"message_request_complete">;
     conversationId: z.ZodString;
     requestId: z.ZodString;
     runStillActive: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"message_requeued">;
+    conversationId: z.ZodString;
+    requestId: z.ZodString;
+    position: z.ZodNumber;
+    clientMessageId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"message_steered">;
     conversationId: z.ZodString;
@@ -3309,6 +3351,7 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     deepLinkMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     targetGuardianPrincipalId: z.ZodOptional<z.ZodString>;
     silent: z.ZodOptional<z.ZodBoolean>;
+    remotePushDispatched: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"oauth_connect_result">;
     success: z.ZodBoolean;
@@ -3541,6 +3584,7 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 brave: "brave";
                 perplexity: "perplexity";
                 tavily: "tavily";
+                keenable: "keenable";
                 firecrawl: "firecrawl";
             }>;
             resultCount: z.ZodNumber;
@@ -3606,6 +3650,12 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"ui_surface_dismiss">;
     conversationId: z.ZodString;
     surfaceId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ui_surface_pending">;
+    conversationId: z.ZodString;
+    surfaceType: z.ZodLiteral<"visual">;
+    toolUseId: z.ZodString;
+    messageId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"ui_surface_show">;
     conversationId: z.ZodString;
@@ -3735,7 +3785,7 @@ export declare interface AssistantEventSubscription {
     readonly connectionId: string;
 }
 
-declare interface AudioEmbeddingInput {
+export declare interface AudioEmbeddingInput {
     type: "audio";
     data: Buffer;
     mimeType: string;
@@ -4047,28 +4097,30 @@ declare type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Om
  */
 export declare function doesSupportVision(modelOrProfile: ModelProfileInfo | string): boolean;
 
+/**
+ * Embed an input and return the raw dense vector (provider, model, and
+ * dimensions included), with no persistence.
+ */
+export declare function embed(input: EmbeddingInput): Promise<EmbedResult>;
+
 /** Embed a target and upsert its vector into the vector store. */
 export declare function embedAndUpsert(targetType: EmbeddingTargetType, targetId: string, input: EmbeddingInput, extraPayload?: Record<string, unknown>): Promise<void>;
 
 declare function embedAndUpsert_2(config: AssistantConfig, targetType: "segment" | "item" | "summary" | "media" | "graph_node" | "pkb_file", targetId: string, input: EmbeddingInput, extraPayload?: Record<string, unknown>): Promise<void>;
 
 /** Accepts raw strings as shorthand for text inputs. */
-declare type EmbeddingInput = string | MultimodalEmbeddingInput;
+export declare type EmbeddingInput = string | MultimodalEmbeddingInput;
 
-/**
- * Plugin-facing facade over the embeddings subsystem: self-contained
- * operations that resolve the live workspace config internally, so callers
- * (plugins importing via `@vellumai/plugin-api`) hold no host config.
- *
- * The operations are loaded via dynamic `import()` inside each wrapper so
- * that importing this module — which every `@vellumai/plugin-api` consumer
- * does transitively — does not eagerly pull the embed/vector import graph
- * (`job-utils`, `embedding-backend`). An eager pull would force those
- * modules' named exports to resolve at instantiation, which breaks the
- * intentional partial module mocks in tests.
- */
 declare type EmbeddingTargetType = Parameters<embedAndUpsert_2>[1];
 
+/** A computed embedding with the provider/model that produced it. */
+export declare interface EmbedResult {
+    vector: number[];
+    provider: string;
+    model: string;
+    dimensions: number;
+}
+
 export declare function extractTextFromStoredMessageContent(raw: string | ContentBlock[]): string;
 
 export declare interface FileContent {
@@ -4086,6 +4138,12 @@ export declare interface FileContent {
     _attachmentId?: string;
 }
 
+/**
+ * Generate the sparse (lexical) vector for a text using the host's shared
+ * encoder. Pure and local: no backend call, no persistence.
+ */
+export declare function generateSparseEmbedding(text: string): Promise<SparseEmbedding>;
+
 /** Read the assistant's name from IDENTITY.md for personalized responses. */
 export declare function getAssistantName(): string | null;
 
@@ -4108,6 +4166,9 @@ export declare function getConversation(id: string): Promise<ConversationRow | n
  */
 export declare function getConversationDirPath(id: string, createdAtMs: number): Promise<string>;
 
+/** Fetch one document from the calling plugin's index, or null. */
+export declare function getDocument(documentId: string): Promise<IndexedDocument | null>;
+
 /** All messages of a conversation in insertion order. */
 export declare function getMessages(conversationId: string): Promise<MessageRow[]>;
 
@@ -4254,12 +4315,57 @@ export declare interface ImageContent {
     source: MediaSource_2;
 }
 
-declare interface ImageEmbeddingInput {
+export declare interface ImageEmbeddingInput {
     type: "image";
     data: Buffer;
     mimeType: string;
 }
 
+/**
+ * Embed and upsert a document into the calling plugin's private index (not
+ * agent recall). Returns the document id. Pass `opts.documentId` to overwrite
+ * an existing document in place.
+ */
+export declare function indexDocument(input: EmbeddingInput, opts?: IndexDocumentOptions): Promise<IndexDocumentResult>;
+
+export declare interface IndexDocumentOptions {
+    /**
+     * Reuse a caller-owned id to upsert a document in place (the update path:
+     * same id, overwrite). Omit to have the host mint a fresh document id.
+     */
+    documentId?: string;
+    /**
+     * Opaque provenance carried with the document (e.g. `{ rowId, fileId }`).
+     * Round-tripped verbatim on query/get; never interpreted by the host.
+     */
+    metadata?: Record<string, unknown>;
+    /** Override the stored creation timestamp (defaults to now). */
+    createdAt?: number;
+}
+
+export declare interface IndexDocumentResult {
+    documentId: string;
+    provider: string;
+    model: string;
+    dimensions: number;
+}
+
+export declare interface IndexedDocument {
+    documentId: string;
+    text: string;
+    modality: "text" | "image" | "audio" | "video";
+    metadata?: Record<string, unknown>;
+    createdAt: number;
+}
+
+export declare interface IndexHit {
+    documentId: string;
+    score: number;
+    text: string;
+    modality: "text" | "image" | "audio" | "video";
+    metadata?: Record<string, unknown>;
+}
+
 /**
  * Context passed to `Plugin.init()` during bootstrap. Carries the resolved
  * config, a pino-compatible logger scoped to the plugin, a per-plugin
@@ -4760,6 +4866,7 @@ declare const messageMetadataSchema: z.ZodObject<{
     provenanceRequesterIdentifier: z.ZodOptional<z.ZodString>;
     automated: z.ZodOptional<z.ZodBoolean>;
     hidden: z.ZodOptional<z.ZodBoolean>;
+    voiceSessionTurn: z.ZodOptional<z.ZodBoolean>;
     messageKind: z.ZodOptional<z.ZodString>;
     backgroundToolCompletion: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
@@ -4840,7 +4947,7 @@ export declare interface ModelProfileInfo {
     readonly isMix: boolean;
 }
 
-declare type MultimodalEmbeddingInput = TextEmbeddingInput | ImageEmbeddingInput | AudioEmbeddingInput | VideoEmbeddingInput;
+export declare type MultimodalEmbeddingInput = TextEmbeddingInput | ImageEmbeddingInput | AudioEmbeddingInput | VideoEmbeddingInput;
 
 /**
  * Open a streaming transcription session against the configured STT provider
@@ -5392,6 +5499,16 @@ export declare function quarantineRefusedExchanges(messages: Message[]): {
     droppedExchanges: number;
 };
 
+/** Hybrid semantic search over the calling plugin's index only. */
+export declare function queryIndex(query: EmbeddingInput, opts?: QueryIndexOptions): Promise<IndexHit[]>;
+
+export declare interface QueryIndexOptions {
+    /** Max hits to return. Defaults to 10. */
+    limit?: number;
+    /** Per-branch prefetch depth for the hybrid fusion. */
+    prefetchLimit?: number;
+}
+
 export declare interface RedactedThinkingContent {
     type: "redacted_thinking";
     data: string;
@@ -5410,6 +5527,9 @@ export declare interface RedactedThinkingContent {
  */
 export declare const REFUSAL_FALLBACK_TEXT = "Sorry \u2014 I wasn't able to generate a response to that. Please try rephrasing or asking in a different way.";
 
+/** Remove one document from the calling plugin's index. */
+export declare function removeDocument(documentId: string): Promise<void>;
+
 declare type ResolutionFallbackReason = "missing" | "disabled" | "incomplete";
 
 /**
@@ -5446,7 +5566,9 @@ declare type ResolutionFallbackReason = "missing" | "disabled" | "incomplete";
  * sits at the top of the chain for every call site.
  *
  * Profile names are resolved against the effective profile catalog
- * (code-defined defaults + workspace `llm.profiles`; see `getEffectiveProfile`).
+ * (code-defined defaults + workspace `llm.profiles`), with default profile
+ * keys resolved through `llm.defaultProvider`'s column of the intent ×
+ * provider matrix (see `resolveDefaultProfileForProvider`).
  * A "mix" profile is expanded to one of its arms by a seeded weighted pick (see
  * `resolveProfileFragment` and `opts.selectionSeed`), uniformly wherever a name
  * is dereferenced. Missing references silently fall through (no throw) so the
@@ -5905,12 +6027,19 @@ declare interface SkillInstallMeta {
  * - `workspace`: user-authored skill living in a conversation's working dir.
  * - `extra`: third-party directory roots passed via `loadSkillCatalog`'s
  *   `extraDirs` argument (primarily for tests).
- * - `plugin`: shipped on disk inside an installed plugin at
- *   `<workspaceDir>/plugins/<name>/skills/<id>/SKILL.md`, attributed back to
- *   the owning plugin via its `owner` descriptor.
+ * - `plugin`: shipped on disk inside a plugin: an installed one at
+ *   `<workspaceDir>/plugins/<name>/skills/<id>/SKILL.md`, or an in-process
+ *   default at `plugins/defaults/<dir>/skills/<id>/SKILL.md`, attributed back
+ *   to the owning plugin via its `owner` descriptor.
  */
 declare type SkillSource = "bundled" | "managed" | "workspace" | "extra" | "plugin";
 
+/** Sparse vector representation: parallel arrays of term indices and weights. */
+export declare interface SparseEmbedding {
+    indices: number[];
+    values: number[];
+}
+
 /**
  * The full `stop` context a hook receives — the dispatching call site's
  * {@link StopInputContext} plus the pipeline-stamped {@link BaseHookContext}
@@ -6209,7 +6338,7 @@ export declare interface TextContent {
     text: string;
 }
 
-declare interface TextEmbeddingInput {
+export declare interface TextEmbeddingInput {
     type: "text";
     text: string;
 }
@@ -6872,7 +7001,7 @@ declare interface UserPromptSubmitInputContext {
     latestMessages: Message[];
 }
 
-declare interface VideoEmbeddingInput {
+export declare interface VideoEmbeddingInput {
     type: "video";
     data: Buffer;
     mimeType: string;
@@ -6911,7 +7040,7 @@ declare interface WebSearchMetadata {
     errorMessage?: string;
 }
 
-declare type WebSearchProviderId = "anthropic-native" | "brave" | "perplexity" | "tavily" | "firecrawl";
+declare type WebSearchProviderId = "anthropic-native" | "brave" | "perplexity" | "tavily" | "keenable" | "firecrawl";
 
 declare interface WebSearchResultItem {
     rank: number;

package/index.js

@@ -13,16 +13,20 @@ export const buildMessageExcerpt = api.buildMessageExcerpt;
 export const createLiveVoiceConnection = api.createLiveVoiceConnection;
 export const deleteConversation = api.deleteConversation;
 export const doesSupportVision = api.doesSupportVision;
+export const embed = api.embed;
 export const embedAndUpsert = api.embedAndUpsert;
 export const extractTextFromStoredMessageContent = api.extractTextFromStoredMessageContent;
+export const generateSparseEmbedding = api.generateSparseEmbedding;
 export const getAssistantName = api.getAssistantName;
 export const getConfiguredProvider = api.getConfiguredProvider;
 export const getConversation = api.getConversation;
 export const getConversationDirPath = api.getConversationDirPath;
+export const getDocument = api.getDocument;
 export const getMessages = api.getMessages;
 export const getModelProfiles = api.getModelProfiles;
 export const getWorkspaceDir = api.getWorkspaceDir;
 export const hasLexicalTokens = api.hasLexicalTokens;
+export const indexDocument = api.indexDocument;
 export const isConversationProcessing = api.isConversationProcessing;
 export const isMaxTokensStopReason = api.isMaxTokensStopReason;
 export const isToolResultMessage = api.isToolResultMessage;
@@ -35,6 +39,8 @@ export const openTranscriptionSession = api.openTranscriptionSession;
 export const parseMessageMetadata = api.parseMessageMetadata;
 export const publishEvent = api.publishEvent;
 export const quarantineRefusedExchanges = api.quarantineRefusedExchanges;
+export const queryIndex = api.queryIndex;
+export const removeDocument = api.removeDocument;
 export const resolveCredential = api.resolveCredential;
 export const resolveMediaSourceData = api.resolveMediaSourceData;
 export const resolveUserName = api.resolveUserName;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.11.0-staging.3",
+  "version": "0.11.1-dev.202608010027.2cfe358",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",