@vellumai/plugin-api 0.11.2 → 0.11.3-dev.202608080427.92f668a

package/index.d.ts

@@ -76,6 +76,37 @@ export declare type AgentLoopExitReason =
 /** An unhandled error ended the turn. */
 | "error";
 
+declare type AnsweredQuestion = z.infer<typeof AnsweredQuestionSchema>;
+
+declare const AnsweredQuestionSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    questions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        question: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        options: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        freeTextPlaceholder: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    responses: z.ZodArray<z.ZodObject<{
+        questionId: z.ZodString;
+        decision: z.ZodEnum<{
+            option: "option";
+            free_text: "free_text";
+            skipped: "skipped";
+        }>;
+        optionId: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    overall: z.ZodEnum<{
+        completed: "completed";
+        closed: "closed";
+    }>;
+}, z.core.$strip>;
+
 /**
  * How {@link listConversations} (and friends) treats archived rows.
  *
@@ -116,11 +147,12 @@ 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";
             }>>;
-            language: z.ZodOptional<z.ZodString>;
+            language: z.ZodDefault<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<{
@@ -139,6 +171,9 @@ declare const AssistantConfigSchema: z.ZodObject<{
                     stability: z.ZodDefault<z.ZodNumber>;
                     similarityBoost: z.ZodDefault<z.ZodNumber>;
                     conversationTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+                    languageVoices: z.ZodOptional<z.ZodPipe<z.ZodRecord<z.ZodString, z.ZodString>, z.ZodTransform<{
+                        [k: string]: string;
+                    }, Record<string, string>>>>;
                 }, z.core.$strip>>;
                 "fish-audio": z.ZodDefault<z.ZodObject<{
                     referenceId: z.ZodDefault<z.ZodString>;
@@ -161,6 +196,9 @@ declare const AssistantConfigSchema: z.ZodObject<{
                         wav: "wav";
                         opus: "opus";
                     }>>;
+                    languageVoices: z.ZodOptional<z.ZodPipe<z.ZodRecord<z.ZodString, z.ZodString>, z.ZodTransform<{
+                        [k: string]: string;
+                    }, Record<string, string>>>>;
                 }, z.core.$strip>>;
                 xai: z.ZodDefault<z.ZodObject<{
                     voiceId: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
@@ -174,6 +212,9 @@ declare const AssistantConfigSchema: z.ZodObject<{
                 }, z.core.$strip>>;
                 vellum: z.ZodDefault<z.ZodObject<{
                     model: z.ZodOptional<z.ZodString>;
+                    languageVoices: z.ZodOptional<z.ZodPipe<z.ZodRecord<z.ZodString, z.ZodString>, z.ZodTransform<{
+                        [k: string]: string;
+                    }, Record<string, string>>>>;
                 }, z.core.$strip>>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
@@ -484,6 +525,11 @@ declare const AssistantConfigSchema: z.ZodObject<{
             }, z.core.$strip>>;
         }, z.core.$strip>>;
         retrospective: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            forkStrategy: z.ZodDefault<z.ZodEnum<{
+                cloning: "cloning";
+                reference: "reference";
+            }>>;
             timeThresholdMs: z.ZodDefault<z.ZodNumber>;
             messageThreshold: z.ZodDefault<z.ZodNumber>;
             minCooldownMs: z.ZodDefault<z.ZodNumber>;
@@ -680,7 +726,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
             skillCategoryInference: "skillCategoryInference";
             inference: "inference";
             vision: "vision";
-            voiceFrontDecision: "voiceFrontDecision";
+            voiceProgressNarration: "voiceProgressNarration";
             voiceFrontDoor: "voiceFrontDoor";
             trustRuleSuggestion: "trustRuleSuggestion";
             homeGreeting: "homeGreeting";
@@ -1010,7 +1056,6 @@ declare const AssistantConfigSchema: z.ZodObject<{
             denyCategories: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
         voice: z.ZodDefault<z.ZodObject<{
-            language: z.ZodDefault<z.ZodString>;
             interruptSensitivity: z.ZodDefault<z.ZodEnum<{
                 low: "low";
                 medium: "medium";
@@ -1039,13 +1084,14 @@ declare const AssistantConfigSchema: z.ZodObject<{
             silenceThresholdMs: z.ZodDefault<z.ZodNumber>;
             maxTurnDurationMs: z.ZodDefault<z.ZodNumber>;
             bargeInMinSpeechMs: z.ZodDefault<z.ZodNumber>;
+            echoBargeInMargin: z.ZodDefault<z.ZodNumber>;
+            echoEmaHalfLifeMs: z.ZodDefault<z.ZodNumber>;
+            echoDrainSlackMs: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strip>>;
         frontModel: z.ZodDefault<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>;
@@ -1056,6 +1102,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>>;
@@ -1070,6 +1125,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
         botId: z.ZodDefault<z.ZodString>;
         botUsername: z.ZodDefault<z.ZodString>;
         apiBaseUrl: z.ZodDefault<z.ZodString>;
+        registeredWebhookUrl: z.ZodOptional<z.ZodString>;
         deliverAuthBypass: z.ZodDefault<z.ZodBoolean>;
         timeoutMs: z.ZodDefault<z.ZodNumber>;
         maxRetries: z.ZodDefault<z.ZodNumber>;
@@ -1162,6 +1218,18 @@ declare const AssistantConfigSchema: z.ZodObject<{
         journalRetentionDays: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     plugins: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    pluginUpdates: z.ZodDefault<z.ZodObject<{
+        mode: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            manual: "manual";
+        }>>;
+        strategy: z.ZodDefault<z.ZodEnum<{
+            theirs: "theirs";
+            ours: "ours";
+            overwrite: "overwrite";
+        }>>;
+        checkIntervalMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
     legacyTelemetryOptOut: z.ZodOptional<z.ZodBoolean>;
     legacyDiagnosticsOptOut: z.ZodOptional<z.ZodBoolean>;
     maxStepsPerSession: z.ZodDefault<z.ZodNumber>;
@@ -1306,8 +1374,8 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         id: z.ZodString;
         conversationId: z.ZodString;
         status: z.ZodEnum<{
-            cancelled: "cancelled";
             completed: "completed";
+            cancelled: "cancelled";
             failed: "failed";
         }>;
         exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -2258,6 +2326,34 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
                 mayRequireJavaScript: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        answeredQuestion: z.ZodOptional<z.ZodObject<{
+            requestId: z.ZodString;
+            questions: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                question: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+                options: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    label: z.ZodString;
+                    description: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+                freeTextPlaceholder: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            responses: z.ZodArray<z.ZodObject<{
+                questionId: z.ZodString;
+                decision: z.ZodEnum<{
+                    option: "option";
+                    free_text: "free_text";
+                    skipped: "skipped";
+                }>;
+                optionId: z.ZodOptional<z.ZodString>;
+                text: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            overall: z.ZodEnum<{
+                completed: "completed";
+                closed: "closed";
+            }>;
+        }, z.core.$strip>>;
         errorCode: z.ZodOptional<z.ZodString>;
         completedAt: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>, z.ZodObject<{
@@ -2474,6 +2570,12 @@ export declare class AssistantEventHub {
      * delivery to remaining subscribers.
      */
     publish(event: AssistantEventEnvelope, options?: AssistantEventPublishOptions): Promise<void>;
