@vellumai/plugin-api 0.11.3 → 0.11.4-dev.202608190019.b94dbf2

package/index.d.ts

@@ -127,9 +127,9 @@ declare const AssistantConfigSchema: z.ZodObject<{
         inference: z.ZodDefault<z.ZodObject<{}, z.core.$strip>>;
         "image-generation": z.ZodDefault<z.ZodObject<{
             provider: z.ZodDefault<z.ZodEnum<{
+                vellum: "vellum";
                 openai: "openai";
                 gemini: "gemini";
-                vellum: "vellum";
             }>>;
             model: z.ZodDefault<z.ZodString>;
         }, z.core.$strip>>;
@@ -147,6 +147,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
             provider: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
                 vellum: "vellum";
                 deepgram: "deepgram";
+                "deepgram-flux": "deepgram-flux";
                 "google-gemini": "google-gemini";
                 "openai-whisper": "openai-whisper";
                 xai: "xai";
@@ -593,33 +594,16 @@ declare const AssistantConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     llm: z.ZodDefault<z.ZodObject<{
         profiles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
-            provider: z.ZodOptional<z.ZodEnum<{
-                openai: "openai";
-                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";
-            }>>;
+            provider: z.ZodOptional<z.ZodString>;
             model: z.ZodOptional<z.ZodString>;
             maxTokens: z.ZodOptional<z.ZodNumber>;
             effort: z.ZodOptional<z.ZodEnum<{
                 low: "low";
                 medium: "medium";
                 high: "high";
+                none: "none";
                 xhigh: "xhigh";
                 max: "max";
-                none: "none";
             }>>;
             speed: z.ZodOptional<z.ZodEnum<{
                 standard: "standard";
@@ -672,8 +656,8 @@ declare const AssistantConfigSchema: z.ZodObject<{
             }>>;
             disableCache: z.ZodOptional<z.ZodBoolean>;
             source: z.ZodOptional<z.ZodEnum<{
-                managed: "managed";
                 user: "user";
+                managed: "managed";
             }>>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             description: z.ZodOptional<z.ZodString>;
@@ -725,40 +709,23 @@ declare const AssistantConfigSchema: z.ZodObject<{
             skillCategoryInference: "skillCategoryInference";
             inference: "inference";
             vision: "vision";
-            voiceFrontDecision: "voiceFrontDecision";
+            voiceProgressNarration: "voiceProgressNarration";
             voiceFrontDoor: "voiceFrontDoor";
             trustRuleSuggestion: "trustRuleSuggestion";
             homeGreeting: "homeGreeting";
             homeSuggestedPrompts: "homeSuggestedPrompts";
             workflowLeaf: "workflowLeaf";
         }> & z.core.$partial, z.ZodObject<{
-            provider: z.ZodOptional<z.ZodEnum<{
-                openai: "openai";
-                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";
-            }>>;
+            provider: z.ZodOptional<z.ZodString>;
             model: z.ZodOptional<z.ZodString>;
             maxTokens: z.ZodOptional<z.ZodNumber>;
             effort: z.ZodOptional<z.ZodEnum<{
                 low: "low";
                 medium: "medium";
                 high: "high";
+                none: "none";
                 xhigh: "xhigh";
                 max: "max";
-                none: "none";
             }>>;
             speed: z.ZodOptional<z.ZodEnum<{
                 standard: "standard";
@@ -816,22 +783,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
         advisorProfile: z.ZodOptional<z.ZodString>;
         defaultProvider: z.ZodCatch<z.ZodOptional<z.ZodObject<{
             provider: z.ZodEnum<{
-                openai: "openai";
-                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";
+                [x: string]: string;
             }>;
             connectionName: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
@@ -1091,8 +1043,6 @@ declare const AssistantConfigSchema: z.ZodObject<{
             endpointDecisionTimeoutMs: z.ZodDefault<z.ZodNumber>;
             endpointExtensionMs: z.ZodDefault<z.ZodNumber>;
             endpointMaxExtensions: z.ZodDefault<z.ZodNumber>;
-            ackFirstDeltaTimeoutMs: z.ZodDefault<z.ZodNumber>;
-            ackGenerationTimeoutMs: z.ZodDefault<z.ZodNumber>;
             progress: z.ZodDefault<z.ZodObject<{
                 enabled: z.ZodDefault<z.ZodBoolean>;
                 opsThreshold: z.ZodDefault<z.ZodNumber>;
@@ -1103,6 +1053,15 @@ declare const AssistantConfigSchema: z.ZodObject<{
                 generationTimeoutMs: z.ZodDefault<z.ZodNumber>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        flux: z.ZodDefault<z.ZodObject<{
+            turnEnd: z.ZodDefault<z.ZodObject<{
+                enabled: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strip>>;
+            model: z.ZodDefault<z.ZodString>;
+            eotThreshold: z.ZodDefault<z.ZodNumber>;
+            eagerEotThreshold: z.ZodOptional<z.ZodNumber>;
+            eotTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
         maxSessionDurationSeconds: z.ZodDefault<z.ZodNumber>;
         archiveAudio: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
@@ -1212,8 +1171,8 @@ declare const AssistantConfigSchema: z.ZodObject<{
     plugins: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     pluginUpdates: z.ZodDefault<z.ZodObject<{
         mode: z.ZodDefault<z.ZodEnum<{
-            auto: "auto";
             manual: "manual";
+            auto: "auto";
         }>>;
         strategy: z.ZodDefault<z.ZodEnum<{
             theirs: "theirs";
@@ -1251,6 +1210,12 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
     seq: z.ZodOptional<z.ZodNumber>;
     emittedAt: z.ZodString;
     message: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"acp_auth_required">;
+        acpSessionId: z.ZodString;
+        authCode: z.ZodString;
+        agent: z.ZodString;
+        parentToolUseId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"acp_session_completed">;
         acpSessionId: z.ZodString;
         stopReason: z.ZodEnum<{
@@ -1275,12 +1240,12 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         type: z.ZodLiteral<"acp_session_update">;
         acpSessionId: z.ZodString;
         updateType: z.ZodEnum<{
+            plan: "plan";
             agent_message_chunk: "agent_message_chunk";
             agent_thought_chunk: "agent_thought_chunk";
             user_message_chunk: "user_message_chunk";
             tool_call: "tool_call";
             tool_call_update: "tool_call_update";
-            plan: "plan";
         }>;
         content: z.ZodOptional<z.ZodString>;
         toolCallId: z.ZodOptional<z.ZodString>;
@@ -1366,8 +1331,8 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         id: z.ZodString;
         conversationId: z.ZodString;
         status: z.ZodEnum<{
-            completed: "completed";
             cancelled: "cancelled";
+            completed: "completed";
             failed: "failed";
         }>;
         exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -1459,18 +1424,18 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         conversationId: z.ZodString;
         requestId: z.ZodString;
         state: z.ZodEnum<{
-            timed_out: "timed_out";
             pending: "pending";
             approved: "approved";
             denied: "denied";
+            timed_out: "timed_out";
             resolved_stale: "resolved_stale";
         }>;
         source: z.ZodEnum<{
+            timeout: "timeout";
             system: "system";
             button: "button";
             inline_nl: "inline_nl";
             auto_deny: "auto_deny";
-            timeout: "timeout";
         }>;
         causedByRequestId: z.ZodOptional<z.ZodString>;
         decisionText: z.ZodOptional<z.ZodString>;
@@ -1545,9 +1510,9 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"conversation_list_invalidated">;
         reason: z.ZodEnum<{
+            deleted: "deleted";
             created: "created";
             renamed: "renamed";
-            deleted: "deleted";
             reordered: "reordered";
             seen_changed: "seen_changed";
         }>;
@@ -1590,9 +1555,9 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
             enabled: z.ZodBoolean;
             state: z.ZodEnum<{
                 unknown: "unknown";
+                ok: "ok";
                 disabled: "disabled";
                 critical: "critical";
-                ok: "ok";
                 warning: "warning";
             }>;
             locked: z.ZodBoolean;
@@ -1707,8 +1672,8 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         hookName: z.ZodString;
         owner: z.ZodObject<{
             kind: z.ZodEnum<{
-                plugin: "plugin";
                 workspace: "workspace";
+                plugin: "plugin";
             }>;
             id: z.ZodString;
         }, z.core.$strip>;
@@ -1833,8 +1798,8 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         targetClientId: z.ZodOptional<z.ZodString>;
         operation: z.ZodLiteral<"read">;
         path: z.ZodString;
-        offset: z.ZodOptional<z.ZodNumber>;
-        limit: z.ZodOptional<z.ZodNumber>;
+        startIndex: z.ZodOptional<z.ZodNumber>;
+        maxChars: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"host_file_request">;
         requestId: z.ZodString;
@@ -1900,9 +1865,9 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         requestId: z.ZodString;
         conversationId: z.ZodString;
         state: z.ZodEnum<{
+            approved: "approved";
             cancelled: "cancelled";
             superseded: "superseded";
-            approved: "approved";
             rejected: "rejected";
             answered: "answered";
         }>;
@@ -2195,9 +2160,9 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         type: z.ZodLiteral<"subagent_status_changed">;
         subagentId: z.ZodString;
         status: z.ZodEnum<{
+            pending: "pending";
             completed: "completed";
             failed: "failed";
-            pending: "pending";
             running: "running";
             awaiting_input: "awaiting_input";
             aborted: "aborted";
@@ -2671,13 +2636,14 @@ declare const AssistantEventPublishOptionsSchema: z.ZodObject<{
     }>>;
     targetClientId: z.ZodOptional<z.ZodString>;
     targetInterfaceId: z.ZodOptional<z.ZodEnum<{
-        telegram: "telegram";
         phone: "phone";
+        a2a: "a2a";
         whatsapp: "whatsapp";
+        discord: "discord";
+        telegram: "telegram";
         slack: "slack";
         email: "email";
-        a2a: "a2a";
-        discord: "discord";
+        plugin: "plugin";
         macos: "macos";
         ios: "ios";
         cli: "cli";
@@ -2702,6 +2668,12 @@ declare const AssistantEventPublishOptionsSchema: z.ZodObject<{
  * migration recipe.
  */
 declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"acp_auth_required">;
+    acpSessionId: z.ZodString;
+    authCode: z.ZodString;
+    agent: z.ZodString;
+    parentToolUseId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"acp_session_completed">;
     acpSessionId: z.ZodString;
     stopReason: z.ZodEnum<{
@@ -2726,12 +2698,12 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"acp_session_update">;
     acpSessionId: z.ZodString;
     updateType: z.ZodEnum<{
+        plan: "plan";
         agent_message_chunk: "agent_message_chunk";
         agent_thought_chunk: "agent_thought_chunk";
         user_message_chunk: "user_message_chunk";
         tool_call: "tool_call";
         tool_call_update: "tool_call_update";
-        plan: "plan";
     }>;
     content: z.ZodOptional<z.ZodString>;
     toolCallId: z.ZodOptional<z.ZodString>;
@@ -2817,8 +2789,8 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodString;
     conversationId: z.ZodString;
     status: z.ZodEnum<{
-        completed: "completed";
         cancelled: "cancelled";
+        completed: "completed";
         failed: "failed";
     }>;
     exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -2910,18 +2882,18 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     conversationId: z.ZodString;
     requestId: z.ZodString;
     state: z.ZodEnum<{
-        timed_out: "timed_out";
         pending: "pending";
         approved: "approved";
         denied: "denied";
+        timed_out: "timed_out";
         resolved_stale: "resolved_stale";
     }>;
     source: z.ZodEnum<{
+        timeout: "timeout";
         system: "system";
         button: "button";
         inline_nl: "inline_nl";
         auto_deny: "auto_deny";
-        timeout: "timeout";
     }>;
     causedByRequestId: z.ZodOptional<z.ZodString>;
     decisionText: z.ZodOptional<z.ZodString>;
@@ -2996,9 +2968,9 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"conversation_list_invalidated">;
     reason: z.ZodEnum<{
+        deleted: "deleted";
         created: "created";
         renamed: "renamed";
-        deleted: "deleted";
         reordered: "reordered";
         seen_changed: "seen_changed";
     }>;
@@ -3041,9 +3013,9 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         enabled: z.ZodBoolean;
         state: z.ZodEnum<{
             unknown: "unknown";
+            ok: "ok";
             disabled: "disabled";
             critical: "critical";
-            ok: "ok";
             warning: "warning";
         }>;
         locked: z.ZodBoolean;
@@ -3158,8 +3130,8 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     hookName: z.ZodString;
     owner: z.ZodObject<{
         kind: z.ZodEnum<{
-            plugin: "plugin";
             workspace: "workspace";
+            plugin: "plugin";
         }>;
         id: z.ZodString;
     }, z.core.$strip>;
@@ -3284,8 +3256,8 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     targetClientId: z.ZodOptional<z.ZodString>;
     operation: z.ZodLiteral<"read">;
     path: z.ZodString;
-    offset: z.ZodOptional<z.ZodNumber>;
-    limit: z.ZodOptional<z.ZodNumber>;
+    startIndex: z.ZodOptional<z.ZodNumber>;
+    maxChars: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"host_file_request">;
     requestId: z.ZodString;
@@ -3351,9 +3323,9 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     requestId: z.ZodString;
     conversationId: z.ZodString;
     state: z.ZodEnum<{
+        approved: "approved";
         cancelled: "cancelled";
         superseded: "superseded";
-        approved: "approved";
         rejected: "rejected";
         answered: "answered";
     }>;
@@ -3646,9 +3618,9 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"subagent_status_changed">;
     subagentId: z.ZodString;
     status: z.ZodEnum<{
+        pending: "pending";
         completed: "completed";
         failed: "failed";
-        pending: "pending";
         running: "running";
         awaiting_input: "awaiting_input";
         aborted: "aborted";
@@ -4040,6 +4012,41 @@ declare interface BaseSubscriberEntry {
  */
 export declare function buildMessageExcerpt(rawContent: string, query: string): Promise<string>;
 
+/**
+ * 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:
+ *
+ * One id, `plugin`, does not name a surface: it names *every* surface a plugin
+ * brings. A plugin channel's real identity is the plugin, which is workspace
+ * state and cannot be a compile-time union member, so the plugin name travels
+ * in `sourceMetadata.plugin` and is prefixed onto every external id the gateway
+ * forwards (`imessage:+15551234567`). Two plugins therefore share a channel
+ * row — one admission floor, one set of channel-wide defaults — while their
+ * conversations, contacts, and trust records stay disjoint. See
+ * `gateway/src/channels/plugin-inbound.ts` for what that concedes.
+ *
+ * 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", "discord", "plugin"];
+
+declare type ChannelId = (typeof CHANNEL_IDS)[number];
+
 export declare const CLI_COMMAND_HELP: readonly CliCommandHelp[];
 
 declare interface CliArgumentHelp {
@@ -4145,6 +4152,43 @@ declare type ConfiguredProviderOptions = Pick<ResolveCallSiteOpts, "overrideProf
 
 export declare type ContentBlock = TextContent | ThinkingContent | RedactedThinkingContent | ImageContent | FileContent | ToolUseContent | ToolResultContent | ServerToolUseContent | WebSearchToolResultContent | UiSurfaceContent;
 
+/**
+ * The chat a turn belongs to, in the channel's own terms.
+ *
+ * Supplied instead of a `conversationId` when the caller knows where the
+ * message came from but not which conversation that is. The pair resolves to
+ * the same conversation an inbound message on those coordinates would land
+ * in, because it resolves through the same binding.
+ *
+ * That sameness is the reason this exists at all. A caller could keep its own
+ * `externalChatId -> conversationId` map and pass the id, and turns would run
+ * in the right place. What it could not do is make the rest of the assistant
+ * agree: conversation reset is addressed by channel coordinates
+ * (`handleDeleteConversation`), the deny lanes attach an access-request card
+ * by them (`findInboundConversationId`), and the conversation and session
+ * APIs read the channel, chat name and sender off the external binding. A
+ * private map is a second name for the same conversation, and everything
+ * keyed on the public one quietly misses.
+ */
+export declare interface ConversationChannelAddress {
+    /** Channel the message arrived on. */
+    sourceChannel: ChannelId;
+    /** The chat, in the channel's own id space. */
+    externalChatId: string;
+    /**
+     * Thread within the chat, where the channel has threads. Only Slack and
+     * Telegram scope a conversation by thread; elsewhere this is carried as
+     * binding metadata and does not split the conversation.
+     */
+    externalThreadId?: string | null;
+    /** Human-readable chat name, for the conversation list. */
+    externalChatName?: string | null;
+    /** Who sent it, in the channel's id space. */
+    externalUserId?: string | null;
+    displayName?: string | null;
+    username?: string | null;
+}
+
 /** How a conversation was created / its execution mode. */
 declare type ConversationCreateType = "standard" | "background" | "scheduled";
 
@@ -4240,8 +4284,9 @@ export declare function createLiveVoiceConnection(options: {
  *
  * ## Plugin scoping
  *
- * When a plugin is in context — its hook or tool is executing, tracked by
- * {@link ../plugins/plugin-execution-context.getCurrentPluginName} — resolution
+ * When a plugin is in context (its hook, tool, or one of its own
+ * `/x/plugins/<name>/` routes is executing, tracked by
+ * {@link ../plugins/plugin-execution-context.getCurrentPluginName}), resolution
  * is restricted: the plugin may only resolve credentials whose `field` equals
  * the plugin's own manifest name. A plugin named `acme` can therefore read
  * `openai/acme` or `stripe/acme` but not `openai/api_key`. Outside any plugin
@@ -4257,6 +4302,44 @@ export declare class CredentialResolutionError extends Error {
     constructor(message: string);
 }
 
+/**
+ * Plugin-facing credential storage.
+ *
+ * {@link storeCredential} writes a credential's plaintext to the secure store,
+ * the same write `assistant credentials set` performs, naming it either by an
+ * existing credential's UUID or by a `"service/field"` string, the same
+ * vocabulary {@link ./resolve-credential.resolveCredential} reads back. A
+ * plugin that obtains a token for itself (an OAuth exchange it drives, a key a
+ * user hands it through its own route) persists it here instead of inventing
+ * its own on-disk secret file.
+ *
+ * ## Plugin scoping
+ *
+ * A plugin may only write credentials whose `field` equals its manifest name,
+ * so `acme` writes `openai/acme` or `stripe/acme` but never `openai/api_key`.
+ * The name comes from the execution context
+ * ({@link ../plugins/plugin-execution-context.getCurrentPluginName}), which the
+ * host establishes around a plugin's hook, tool, and route invocations.
+ *
+ * Unlike the read path, this **fails closed**: with no plugin in context there
+ * is nobody to scope the write to, so it is refused rather than treated as an
+ * unscoped host write. A plugin's module body is evaluated by the loader
+ * outside any context, and an unscoped branch there would let top-level code
+ * overwrite the user's own credentials. Host-internal callers that legitimately
+ * write unscoped (the `credentials/set` route, the CLI behind it) compose
+ * {@link ../tools/credentials/store.storeCredentialValue} directly. This
+ * matches the plugin-owned index (`indexDocument`), which likewise requires a
+ * context because a write with no owner has nothing to attribute.
+ */
+/**
+ * Raised when a credential cannot be stored: the reference is malformed, the
+ * value is empty or invalid for its service, the secure backend rejected the
+ * write, or the calling plugin is not permitted to write the credential.
+ */
+export declare class CredentialStoreError extends Error {
+    constructor(message: string);
+}
+
 /**
  * Delete a conversation, yielding the event loop between row batches, and
  * enqueue vector-store cleanup for the memory segments and summaries the
@@ -4613,7 +4696,7 @@ declare interface InsertedMessage {
     deduplicated: boolean;
 }
 
-declare const INTERFACE_IDS: readonly ["macos", "ios", "cli", "telegram", "phone", "web", "whatsapp", "slack", "email", "chrome-extension", "a2a", "discord", "route"];
+declare const INTERFACE_IDS: readonly ["macos", "ios", "cli", "telegram", "phone", "web", "whatsapp", "slack", "email", "chrome-extension", "a2a", "discord", "route", "plugin"];
 
 declare type InterfaceId = (typeof INTERFACE_IDS)[number];
 
@@ -4834,14 +4917,34 @@ declare interface LiveVoiceMetricsServerFrame extends LiveVoiceServerFrameBase {
     /** End-of-speech (utterance_end, or ptt_release in manual mode) to first TTS audio. */
     readonly roundTripMs: number | null;
     readonly totalMs: number | null;
+    /**
+     * End-of-turn latency: the local VAD speech-stop mark to the moment the
+     * turn committed. Recorded on every committed turn, and measured from the
+     * same anchor whichever decider owned the boundary, so front-door and Flux
+     * turns are one comparable population. Absent on a turn that never
+     * committed and in push-to-talk mode, where there is no local VAD
+     * speech-stop mark.
+     */
+    readonly endpointCommitLatencyMs?: number;
     /**
      * Semantic-endpointing "hold" decisions taken during the turn. Present only
      * when the endpoint decider was consulted (otherwise the field is absent,
      * keeping frames unchanged).
      */
     readonly endpointHoldCount?: number;
-    /** Worst endpoint-decision latency observed during the turn. */
+    /**
+     * Worst endpoint-decision latency observed during the turn. It spans only
+     * the decider's own work, and the two deciders start it at different
+     * moments, so it is a diagnostic rather than a cross-path comparison: read
+     * `endpointCommitLatencyMs` for that.
+     */
     readonly endpointDecisionMaxLatencyMs?: number;
+    /**
+     * Which path decided the turn's endpoint: the front-door hold verdict or
+     * the STT provider's model-integrated end-of-turn. Present under the same
+     * condition as the two fields above.
+     */
+    readonly endpointDecisionSource?: "front-door" | "provider";
     /** Which floor-holding ack actually spoke during the turn, if any. */
     readonly ackSpoken?: "first_delta" | "tool_use";
     /**
@@ -5015,7 +5118,7 @@ declare const LLMCallSiteEnum: z.ZodEnum<{
     skillCategoryInference: "skillCategoryInference";
     inference: "inference";
     vision: "vision";
-    voiceFrontDecision: "voiceFrontDecision";
+    voiceProgressNarration: "voiceProgressNarration";
     voiceFrontDoor: "voiceFrontDoor";
     trustRuleSuggestion: "trustRuleSuggestion";
     homeGreeting: "homeGreeting";
@@ -5058,29 +5161,31 @@ declare type MessageMetadata_2 = z.infer<typeof messageMetadataSchema>;
 
 declare const messageMetadataSchema: z.ZodObject<{
     userMessageChannel: z.ZodOptional<z.ZodEnum<{
-        vellum: "vellum";
-        platform: "platform";
-        telegram: "telegram";
         phone: "phone";
+        platform: "platform";
+        a2a: "a2a";
+        vellum: "vellum";
         whatsapp: "whatsapp";
+        discord: "discord";
+        telegram: "telegram";
         slack: "slack";
         email: "email";
-        a2a: "a2a";
-        discord: "discord";
+        plugin: "plugin";
     }>>;
     assistantMessageChannel: z.ZodOptional<z.ZodEnum<{
-        vellum: "vellum";
-        platform: "platform";
-        telegram: "telegram";
         phone: "phone";
+        platform: "platform";
+        a2a: "a2a";
+        vellum: "vellum";
         whatsapp: "whatsapp";
+        discord: "discord";
+        telegram: "telegram";
         slack: "slack";
         email: "email";
-        a2a: "a2a";
-        discord: "discord";
+        plugin: "plugin";
     }>>;
-    userMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route" | null, string>> & z.ZodType<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string>>>;
-    assistantMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route" | null, string>> & z.ZodType<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string>>>;
+    userMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"phone" | "a2a" | "whatsapp" | "discord" | "telegram" | "slack" | "email" | "plugin" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route" | null, string>> & z.ZodType<"phone" | "a2a" | "whatsapp" | "discord" | "telegram" | "slack" | "email" | "plugin" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"phone" | "a2a" | "whatsapp" | "discord" | "telegram" | "slack" | "email" | "plugin" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string>>>;
+    assistantMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"phone" | "a2a" | "whatsapp" | "discord" | "telegram" | "slack" | "email" | "plugin" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route" | null, string>> & z.ZodType<"phone" | "a2a" | "whatsapp" | "discord" | "telegram" | "slack" | "email" | "plugin" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"phone" | "a2a" | "whatsapp" | "discord" | "telegram" | "slack" | "email" | "plugin" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string>>>;
     client: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     clientOsFromRequest: z.ZodOptional<z.ZodBoolean>;
     subagentNotification: z.ZodOptional<z.ZodObject<{
@@ -5108,15 +5213,16 @@ declare const messageMetadataSchema: z.ZodObject<{
     }>>;
     model: z.ZodOptional<z.ZodString>;
     provenanceSourceChannel: z.ZodOptional<z.ZodEnum<{
-        vellum: "vellum";
-        platform: "platform";
-        telegram: "telegram";
         phone: "phone";
+        platform: "platform";
+        a2a: "a2a";
+        vellum: "vellum";
         whatsapp: "whatsapp";
+        discord: "discord";
+        telegram: "telegram";
         slack: "slack";
         email: "email";
-        a2a: "a2a";
-        discord: "discord";
+        plugin: "plugin";
     }>>;
     provenanceGuardianExternalUserId: z.ZodOptional<z.ZodString>;
     provenanceRequesterIdentifier: z.ZodOptional<z.ZodString>;
@@ -5133,8 +5239,8 @@ declare const messageMetadataSchema: z.ZodObject<{
         command: z.ZodString;
         startedAt: z.ZodNumber;
         status: z.ZodEnum<{
-            completed: "completed";
             cancelled: "cancelled";
+            completed: "completed";
             failed: "failed";
         }>;
         exitCode: z.ZodNullable<z.ZodNumber>;
@@ -5804,7 +5910,7 @@ export declare const REFUSAL_FALLBACK_TEXT = "Sorry \u2014 I wasn't able to gene
 /** Remove one document from the calling plugin's index. */
 export declare function removeDocument(documentId: string): Promise<void>;
 
-declare type ResolutionFallbackReason = "missing" | "disabled" | "incomplete";
+declare type ResolutionFallbackReason = "missing" | "disabled" | "incomplete" | "unresolvable";
 
 /**
  * Resolves a fully-specified `LLMConfigBase` for a given call site.
@@ -5860,6 +5966,15 @@ declare type ResolutionFallbackReason = "missing" | "disabled" | "incomplete";
  */
 declare interface ResolveCallSiteOpts {
     overrideProfile?: string;
+    /**
+     * Whether a profile's provider value can actually dispatch: a known
+     * vendor, or a connection entry row. Selection is pure and DB-blind, so
+     * dispatch-side callers supply this (see `dispatchProviderResolvable` in
+     * `connection-resolution.ts`); a profile failing it is unusable and
+     * selection falls through to the next rung, keeping model and transport
+     * coherent. When absent, every provider is assumed resolvable.
+     */
+    isResolvableProvider?: (provider: string) => boolean;
     /**
      * Float `overrideProfile` above the call-site layers for non-main-agent call
      * sites. Retained for API compatibility; under single-winner selection the
@@ -5966,6 +6081,21 @@ export declare function resolveMediaSourceData(source: MediaSource_2): {
     media_type: string;
 } | null;
 
+/**
+ * Resolve the redirect URI an authorization server should send the user
+ * back to.
+ *
+ * Takes no arguments on purpose: every caller shares one route, so there
+ * is nothing to vary. That is what makes the URI stable across callers and
+ * across attempts, which is what an exact-match `redirect_uri` check needs.
+ *
+ * @throws when no public ingress is configured and the assistant is not
+ *   connected to the platform. There is no URL that would work in that
+ *   case, and returning a plausible one produces an authorization request
+ *   whose callback silently never arrives.
+ */
+export declare function resolveOauthCallbackUrl(): Promise<string>;
+
 /**
  * Read the user's display name from the guardian's persona file
  * (`users/<slug>.md`, resolved via the guardian-delivery binding), falling
@@ -5992,6 +6122,23 @@ export declare function resolveUserName(workspaceDir: string): string | null;
  */
 export declare function resolveWebhookUrl(options: WebhookUrlOptions): Promise<string>;
 
+declare type RiskAllowlistOption = z.infer<typeof RiskAllowlistOptionSchema>;
+
+/** Minimatch ladder for the "always allow" prompt option (what a rule matches). */
+declare const RiskAllowlistOptionSchema: z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodString;
+    pattern: z.ZodString;
+}, z.core.$strip>;
+
+declare type RiskDirectoryScopeOption = z.infer<typeof RiskDirectoryScopeOptionSchema>;
+
+/** Directory ladder for filesystem operations; `scope` is a path glob or `everywhere`. */
+declare const RiskDirectoryScopeOptionSchema: z.ZodObject<{
+    scope: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>;
+
 export declare enum RiskLevel {
     Low = "low",
     Medium = "medium",
@@ -6022,9 +6169,22 @@ export declare function runConversationTurn(options: RunConversationTurnOptions)
 export declare interface RunConversationTurnOptions {
     /**
      * Conversation to run the turn in. If omitted, a new conversation is
-     * created (its ID is generated with `uuidv7` and returned in the result).
+     * created (its ID is generated with `uuidv7` and returned in the result),
+     * unless {@link RunConversationTurnOptions.channel} says which chat this
+     * belongs to, in which case that chat's conversation is used.
      */
     conversationId?: string;
+    /**
+     * The chat this turn belongs to, resolved to a conversation and bound to
+     * the channel. See {@link ConversationChannelAddress}.
+     *
+     * Ignored when `conversationId` is given: an explicit conversation is the
+     * caller saying which one, and re-resolving would overrule it. A caller
+     * that wants both the binding and a conversation of its own choosing is
+     * describing two different conversations, which is a bug worth surfacing
+     * as one rather than silently picking a winner.
+     */
+    channel?: ConversationChannelAddress;
     /**
      * User message content blocks for this turn. Text blocks become the
      * user message body; image/file blocks are resolved to inline
@@ -6406,6 +6566,43 @@ declare interface StopInputContext {
     readonly exitReason: AgentLoopExitReason;
 }
 
+/**
+ * Store a credential's plaintext value, creating it or replacing the value of
+ * an existing one.
+ *
+ * @param ref A credential UUID (an existing credential) or a `"service/field"`
+ *   string (created when no such credential exists).
+ * @param value The plaintext value. Edge whitespace is trimmed.
+ * @returns The identity of the stored credential, which
+ *   {@link ./resolve-credential.resolveCredential} accepts as a ref.
+ * @throws {CredentialStoreError} when no plugin is in context, the ref is
+ *   malformed or names no credential, the value is empty or invalid for its
+ *   service, the store rejects the write, or the calling plugin is not scoped
+ *   to the credential.
+ */
+export declare function storeCredential(ref: string, value: string, options?: StoreCredentialOptions): Promise<StoredCredentialRef>;
+
+export declare interface StoreCredentialOptions {
+    /** Human-friendly alias shown in credential listings. */
+    label?: string;
+    /** What the credential is for, surfaced to the agent. */
+    description?: string;
+    /**
+     * Skip the retroactive sweep that removes the value from recent transcripts.
+     * The sweep exists because a secret is often pasted into chat before it is
+     * stored; pass `true` only for a value that provably never transited a
+     * conversation, such as a token minted by an OAuth refresh.
+     */
+    skipTranscriptScrub?: boolean;
+}
+
+/** Identity of the credential that was written. */
+export declare interface StoredCredentialRef {
+    credentialId: string;
+    service: string;
+    field: string;
+}
+
 /**
  * Daemon-hosted streaming transcriber contract.
  *
@@ -6511,13 +6708,32 @@ export declare type SttErrorCategory =
  * Canonical provider identifiers for daemon-hosted STT backends.
  * Extend this union as new providers are integrated.
  */
-export declare type SttProviderId = "openai-whisper" | "deepgram" | "google-gemini" | "xai" | "vellum";
+export declare type SttProviderId = "openai-whisper" | "deepgram"
+/**
+* Deepgram's Flux conversational speech model. Shares the `deepgram`
+* credential and is streaming-only: Flux has no batch endpoint.
+*/
+| "deepgram-flux" | "google-gemini" | "xai" | "vellum";
 
 /** The streaming session has closed (no more events will be emitted). */
 export declare interface SttStreamServerClosedEvent {
     readonly type: "closed";
 }
 
+/**
+ * The provider's turn model speculates the user has finished, ahead of its
+ * committed end-of-turn decision. A {@link SttStreamServerTurnResumedEvent}
+ * retracts the speculation; a {@link SttStreamServerTurnEndEvent} confirms it.
+ *
+ * Emitted only by providers with model-integrated turn detection; providers
+ * without it never emit these.
+ */
+export declare interface SttStreamServerEagerTurnEndEvent {
+    readonly type: "eager-turn-end";
+    /** Transcript text as of the speculated turn end. */
+    readonly text: string;
+}
+
 /** An error occurred during streaming transcription. */
 export declare interface SttStreamServerErrorEvent {
     readonly type: "error";
@@ -6534,7 +6750,7 @@ export declare interface SttStreamServerErrorEvent {
  * and final transcripts, errors, and session lifecycle signals in a
  * type-safe manner.
  */
-export declare type SttStreamServerEvent = SttStreamServerPartialEvent | SttStreamServerFinalEvent | SttStreamServerFinalizedEvent | SttStreamServerErrorEvent | SttStreamServerClosedEvent;
+export declare type SttStreamServerEvent = SttStreamServerPartialEvent | SttStreamServerFinalEvent | SttStreamServerFinalizedEvent | SttStreamServerTurnStartEvent | SttStreamServerEagerTurnEndEvent | SttStreamServerTurnResumedEvent | SttStreamServerTurnEndEvent | SttStreamServerErrorEvent | SttStreamServerClosedEvent;
 
 /**
  * A final (committed) transcript — this segment will not be revised.
@@ -6600,6 +6816,59 @@ export declare interface SttStreamServerPartialEvent {
     readonly languages?: readonly string[];
 }
 
+/**
+ * The provider's turn model committed an end of turn: the user has finished
+ * speaking and a reply can be dispatched.
+ *
+ * Emitted only by providers with model-integrated turn detection; providers
+ * without it never emit these.
+ */
+export declare interface SttStreamServerTurnEndEvent {
+    readonly type: "turn-end";
+    /** Committed transcript text for the completed turn. */
+    readonly text: string;
+    /**
+     * Provider-emitted end-of-turn confidence in [0, 1]. Undefined when the
+     * provider does not surface a score.
+     */
+    readonly confidence?: number;
+    /**
+     * Provider's index for the turn being closed, matching the
+     * {@link SttStreamServerTurnStartEvent} that opened it. A consumer can
+     * compare it against the newest turn it has seen opened to tell an
+     * end-of-turn for the turn still in progress from one the provider has
+     * already superseded. Undefined when the provider does not number its
+     * turns.
+     */
+    readonly turnIndex?: number;
+}
+
+/**
+ * The user kept speaking after an {@link SttStreamServerEagerTurnEndEvent},
+ * retracting the speculated turn end.
+ *
+ * Emitted only by providers with model-integrated turn detection; providers
+ * without it never emit these.
+ */
+export declare interface SttStreamServerTurnResumedEvent {
+    readonly type: "turn-resumed";
+}
+
+/**
+ * The provider's turn model detected the start of a user turn.
+ *
+ * Emitted only by providers with model-integrated turn detection; providers
+ * without it never emit these.
+ */
+export declare interface SttStreamServerTurnStartEvent {
+    readonly type: "turn-start";
+    /**
+     * Provider's index for the turn being opened, monotonically increasing
+     * within a stream. Undefined when the provider does not number its turns.
+     */
+    readonly turnIndex?: number;
+}
+
 declare type SubscriberEntry = ClientEntry | ProcessEntry;
 
 /** Input shape for `subscribe()` — hub fills `active`, `connectedAt`, `lastActiveAt`, `connectionId` and defaults `filter`/`onEvict`. */
@@ -7112,16 +7381,9 @@ export declare interface ToolExecutionResult {
      * wildcards) — what the gateway actually matches against. Mirrors
      * the `allowlistOptions` field on `ConfirmationRequest` SSE events.
      */
-    riskAllowlistOptions?: Array<{
-        label: string;
-        description: string;
-        pattern: string;
-    }>;
+    riskAllowlistOptions?: RiskAllowlistOption[];
     /** Directory scope ladder for the rule editor (narrowest to broadest). */
-    riskDirectoryScopeOptions?: Array<{
-        scope: string;
-        label: string;
-    }>;
+    riskDirectoryScopeOptions?: RiskDirectoryScopeOption[];
     /** Structured activity metadata for client rendering (web search, web fetch, etc).
      *  Populated by daemon-internal tools; plugins must not set this. */
     activityMetadata?: ToolActivityMetadata;
@@ -7336,6 +7598,11 @@ declare interface UserPromptSubmitInputContext {
      * user speech (e.g. title generation) should skip these turns.
      */
     readonly isHiddenPrompt?: boolean;
+    /**
+     * Daemon-authored kind from the triggering row's `metadata.messageKind`,
+     * when the turn needs a more specific identity than role or visibility.
+     */
+    readonly messageKind?: string;
     /**
      * The user's original message list, immutable for the hook. Plugins
      * may snapshot or compare against this but MUST NOT mutate it.
@@ -7354,6 +7621,13 @@ export declare interface VideoEmbeddingInput {
     mimeType: string;
 }
 
+/**
+ * Message kind for the hidden user row that starts a voice escalation leg.
+ * Hooks use this marker to distinguish the continuation instruction from
+ * other transcript-suppressed prompts without depending on host voice code.
+ */
+export declare const VOICE_ESCALATION_CONTINUATION_MESSAGE_KIND = "voice_escalation_continuation";
+
 declare interface WebFetchMetadata {
     url: string;
     finalUrl: string;

package/index.js

@@ -2,11 +2,13 @@
 const api = globalThis[Symbol.for("vellum.plugin-api")] ?? {};
 export const CLI_COMMAND_HELP = api.CLI_COMMAND_HELP;
 export const CredentialResolutionError = api.CredentialResolutionError;
+export const CredentialStoreError = api.CredentialStoreError;
 export const HOOKS = api.HOOKS;
 export const INTERNAL_NUDGE_OUTPUT_SUPPRESSION = api.INTERNAL_NUDGE_OUTPUT_SUPPRESSION;
 export const REFUSAL_FALLBACK_TEXT = api.REFUSAL_FALLBACK_TEXT;
 export const RiskLevel = api.RiskLevel;
 export const TtsSynthesisError = api.TtsSynthesisError;
+export const VOICE_ESCALATION_CONTINUATION_MESSAGE_KIND = api.VOICE_ESCALATION_CONTINUATION_MESSAGE_KIND;
 export const addMessage = api.addMessage;
 export const assistantEventHub = api.assistantEventHub;
 export const buildMessageExcerpt = api.buildMessageExcerpt;
@@ -44,11 +46,13 @@ export const queryIndex = api.queryIndex;
 export const removeDocument = api.removeDocument;
 export const resolveCredential = api.resolveCredential;
 export const resolveMediaSourceData = api.resolveMediaSourceData;
+export const resolveOauthCallbackUrl = api.resolveOauthCallbackUrl;
 export const resolveUserName = api.resolveUserName;
 export const resolveWebhookUrl = api.resolveWebhookUrl;
 export const runConversationTurn = api.runConversationTurn;
 export const searchMessageIdsLexical = api.searchMessageIdsLexical;
 export const selectedBackendSupportsMultimodal = api.selectedBackendSupportsMultimodal;
+export const storeCredential = api.storeCredential;
 export const stringifyMessageContent = api.stringifyMessageContent;
 export const sweepOrphanedGraphNodePoints = api.sweepOrphanedGraphNodePoints;
 export const syncMessageToDisk = api.syncMessageToDisk;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.11.3",
+  "version": "0.11.4-dev.202608190019.b94dbf2",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",