@vellumai/plugin-api 0.11.11-staging.3 → 0.12.0-dev.202609110124.4b134bf

package/index.d.ts

@@ -1077,15 +1077,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 +1092,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>;
@@ -1137,7 +1125,6 @@ declare const AssistantConfigSchema: z.ZodObject<{
             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<{
@@ -1375,6 +1362,7 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         reason: z.ZodEnum<{
             thinking_delta: "thinking_delta";
             message_dequeued: "message_dequeued";
+            message_interrupted: "message_interrupted";
             first_text_delta: "first_text_delta";
             tool_use_start: "tool_use_start";
             preview_start: "preview_start";
@@ -2049,6 +2037,10 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
             filePath: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
         attachmentWarnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        assistantTextVisibility: z.ZodOptional<z.ZodEnum<{
+            private: "private";
+            visible: "visible";
+        }>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"message_dequeued">;
         conversationId: z.ZodString;
@@ -2898,6 +2890,7 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     reason: z.ZodEnum<{
         thinking_delta: "thinking_delta";
         message_dequeued: "message_dequeued";
+        message_interrupted: "message_interrupted";
         first_text_delta: "first_text_delta";
         tool_use_start: "tool_use_start";
         preview_start: "preview_start";
@@ -3572,6 +3565,10 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         filePath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     attachmentWarnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    assistantTextVisibility: z.ZodOptional<z.ZodEnum<{
+        private: "private";
+        visible: "visible";
+    }>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"message_dequeued">;
     conversationId: z.ZodString;
@@ -4238,6 +4235,18 @@ declare interface BaseSubscriberEntry {
  */
 export declare function buildMessageExcerpt(rawContent: string, query: string): Promise<string>;
 
+/**
+ * The turn-cancellation guard every side-effecting tool calls, host tools and
+ * plugin tools alike. It lives on the plugin API surface because that is the
+ * only module a plugin may import from, and the guard must be one
+ * implementation rather than a copy per side of the boundary.
+ */
+/** The slice of a tool's context this guard reads. */
+export declare interface CancellableToolContext {
+    /** Cooperative cancellation signal for the turn, when the caller supplies one. */
+    signal?: AbortSignal;
+}
+
 /**
  * Conversation-type axis within an adapter (the "channel-type" cascade
  * level): direct message, private channel/group, public channel. Adapters
@@ -4827,6 +4836,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>;
 
@@ -4868,6 +4878,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";
 };
 
 /**
@@ -5271,8 +5283,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
@@ -5513,6 +5523,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 {
@@ -5611,6 +5652,7 @@ declare const messageMetadataSchema: z.ZodObject<{
     hidden: z.ZodOptional<z.ZodBoolean>;
     voiceSessionTurn: z.ZodOptional<z.ZodBoolean>;
     messageKind: z.ZodOptional<z.ZodString>;
+    assistantTextVisibility: z.ZodOptional<z.ZodString>;
     providerErrorCode: z.ZodOptional<z.ZodString>;
     providerErrorCategory: z.ZodOptional<z.ZodString>;
     backgroundToolCompletion: z.ZodOptional<z.ZodObject<{
@@ -5631,6 +5673,7 @@ declare const messageMetadataSchema: z.ZodObject<{
     forkSourceMessageId: z.ZodOptional<z.ZodString>;
     imageSourcePaths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     attachmentStoredPaths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    interruptedPriorTurn: z.ZodOptional<z.ZodBoolean>;
     memoryInjectedBlock: z.ZodOptional<z.ZodString>;
     memoryV3InjectedBlock: z.ZodOptional<z.ZodString>;
     memoryV3InjectedBlockFormat: z.ZodOptional<z.ZodNumber>;
@@ -5947,6 +5990,28 @@ declare interface PostModelCallInputContext {
     messages: Message[];
     /** Provider-reported stop reason for the turn; `null` when not reported. */
     readonly stopReason: string | null;
+    /**
+     * True when this run's plain assistant text does not reach the user: the
+     * turn routes its reply through the `send_user_message` tool instead, and
+     * {@link content}'s text blocks are private working notes. A hook that
+     * decides whether the user was answered must read this rather than assume
+     * visible text was delivered. Absent or false on every ordinary run, so a
+     * hook reads it as `=== true`.
+     */
+    readonly assistantTextSuppressed?: boolean;
+    /**
+     * Whether the user has already been told the OUTCOME of this run's work,
+     * decided by the host so a hook cannot reach a different answer than the
+     * loop does.
+     *
+     * True when the last response that called any tool reported on the work
+     * before it: every one of its tool calls delivered a message to the user. A
+     * response that sends a message alongside other tool calls is a progress
+     * update, and a call the executor rejects (blank or non-string message)
+     * delivers nothing, so neither counts. Absent on a host that does not
+     * compute it, so a hook reads it as `=== true`.
+     */
+    readonly userToldOutcome?: boolean;
     /**
      * The provider rejection that ended the call, on a rejection outcome. Absent
      * on a finalized reply. A hook that recovers from a specific rejection class
@@ -7410,6 +7475,22 @@ export declare interface ThinkingContent {
     signature: string;
 }
 
+/**
+ * Stop a side-effecting tool whose turn was cancelled before it acted.
+ *
+ * Call this immediately before the step that changes something the user would
+ * notice: a write, a create/update/delete, a message send, a process spawn, a
+ * paid provider call. The agent loop tells the model an aborted batch was
+ * cancelled, so anything that lands after the abort is work the model believes
+ * never happened.
+ *
+ * Throws the signal's own reason, which is the daemon's tagged abort reason
+ * for a conversation abort and a `DOMException` named `AbortError` for a plain
+ * one. The tool executor recognizes both and reports the call as an expected
+ * cancellation rather than a tool failure.
+ */
+export declare function throwIfCancelled(context: CancellableToolContext): void;
+
 /** Discriminated container so future tools can add their own metadata. */
 declare interface ToolActivityMetadata {
     webSearch?: WebSearchMetadata;
@@ -7502,6 +7583,12 @@ export declare interface ToolContext {
      * @legacy
      */
     diskPressureCleanupModeActive?: boolean;
+    /**
+     * Whether this turn routes its user-facing text through `send_user_message`.
+     * Read by the cleanup-mode gate, which keeps that tool callable on a gated
+     * turn: the wire offers it, so the executor must not refuse it.
+     */
+    sendUserMessageActive?: boolean;
     /**
      * Prompt the user for a secret value via native SecureField UI.
      * @legacy

package/index.js

@@ -61,4 +61,5 @@ export const stringifyMessageContent = api.stringifyMessageContent;
 export const sweepOrphanedGraphNodePoints = api.sweepOrphanedGraphNodePoints;
 export const syncMessageToDisk = api.syncMessageToDisk;
 export const synthesizeText = api.synthesizeText;
+export const throwIfCancelled = api.throwIfCancelled;
 export const updateMessageMetadata = api.updateMessageMetadata;

package/package.json

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