+    /**
+     * Yield every active client entry with the given clientId. `subscribe`
+     * disposes any prior entries for the same clientId, so at most one entry
+     * matches.
+     */
+    private activeClientEntries;
     /**
      * Return the active client subscriber with the given clientId, or
      * `undefined` if no such subscriber exists.
@@ -2488,6 +2590,29 @@ export declare class AssistantEventHub {
      * authenticated user identity that opened the target client's SSE stream.
      */
     getActorPrincipalIdForClient(clientId: string): string | undefined;
+    /**
+     * Whether the connection identified by `connectionId` is still an active
+     * client subscription that carries no `actorPrincipalId`.
+     *
+     * Drives the retrying SSE self-heal (`sse-actor-principal-heal.ts`): the loop
+     * re-checks before each attempt so it stops as soon as the connection closes,
+     * is replaced by a reconnect, or gets a principal from any path. Returns
+     * `false` for an unknown, inactive, or process-type connection.
+     */
+    needsActorPrincipalHeal(connectionId: string): boolean;
+    /**
+     * Fill a missing `actorPrincipalId` on a live client subscription.
+     *
+     * Used by the SSE dev-bypass self-heal: when the guardian-delivery cache is
+     * cold at subscribe time, the registration lands without a principal; the
+     * route resolves it async and patches the record here. Keyed by
+     * `connectionId` (not clientId) so a reconnect race cannot patch the
+     * subscription that replaced the one being healed. No-op when the
+     * connection is gone or already carries a principal: this only fills a
+     * missing value, never overwrites one. The value must come from the
+     * daemon's own server-side guardian lookup, never from client input.
+     */
+    fillClientActorPrincipalId(connectionId: string, actorPrincipalId: string): void;
     /**
      * Returns true when at least one active subscriber would receive the given
      * event based on the same conversation matching rules as publish().
@@ -2517,6 +2642,12 @@ export declare class AssistantEventHub {
      * Touch a client subscriber — update `lastActiveAt`. Used by heartbeat.
      */
     touchClient(clientId: string): void;
