@vellumai/plugin-api 0.12.1-staging.2 → 0.12.2-dev.202609162214.308bda0

package/index.d.ts

@@ -167,10 +167,10 @@ declare const AssistantConfigSchema: z.ZodObject<{
             language: z.ZodDefault<z.ZodString>;
             providers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
             roles: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
-                watch: "watch";
                 liveVoice: "liveVoice";
                 telephony: "telephony";
                 dictation: "dictation";
+                watch: "watch";
                 batch: "batch";
             }> & z.core.$partial, z.ZodObject<{
                 provider: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
@@ -312,6 +312,12 @@ declare const AssistantConfigSchema: z.ZodObject<{
                 "your-own": "your-own";
             }>>;
         }, z.core.$strip>>;
+        "shopify-oauth": z.ZodDefault<z.ZodObject<{
+            mode: z.ZodDefault<z.ZodEnum<{
+                managed: "managed";
+                "your-own": "your-own";
+            }>>;
+        }, z.core.$strip>>;
         "stripe-link-oauth": z.ZodDefault<z.ZodObject<{
             mode: z.ZodDefault<z.ZodEnum<{
                 managed: "managed";
@@ -324,6 +330,12 @@ declare const AssistantConfigSchema: z.ZodObject<{
                 "your-own": "your-own";
             }>>;
         }, z.core.$strip>>;
+        "quickbooks-oauth": z.ZodDefault<z.ZodObject<{
+            mode: z.ZodDefault<z.ZodEnum<{
+                managed: "managed";
+                "your-own": "your-own";
+            }>>;
+        }, z.core.$strip>>;
         "eventbrite-oauth": z.ZodDefault<z.ZodObject<{
             mode: z.ZodDefault<z.ZodEnum<{
                 managed: "managed";
@@ -592,6 +604,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
         }, z.core.$strip>>;
         retrospective: z.ZodDefault<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
+            skillImprovement: z.ZodDefault<z.ZodBoolean>;
             timeThresholdMs: z.ZodDefault<z.ZodNumber>;
             messageThreshold: z.ZodDefault<z.ZodNumber>;
             minCooldownMs: z.ZodDefault<z.ZodNumber>;
@@ -611,6 +624,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
         fdPollIntervalMs: z.ZodDefault<z.ZodNumber>;
         highFdThresholdRatio: z.ZodDefault<z.ZodNumber>;
         fdWarnCooldownMs: z.ZodDefault<z.ZodNumber>;
+        mountWatchIntervalMs: z.ZodDefault<z.ZodNumber>;
         pluginSourceScanIntervalMs: z.ZodDefault<z.ZodNumber>;
         baselineSnapshotIntervalMs: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
@@ -945,31 +959,14 @@ declare const AssistantConfigSchema: z.ZodObject<{
         }, z.core.$strip>>;
         localDirectory: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>;
-    mcp: z.ZodDefault<z.ZodObject<{
-        servers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
-            transport: z.ZodDiscriminatedUnion<[z.ZodObject<{
-                type: z.ZodLiteral<"stdio">;
-                command: z.ZodString;
-                args: z.ZodDefault<z.ZodArray<z.ZodString>>;
-                env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-            }, z.core.$strip>, z.ZodObject<{
-                type: z.ZodLiteral<"sse">;
-                url: z.ZodString;
-                headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-            }, z.core.$strip>, z.ZodObject<{
-                type: z.ZodLiteral<"streamable-http">;
-                url: z.ZodString;
-                headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-            }, z.core.$strip>], "type">;
-        }, z.core.$strip>>>;
-    }, z.core.$strip>>;
     acp: z.ZodDefault<z.ZodObject<{
         maxConcurrentSessions: z.ZodDefault<z.ZodNumber>;
         agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
-            command: z.ZodString;
+            command: z.ZodOptional<z.ZodString>;
             args: z.ZodDefault<z.ZodArray<z.ZodString>>;
             description: z.ZodOptional<z.ZodString>;
             env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            model: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
     skills: z.ZodDefault<z.ZodObject<{
@@ -981,8 +978,6 @@ declare const AssistantConfigSchema: z.ZodObject<{
         }, z.core.$strip>>>;
         load: z.ZodDefault<z.ZodObject<{
             extraDirs: z.ZodDefault<z.ZodArray<z.ZodString>>;
-            watch: z.ZodDefault<z.ZodBoolean>;
-            watchDebounceMs: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strip>>;
         install: z.ZodDefault<z.ZodObject<{
             nodeManager: z.ZodDefault<z.ZodEnum<{
@@ -1077,15 +1072,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
             text: z.ZodDefault<z.ZodString>;
         }, z.core.$strip>>;
-        safety: z.ZodDefault<z.ZodObject<{
-            denyCategories: z.ZodDefault<z.ZodArray<z.ZodString>>;
-        }, z.core.$strip>>;
         voice: z.ZodDefault<z.ZodObject<{
-            interruptSensitivity: z.ZodDefault<z.ZodEnum<{
-                low: "low";
-                medium: "medium";
-                high: "high";
-            }>>;
             telephonyStreaming: z.ZodDefault<z.ZodBoolean>;
             utteranceEndMs: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strip>>;
@@ -1100,10 +1087,6 @@ declare const AssistantConfigSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     liveVoice: z.ZodDefault<z.ZodObject<{
-        mode: z.ZodDefault<z.ZodEnum<{
-            ptt: "ptt";
-            "open-mic": "open-mic";
-        }>>;
         vad: z.ZodDefault<z.ZodObject<{
             speechEnergyThreshold: z.ZodDefault<z.ZodNumber>;
             noiseFloorMargin: z.ZodDefault<z.ZodNumber>;
@@ -1114,6 +1097,18 @@ declare const AssistantConfigSchema: z.ZodObject<{
             echoEmaHalfLifeMs: z.ZodDefault<z.ZodNumber>;
             echoDrainSlackMs: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strip>>;
+        flux: z.ZodDefault<z.ZodObject<{
+            turnEnd: z.ZodDefault<z.ZodObject<{
+                enabled: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strip>>;
+            model: z.ZodOptional<z.ZodString>;
+            eotThreshold: z.ZodDefault<z.ZodNumber>;
+            eagerEotThreshold: z.ZodOptional<z.ZodNumber>;
+            eotTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        archiveAudio: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    voice: z.ZodDefault<z.ZodObject<{
         frontModel: z.ZodDefault<z.ZodObject<{
             endpointDecisionTimeoutMs: z.ZodDefault<z.ZodNumber>;
             endpointExtensionMs: z.ZodDefault<z.ZodNumber>;
@@ -1128,17 +1123,6 @@ 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.ZodOptional<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>>;
     sight: z.ZodDefault<z.ZodObject<{
         keepLatestFrames: z.ZodDefault<z.ZodNumber>;
@@ -1313,6 +1297,18 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         type: z.ZodLiteral<"acp_session_error">;
         acpSessionId: z.ZodString;
         error: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"acp_session_model_update">;
+        acpSessionId: z.ZodString;
+        modelRevisionEpoch: z.ZodString;
+        modelRevision: z.ZodNumber;
+        model: z.ZodOptional<z.ZodString>;
+        availableModels: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            group: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"acp_session_spawned">;
         acpSessionId: z.ZodString;
@@ -1665,6 +1661,8 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         type: z.ZodLiteral<"conversation_title_updated">;
         conversationId: z.ZodString;
         title: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"desktop_activity_changed">;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"disk_pressure_status_changed">;
         status: z.ZodObject<{
@@ -1764,6 +1762,7 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
                 sandbox_file: "sandbox_file";
                 tool_block: "tool_block";
             }>>;
+            computerUseScreenshot: z.ZodOptional<z.ZodBoolean>;
             sizeBytes: z.ZodOptional<z.ZodNumber>;
             thumbnailData: z.ZodOptional<z.ZodString>;
             fileBacked: z.ZodOptional<z.ZodBoolean>;
@@ -2044,6 +2043,7 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
                 sandbox_file: "sandbox_file";
                 tool_block: "tool_block";
             }>>;
+            computerUseScreenshot: z.ZodOptional<z.ZodBoolean>;
             sizeBytes: z.ZodOptional<z.ZodNumber>;
             thumbnailData: z.ZodOptional<z.ZodString>;
             fileBacked: z.ZodOptional<z.ZodBoolean>;
@@ -2121,6 +2121,7 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"notification_intent">;
         sourceEventName: z.ZodString;
+        assistantName: z.ZodOptional<z.ZodString>;
         title: z.ZodString;
         body: z.ZodString;
         deliveryId: z.ZodOptional<z.ZodString>;
@@ -2548,6 +2549,7 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         messageId: z.ZodOptional<z.ZodString>;
         requestId: z.ZodOptional<z.ZodString>;
         clientMessageId: z.ZodOptional<z.ZodString>;
+        cameraFrame: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"watch_retro_completed">;
         sessionId: z.ZodString;
@@ -2781,6 +2783,7 @@ declare const AssistantEventPublishOptionsSchema: z.ZodObject<{
         host_file: "host_file";
         host_cu: "host_cu";
         host_cu_window_capture: "host_cu_window_capture";
+        host_cu_sequence: "host_cu_sequence";
         host_cu_annotate: "host_cu_annotate";
         host_browser: "host_browser";
         host_app_control: "host_app_control";
@@ -2841,6 +2844,18 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"acp_session_error">;
     acpSessionId: z.ZodString;
     error: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"acp_session_model_update">;
+    acpSessionId: z.ZodString;
+    modelRevisionEpoch: z.ZodString;
+    modelRevision: z.ZodNumber;
+    model: z.ZodOptional<z.ZodString>;
+    availableModels: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        group: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"acp_session_spawned">;
     acpSessionId: z.ZodString;
@@ -3193,6 +3208,8 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"conversation_title_updated">;
     conversationId: z.ZodString;
     title: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"desktop_activity_changed">;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"disk_pressure_status_changed">;
     status: z.ZodObject<{
@@ -3292,6 +3309,7 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             sandbox_file: "sandbox_file";
             tool_block: "tool_block";
         }>>;
+        computerUseScreenshot: z.ZodOptional<z.ZodBoolean>;
         sizeBytes: z.ZodOptional<z.ZodNumber>;
         thumbnailData: z.ZodOptional<z.ZodString>;
         fileBacked: z.ZodOptional<z.ZodBoolean>;
@@ -3572,6 +3590,7 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             sandbox_file: "sandbox_file";
             tool_block: "tool_block";
         }>>;
+        computerUseScreenshot: z.ZodOptional<z.ZodBoolean>;
         sizeBytes: z.ZodOptional<z.ZodNumber>;
         thumbnailData: z.ZodOptional<z.ZodString>;
         fileBacked: z.ZodOptional<z.ZodBoolean>;
@@ -3649,6 +3668,7 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"notification_intent">;
     sourceEventName: z.ZodString;
+    assistantName: z.ZodOptional<z.ZodString>;
     title: z.ZodString;
     body: z.ZodString;
     deliveryId: z.ZodOptional<z.ZodString>;
@@ -4076,6 +4096,7 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     messageId: z.ZodOptional<z.ZodString>;
     requestId: z.ZodOptional<z.ZodString>;
     clientMessageId: z.ZodOptional<z.ZodString>;
+    cameraFrame: z.ZodOptional<z.ZodLiteral<true>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"watch_retro_completed">;
     sessionId: z.ZodString;
@@ -4754,6 +4775,12 @@ export declare function getConversationDirPath(id: string, createdAtMs: number):
  */
 export declare function getConversationProcessingStartedAt(id: string): Promise<number | null>;
 
+/**
+ * The tool definitions the conversation's most recent live turn sent to the
+ * provider, or `null` when none has been recorded.
+ */
+export declare function getConversationToolSurface(conversationId: string): Promise<ToolDefinition_2[] | null>;
+
 /** Fetch one document from the calling plugin's index, or null. */
 export declare function getDocument(documentId: string): Promise<IndexedDocument | null>;
 
@@ -4849,6 +4876,7 @@ export declare type HookBroadcast = (detail: Record<string, unknown>) => void;
  *   - `post-model-call` — {@link PostModelCallContext}
  *   - `conversation-deleted` — {@link ConversationDeletedContext}
  *   - `conversations-cleared` — {@link ConversationsClearedContext}
+ *   - `message-deleted`: {@link MessageDeletedContext}
  */
 export declare type HookFunction<TCtx = unknown> = (ctx: TCtx) => Promise<Partial<TCtx> | void>;
 
@@ -4890,6 +4918,8 @@ export declare const HOOKS: {
     readonly CONVERSATION_DELETED: "conversation-deleted";
     /** Fires once when every conversation is wiped at once (the clear-all reset), after the main tables are cleared. Carries no `conversationId`; cleanup hooks wipe their own per-conversation state wholesale. */
     readonly CONVERSATIONS_CLEARED: "conversations-cleared";
+    /** Fires once per deleted message row, after the row is removed, carrying the row's `(createdAt, id)` so a hook can settle state that pointed at it. Fire-and-forget cleanup signal, like `conversation-deleted`; whole-conversation deletes dispatch that hook instead. */
+    readonly MESSAGE_DELETED: "message-deleted";
 };
 
 /**
@@ -4904,7 +4934,7 @@ export declare const HOOKS: {
  *
  * Pure data and pure functions only: no imports, no daemon runtime graph.
  */
-declare const HOST_PROXY_CAPABILITIES: readonly ["host_bash", "host_file", "host_cu", "host_cu_window_capture", "host_cu_annotate", "host_browser", "host_app_control", "host_ui_snapshot"];
+declare const HOST_PROXY_CAPABILITIES: readonly ["host_bash", "host_file", "host_cu", "host_cu_window_capture", "host_cu_sequence", "host_cu_annotate", "host_browser", "host_app_control", "host_ui_snapshot"];
 
 declare type HostProxyCapability = (typeof HOST_PROXY_CAPABILITIES)[number];
 
@@ -5116,7 +5146,9 @@ export declare function listConversations(limit?: number, conversationType?: Con
  */
 export declare function listInstalledSkills(): Promise<ResolvedSkillEntry[]>;
 
-declare const _LIVE_VOICE_SERVER_FRAME_TYPES: readonly ["ready", "busy", "speech_started", "utterance_end", "utterance_discarded", "stt_partial", "stt_final", "thinking", "activity", "assistant_text_delta", "tts_audio", "tts_done", "turn_cancelled", "minimize_room", "metrics", "archived", "error"];
+declare const _LIVE_VOICE_SERVER_FRAME_TYPES: readonly ["ready", "busy", "speech_started", "utterance_end", "utterance_discarded", "stt_partial", "stt_final", "thinking", "activity", "assistant_text_delta", "tts_audio", "tts_done", "turn_cancelled", "minimize_room", "session_control", "metrics", "archived", "error"];
+
+declare const LIVE_VOICE_SESSION_CONTROLS: readonly ["end", "mute", "look_screen", "look_camera", "look_stop"];
 
 declare const LIVE_VOICE_TURN_DETECTION_MODES: readonly ["manual", "server_vad"];
 
@@ -5293,8 +5325,6 @@ declare interface LiveVoiceMetricsServerFrame extends LiveVoiceServerFrameBase {
      * 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";
     /**
      * Spoken progress narrations during the turn. Present only when at least
      * one progress update spoke (otherwise the field is absent, keeping frames
@@ -5361,7 +5391,7 @@ declare interface LiveVoiceReadyServerFrame extends LiveVoiceServerFrameBase {
     readonly audioInput?: boolean;
 }
 
-export declare type LiveVoiceServerFrame = LiveVoiceReadyServerFrame | LiveVoiceBusyServerFrame | LiveVoiceSpeechStartedServerFrame | LiveVoiceUtteranceEndServerFrame | LiveVoiceUtteranceDiscardedServerFrame | LiveVoiceSttPartialServerFrame | LiveVoiceSttFinalServerFrame | LiveVoiceThinkingServerFrame | LiveVoiceActivityServerFrame | LiveVoiceAssistantTextDeltaServerFrame | LiveVoiceTtsAudioServerFrame | LiveVoiceTtsDoneServerFrame | LiveVoiceTurnCancelledServerFrame | LiveVoiceMinimizeRoomServerFrame | LiveVoiceMetricsServerFrame | LiveVoiceArchivedServerFrame | LiveVoiceErrorServerFrame;
+export declare type LiveVoiceServerFrame = LiveVoiceReadyServerFrame | LiveVoiceBusyServerFrame | LiveVoiceSpeechStartedServerFrame | LiveVoiceUtteranceEndServerFrame | LiveVoiceUtteranceDiscardedServerFrame | LiveVoiceSttPartialServerFrame | LiveVoiceSttFinalServerFrame | LiveVoiceThinkingServerFrame | LiveVoiceActivityServerFrame | LiveVoiceAssistantTextDeltaServerFrame | LiveVoiceTtsAudioServerFrame | LiveVoiceTtsDoneServerFrame | LiveVoiceTurnCancelledServerFrame | LiveVoiceMinimizeRoomServerFrame | LiveVoiceSessionControlServerFrame | LiveVoiceMetricsServerFrame | LiveVoiceArchivedServerFrame | LiveVoiceErrorServerFrame;
 
 declare interface LiveVoiceServerFrameBase {
     readonly type: LiveVoiceServerFrameType;
@@ -5372,6 +5402,32 @@ declare type LiveVoiceServerFrameType = (typeof _LIVE_VOICE_SERVER_FRAME_TYPES)[
 
 export declare type LiveVoiceSessionCloseReason = "client_end" | "error" | "websocket_close" | "transport_closed" | "client_timeout" | "forced_end" | "manager_shutdown";
 
+/** A session control a client can carry out on the assistant's behalf. */
+declare type LiveVoiceSessionControl = (typeof LIVE_VOICE_SESSION_CONTROLS)[number];
+
+/**
+ * A session control the just-completed reply asked for with a terminal marker
+ * (`[END_CALL]`, `[MUTE]`, `[MUTE:<seconds>]`). Sent only after the turn's TTS
+ * has fully drained, so the spoken acknowledgement is heard first, never for a
+ * turn the user barged in on, at most once per turn, and only for a control
+ * the client listed in the start frame's `sessionControls`.
+ *
+ * - `end`: end the session the way the client's own end control does.
+ * - `mute`: mute the microphone. With `durationMs`, unmute again once it
+ *   elapses; without, stay muted until the user unmutes. The timer is the
+ *   client's: a muted microphone sends silence, so the daemon cannot hear an
+ *   "unmute".
+ * - `look_screen`: start showing the call the user's screen.
+ * - `look_camera`: start showing the call what the camera sees.
+ * - `look_stop`: stop showing the call the screen and the camera.
+ */
+declare interface LiveVoiceSessionControlServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "session_control";
+    readonly turnId: string;
+    readonly action: LiveVoiceSessionControl;
+    readonly durationMs?: number;
+}
+
 /**
  * Where the session holding the daemon's single live-voice slot is running,
  * as much of it as the daemon knows.
@@ -5535,6 +5591,37 @@ export declare interface Message {
     content: ContentBlock[];
 }
 
+/**
+ * The full `message-deleted` context a hook receives: the dispatching call
+ * site's {@link MessageDeletedInputContext} plus the pipeline-stamped
+ * {@link BaseHookContext} capabilities.
+ */
+export declare interface MessageDeletedContext extends MessageDeletedInputContext, BaseHookContext {
+}
+
+/**
+ * Context passed to the `message-deleted` hook. Fires once per deleted
+ * message row, from the shared single-message delete primitive, after the row
+ * is removed. Whole-conversation deletes dispatch `conversation-deleted`
+ * instead.
+ *
+ * Fire-and-forget like `conversation-deleted`: the primitive is synchronous
+ * and does not wait for the chain. The row is gone by the time a hook runs,
+ * so the context carries the row's `createdAt` alongside its id. Together
+ * they are the `(createdAt, id)` position the row held, which is what a hook
+ * keeping a cursor on that row needs to record once the row can no longer be
+ * looked up. The default memory plugin contributes a hook here that stamps
+ * its retrospective cursor.
+ */
+declare interface MessageDeletedInputContext {
+    /** ID of the conversation that owned the row. */
+    readonly conversationId: string;
+    /** ID of the deleted message row. */
+    readonly messageId: string;
+    /** The deleted row's `createdAt`. */
+    readonly createdAt: number;
+}
+
 declare type MessageLexicalSearchResult = Awaited<ReturnType<searchMessageIdsLexical_2>>[number];
 
 declare interface MessageLexicalSearchResult_2 {
@@ -5632,6 +5719,7 @@ declare const messageMetadataSchema: z.ZodObject<{
     automated: z.ZodOptional<z.ZodBoolean>;
     hidden: z.ZodOptional<z.ZodBoolean>;
     voiceSessionTurn: z.ZodOptional<z.ZodBoolean>;
+    computerUseScreenshotAttachmentIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     messageKind: z.ZodOptional<z.ZodString>;
     assistantTextVisibility: z.ZodOptional<z.ZodString>;
     providerErrorCode: z.ZodOptional<z.ZodString>;
@@ -5823,6 +5911,11 @@ export declare interface PluginLogger {
     debug(obj: Record<string, unknown>, msg?: string): void;
 }
 
+export declare class PluginTurnNotAdmittedError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+
 /**
  * The full `post-compact` context a hook receives — the dispatching call
  * site's {@link PostCompactInputContext} plus the pipeline-stamped
@@ -6707,6 +6800,23 @@ export declare interface RunConversationTurnResult {
     queued?: boolean;
 }
 
+/**
+ * Slice a string like `String.prototype.slice`, but never cut a UTF-16
+ * surrogate pair in half.
+ *
+ * If the character at `end - 1` is a high surrogate *and* there is more of
+ * the string beyond `end` (so cutting would actually orphan it), `end` is
+ * decremented by one.
+ *
+ * If the character at `start` is a low surrogate *and* `start > 0` (so we
+ * would be starting mid-pair), `start` is incremented by one.
+ *
+ * When `end === str.length` we do not touch a trailing high surrogate: if it
+ * was already orphaned upstream, repairing it here would silently mutate
+ * content. That is the sanitizer's job, not this function's.
+ */
+export declare function safeStringSlice(str: string, start?: number, end?: number): string;
+
 /** Sparse lexical search over stored message text; ranked message-id hits. */
 export declare function searchMessageIdsLexical(query: string, limit: number, opts?: {
     conversationId?: string;

package/index.js

@@ -5,6 +5,7 @@ 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 PluginTurnNotAdmittedError = api.PluginTurnNotAdmittedError;
 export const REFUSAL_FALLBACK_TEXT = api.REFUSAL_FALLBACK_TEXT;
 export const RiskLevel = api.RiskLevel;
 export const TtsSynthesisError = api.TtsSynthesisError;
@@ -25,6 +26,7 @@ export const getConfiguredProvider = api.getConfiguredProvider;
 export const getConversation = api.getConversation;
 export const getConversationDirPath = api.getConversationDirPath;
 export const getConversationProcessingStartedAt = api.getConversationProcessingStartedAt;
+export const getConversationToolSurface = api.getConversationToolSurface;
 export const getDocument = api.getDocument;
 export const getMessages = api.getMessages;
 export const getModelProfiles = api.getModelProfiles;
@@ -54,6 +56,7 @@ export const resolveOauthCallbackUrl = api.resolveOauthCallbackUrl;
 export const resolveUserName = api.resolveUserName;
 export const resolveWebhookUrl = api.resolveWebhookUrl;
 export const runConversationTurn = api.runConversationTurn;
+export const safeStringSlice = api.safeStringSlice;
 export const searchMessageIdsLexical = api.searchMessageIdsLexical;
 export const selectedBackendSupportsMultimodal = api.selectedBackendSupportsMultimodal;
 export const storeCredential = api.storeCredential;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.12.1-staging.2",
+  "version": "0.12.2-dev.202609162214.308bda0",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",