+    /**
+     * Record the desktop presence state reported by a client. `reportedAt`
+     * always advances. Returns true when at least one active client entry
+     * matched.
+     */
+    setClientPresence(clientId: string, state: DesktopPresenceState): boolean;
     /**
      * Force-disconnect a client by disposing all subscribers for the given
      * `clientId`. Returns the number of disposed entries.
@@ -2548,6 +2679,7 @@ declare const AssistantEventPublishOptionsSchema: z.ZodObject<{
     }>>;
     targetClientId: z.ZodOptional<z.ZodString>;
     targetInterfaceId: z.ZodOptional<z.ZodEnum<{
+        plugin: "plugin";
         telegram: "telegram";
         phone: "phone";
         whatsapp: "whatsapp";
@@ -2694,8 +2826,8 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodString;
     conversationId: z.ZodString;
     status: z.ZodEnum<{
-        cancelled: "cancelled";
         completed: "completed";
+        cancelled: "cancelled";
         failed: "failed";
     }>;
     exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -3646,6 +3778,34 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             mayRequireJavaScript: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    answeredQuestion: z.ZodOptional<z.ZodObject<{
+        requestId: z.ZodString;
+        questions: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            question: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            options: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            freeTextPlaceholder: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        responses: z.ZodArray<z.ZodObject<{
+            questionId: z.ZodString;
+            decision: z.ZodEnum<{
+                option: "option";
+                free_text: "free_text";
+                skipped: "skipped";
+            }>;
+            optionId: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        overall: z.ZodEnum<{
+            completed: "completed";
+            closed: "closed";
+        }>;
+    }, z.core.$strip>>;
     errorCode: z.ZodOptional<z.ZodString>;
     completedAt: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
@@ -3944,6 +4104,17 @@ declare interface ClientEntry extends BaseSubscriberEntry {
      * service-token connections that have no principal.
      */
     actorPrincipalId?: string;
+    /**
+     * Last desktop presence reported by this client, for clients that report it.
+     * In-memory only, so consumers must fail open when it is absent.
+     */
+    presence?: ClientPresence;
+}
+
+declare interface ClientPresence {
+    state: DesktopPresenceState;
+    /** When the daemon last heard from the client. Drives staleness. */
+    reportedAt: Date;
 }
 
 declare interface CliOptionHelp {
@@ -4033,6 +4204,8 @@ export declare interface ConversationRow {
     originInterface: string | null;
     forkParentConversationId: string | null;
     forkParentMessageId: string | null;
+    /** `"reference"` on referential forks; `"cloning"` or null on copied ones. */
+    forkStrategy: string | null;
     isAutoTitle: number;
     scheduleJobId: string | null;
     lastMessageAt: number | null;
@@ -4102,6 +4275,14 @@ export declare class CredentialResolutionError extends Error {
  */
 export declare function deleteConversation(id: string): Promise<void>;
 
+/**
+ * The presence states a desktop client may report. Single runtime source: the
+ * stored type and the route's wire enum both derive from this tuple.
+ */
+declare const DESKTOP_PRESENCE_STATES: readonly ["active", "idle", "away"];
+
+declare type DesktopPresenceState = (typeof DESKTOP_PRESENCE_STATES)[number];
+
 declare interface DiffInfo {
     filePath: string;
     oldContent: string;
@@ -4190,6 +4371,14 @@ export declare function getConversation(id: string): Promise<ConversationRow | n
  */
 export declare function getConversationDirPath(id: string, createdAtMs: number): Promise<string>;
 
+/**
+ * The persisted `processing_started_at` stamp for a conversation, or null
+ * when the conversation is idle (or the row does not exist). Lets background
+ * consumers age-gate the processing flag: a stamp far in the past is a
+ * stranded flag (a swallowed turn-end clear), not a live turn.
+ */
+export declare function getConversationProcessingStartedAt(id: string): Promise<number | null>;
+
 /** Fetch one document from the calling plugin's index, or null. */
 export declare function getDocument(documentId: string): Promise<IndexedDocument | null>;
 
@@ -4433,7 +4622,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];
 
@@ -4512,7 +4701,13 @@ export declare function lastToolResultUserMessageIndex(history: Message[]): numb
  */
 export declare function listCatalogSkills(): Promise<ResolvedSkillEntry[]>;
 
-/** List conversation rows, newest first. */
+/**
+ * List conversation rows, newest first.
+ *
+ * The positional signature is part of the plugin API surface and stays
+ * stable; the underlying query takes a named filter, which this maps onto.
+ * Omitted arguments stay omitted so the query's own defaults apply.
+ */
 export declare function listConversations(limit?: number, conversationType?: ConversationType, offset?: number, archiveStatus?: ArchiveStatusFilter, originChannel?: string): Promise<ConversationRow[]>;
 
 /**
@@ -4607,6 +4802,19 @@ declare interface LiveVoiceErrorServerFrame extends LiveVoiceServerFrameBase {
     readonly type: "error";
     readonly code: LiveVoiceProtocolErrorCode;
     readonly message: string;
+    /**
+     * The client frame this error is about, when the failure was a parse or
+     * validation failure of a specific frame. Absent otherwise, and absent from
+     * daemons predating the field.
+     *
+     * It exists so an `unknown_type` is attributable. A client that sends more
+     * than one optional frame (today: `update_config` and `attach_image`) gets
+     * the same code for either, and without this has to assume which one was
+     * refused. The wrong assumption is silent in both directions: settings stop
+     * applying for a session, or a photo the user watched themselves take is
+     * dropped with nothing said.
+     */
+    readonly frameType?: string;
     /**
      * True when the session continues past the error (e.g. a transient
      * transcriber blip or one failed TTS segment). Absent (including on frames
@@ -4635,14 +4843,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";
     /**
@@ -4816,7 +5044,7 @@ declare const LLMCallSiteEnum: z.ZodEnum<{
     skillCategoryInference: "skillCategoryInference";
     inference: "inference";
     vision: "vision";
-    voiceFrontDecision: "voiceFrontDecision";
+    voiceProgressNarration: "voiceProgressNarration";
     voiceFrontDoor: "voiceFrontDoor";
     trustRuleSuggestion: "trustRuleSuggestion";
     homeGreeting: "homeGreeting";
@@ -4859,6 +5087,7 @@ declare type MessageMetadata_2 = z.infer<typeof messageMetadataSchema>;
 
 declare const messageMetadataSchema: z.ZodObject<{
     userMessageChannel: z.ZodOptional<z.ZodEnum<{
+        plugin: "plugin";
         vellum: "vellum";
         platform: "platform";
         telegram: "telegram";
@@ -4870,6 +5099,7 @@ declare const messageMetadataSchema: z.ZodObject<{
         discord: "discord";
     }>>;
     assistantMessageChannel: z.ZodOptional<z.ZodEnum<{
+        plugin: "plugin";
         vellum: "vellum";
         platform: "platform";
         telegram: "telegram";
@@ -4880,9 +5110,10 @@ declare const messageMetadataSchema: z.ZodObject<{
         a2a: "a2a";
         discord: "discord";
     }>>;
-    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<"plugin" | "telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route" | null, string>> & z.ZodType<"plugin" | "telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"plugin" | "telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string>>>;
+    assistantMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"plugin" | "telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route" | null, string>> & z.ZodType<"plugin" | "telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"plugin" | "telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "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<{
         subagentId: z.ZodString;
         label: z.ZodString;
@@ -4908,6 +5139,7 @@ declare const messageMetadataSchema: z.ZodObject<{
     }>>;
     model: z.ZodOptional<z.ZodString>;
     provenanceSourceChannel: z.ZodOptional<z.ZodEnum<{
+        plugin: "plugin";
         vellum: "vellum";
         platform: "platform";
         telegram: "telegram";
@@ -4933,8 +5165,8 @@ declare const messageMetadataSchema: z.ZodObject<{
         command: z.ZodString;
         startedAt: z.ZodNumber;
         status: z.ZodEnum<{
-            cancelled: "cancelled";
             completed: "completed";
+            cancelled: "cancelled";
             failed: "failed";
         }>;
         exitCode: z.ZodNullable<z.ZodNumber>;
@@ -5624,7 +5856,7 @@ declare type ResolutionFallbackReason = "missing" | "disabled" | "incomplete";
  *   3. `llm.callSites[callSite].profile` (the call site's named profile)
  *   4. `CALL_SITE_DEFAULTS[callSite].profile` intent resolved through
  *      `llm.defaultProvider`
- *   5. balanced intent through `llm.defaultProvider` — the code-owned anchor
+ *   5. balanced intent through `llm.defaultProvider`: the code-owned anchor
  *      for profileless call sites, or when nothing above is usable
  *
  * A winner must carry its own `provider` AND `model`: the base layer's schema
@@ -5767,12 +5999,46 @@ export declare function resolveMediaSourceData(source: MediaSource_2): {
 } | null;
 
 /**
- * Read the guardian's display name from `users/default.md`. We look for the
- * markdown-bold "Name" label (matching the IDENTITY.md convention) and fall
- * back to `null` on any miss; callers substitute a generic label.
+ * 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
+ * back to `users/default.md`. Returns `null` on any miss; callers substitute
+ * a generic label.
+ *
+ * The guardian resolution reads the sync in-process guardian-delivery cache;
+ * callers in processes that do not otherwise warm it (memory worker) await
+ * `getGuardianDelivery` first.
  */
 export declare function resolveUserName(workspaceDir: string): string | null;
 
+/**
+ * Resolve the public URL a third party should deliver to for `path`.
+ *
+ * On the managed branches this registers a callback route with the platform,
+ * which is idempotent and matches what `assistant webhooks register` does.
+ *
+ * @throws when the plugin cannot be determined, when `path` is not one the
+ *   gateway would serve, or when no ingress is configured and the assistant is
+ *   not connected to the platform. That last case has no URL that would work,
+ *   and a plausible one would produce a vendor registration that silently
+ *   receives nothing.
+ */
+export declare function resolveWebhookUrl(options: WebhookUrlOptions): Promise<string>;
+
 export declare enum RiskLevel {
     Low = "low",
     Medium = "medium",
@@ -5992,12 +6258,32 @@ export declare interface SendMessageConfig {
      */
     logit_bias?: Record<string, number>;
     /**
-     * When true, the most recent user message's content varies across
-     * otherwise-identical turns (e.g. a per-turn memory block was injected into
-     * it). The provider places the primary long-TTL cache breakpoint on the most
-     * recent *stable* user message instead of the volatile latest one, so the
-     * cached prefix stays reusable across turns. Default false — existing
-     * behavior.
+     * When true, the TURN-STARTING user message carries content that will not
+     * recur byte-identically on the next turn, so a long-TTL breakpoint placed
+     * on it could never be read back across turns. The agent loop is the only
+     * producer: it sets the flag from the history it is about to send, when the
+     * turn-starting message carries a memory-v3 `<memory_spotlight>` block (the
+     * one injected block strip-and-replaced from every user message each turn).
+     *
+     * The flag describes the turn, not the request, so it holds for every
+     * request the turn makes, including tool-loop iterations, whose trailing
+     * tool-result message is user-role but carries no injected blocks.
+     *
+     * Consumed by the Anthropic client only, where it selects the TTL of the
+     * turn-start breakpoint: short instead of long. The block is still marked,
+     * so the turn's tool-loop iterations read the prefix back and each hit
+     * refreshes the entry; nothing is spent on a long-TTL entry whose bytes
+     * change before the next turn could reach it. Holding the flag steady across
+     * the turn is what keeps that one boundary on a single TTL; marking it at
+     * two would bill two writes for one reusable prefix.
+     *
+     * The OpenAI Responses transport ignores the flag and marks every markable
+     * user item: a volatile message is fixed within its own turn, so the write is
+     * prepaid once and read back by each tool-loop iteration.
+     *
+     * Default false. Providers that place no message-level breakpoints, or that
+     * key their cache on a request-level identifier rather than message bytes,
+     * can ignore it.
      */
     mutableLatestUserMessage?: boolean;
     /**
@@ -6272,13 +6558,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";
@@ -6295,7 +6600,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.
@@ -6310,6 +6615,14 @@ export declare interface SttStreamServerFinalEvent {
      * provider does not surface confidence on this chunk.
      */
     readonly confidence?: number;
+    /**
+     * All detected languages of this chunk in dominance order (first entry
+     * dominant), already normalized to lowercase base subtags (e.g. "en",
+     * "hi") by the emitting adapter; consumers must not re-normalize. Only
+     * providers with code-switching metadata (currently Deepgram nova-3
+     * `multi`) populate this. Absence means "unknown", never English.
+     */
+    readonly languages?: readonly string[];
     /**
      * True when this final is the flush response to
      * {@link StreamingTranscriber.finalizeUtterance} — i.e. it commits audio
@@ -6343,6 +6656,67 @@ export declare interface SttStreamServerPartialEvent {
      * provider does not surface confidence on interim chunks.
      */
     readonly confidence?: number;
+    /**
+     * All detected languages of this chunk in dominance order (first entry
+     * dominant), already normalized to lowercase base subtags (e.g. "en",
+     * "hi") by the emitting adapter; consumers must not re-normalize. Only
+     * providers with code-switching metadata (currently Deepgram nova-3
+     * `multi`) populate this. Absence means "unknown", never English.
+     */
+    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;
@@ -6685,6 +7059,14 @@ export declare interface ToolContext {
      * @legacy
      */
     overrideProfile?: string;
+    /**
+     * The firing's `cron_runs.id` when a schedule triggered this turn, `null`
+     * otherwise. Tools that spawn further LLM work (`subagent_spawn`,
+     * `subagent_message`) forward it so the delegated usage rows carry the same
+     * stamp and attribute to the firing rather than dropping out of schedule
+     * cost reporting.
+     */
+    cronRunId?: string | null;
     /**
      * The LLM call site of the turn currently executing this tool (`mainAgent`,
      * `heartbeatAgent`, scheduled work, etc.). `subagent_spawn` reads it to
@@ -6696,10 +7078,12 @@ export declare interface ToolContext {
     invokingCallSite?: LLMCallSite;
     /**
      * Canonical principal ID of the actor on whose behalf this tool invocation
-     * is running. Sourced from `conversation.trustContext.guardianPrincipalId`.
+     * is running — the turn's actor principal, falling back to the trust
+     * context's `guardianPrincipalId` (see `resolveTurnActorPrincipalId`).
      * 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.
+     * authenticated user identity, so it must resolve to the SAME principal a
+     * desktop client registers with on its SSE stream. May be undefined for
+     * legacy/internal flows with no resolved actor identity.
      * @legacy
      */
     sourceActorPrincipalId?: string;
@@ -6860,6 +7244,14 @@ export declare interface ToolExecutionResult {
     /** Structured activity metadata for client rendering (web search, web fetch, etc).
      *  Populated by daemon-internal tools; plugins must not set this. */
     activityMetadata?: ToolActivityMetadata;
+    /**
+     * Typed side channel from the `ask_question` executor to the agent loop: the
+     * questions asked and the answers the user gave. The loop forwards it on the
+     * `tool_result` event and persists it on the tool_use block, so the answered
+     * card renders live and survives a history reopen instead of the decision
+     * disappearing with the interactive prompt. Set only by `ask_question`.
+     */
+    answeredQuestion?: AnsweredQuestion;
 }
 
 export declare interface ToolResultContent {
@@ -7104,6 +7496,38 @@ declare interface WebFetchMetadata {
 /** Provider that backed a `web_fetch` call. `default` is the built-in fetcher. */
 declare type WebFetchProviderId = "default" | "firecrawl";
 
+/**
+ * Public URL resolution for a plugin's own ingress route.
+ *
+ * A plugin that receives third-party webhooks has to tell the vendor where to
+ * deliver. Which URL is correct depends on how the assistant is reachable:
+ * a platform pod and a platform-connected assistant are served through a
+ * managed callback route, while a self-hosted deployment is served through its
+ * configured public ingress. `ingress.publicBaseUrl` alone does not decide it,
+ * because on a platform-connected assistant that value holds the Velay tunnel
+ * address, which is not where plugin routes are served.
+ *
+ * `resolveCallbackUrl` owns that decision for every caller in the codebase
+ * (`webhooks register`, the Telegram webhook manager). This exposes it to
+ * plugins so there is one implementation rather than one per plugin.
+ */
+export declare interface WebhookUrlOptions {
+    /**
+     * Route path within the plugin's namespace, such as `"events-photon"`.
+     * Relative, with no leading slash.
+     */
+    path: string;
+    /**
+     * Plugin whose namespace the route belongs to.
+     *
+     * Defaults to the plugin in context, which covers hooks and tools. Supply it
+     * explicitly from a plugin route handler, where no context is established.
+     */
+    plugin?: string;
+    /** Human-readable label for the platform's admin display. */
+    sourceIdentifier?: string;
+}
+
 declare interface WebSearchMetadata {
     query: string;
     provider: WebSearchProviderId;

package/index.js

@@ -21,6 +21,7 @@ export const getAssistantName = api.getAssistantName;
 export const getConfiguredProvider = api.getConfiguredProvider;
 export const getConversation = api.getConversation;
 export const getConversationDirPath = api.getConversationDirPath;
+export const getConversationProcessingStartedAt = api.getConversationProcessingStartedAt;
 export const getDocument = api.getDocument;
 export const getMessages = api.getMessages;
 export const getModelProfiles = api.getModelProfiles;
@@ -43,7 +44,9 @@ 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;

package/package.json

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