@vellumai/plugin-api 0.11.7 → 0.11.8-dev.202609020238.afcca64

package/index.d.ts

@@ -31,6 +31,17 @@ declare interface AddMessageOptions {
      *  internally. Pass the same value as `requestId` for user turns so
      *  the persisted row ID matches the runtime correlation ID. */
     id?: string;
+    /**
+     * Answered synchronously at the top of every insert attempt, immediately
+     * before that attempt's statement. False aborts with a
+     * {@link MessageInsertPreconditionError} and writes nothing.
+     *
+     * For a caller whose right to write can lapse while the insert is in
+     * flight. Per attempt rather than per call because contention retries the
+     * insert after an awaited backoff, and the world can move under a caller
+     * during that sleep.
+     */
+    insertPrecondition?: () => boolean;
 }
 
 declare type AddMessageResult = Awaited<ReturnType<addMessage_2>>;
@@ -1065,6 +1076,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
         }>>;
         vad: z.ZodDefault<z.ZodObject<{
             speechEnergyThreshold: z.ZodDefault<z.ZodNumber>;
+            noiseFloorMargin: z.ZodDefault<z.ZodNumber>;
             silenceThresholdMs: z.ZodDefault<z.ZodNumber>;
             maxTurnDurationMs: z.ZodDefault<z.ZodNumber>;
             bargeInMinSpeechMs: z.ZodDefault<z.ZodNumber>;
@@ -1098,6 +1110,9 @@ declare const AssistantConfigSchema: z.ZodObject<{
         maxSessionDurationSeconds: z.ZodDefault<z.ZodNumber>;
         archiveAudio: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
+    sight: z.ZodDefault<z.ZodObject<{
+        keepLatestFrames: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
     whatsapp: z.ZodDefault<z.ZodObject<{
         phoneNumber: z.ZodDefault<z.ZodString>;
         deliverAuthBypass: z.ZodDefault<z.ZodBoolean>;
@@ -1479,6 +1494,34 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         causedByRequestId: z.ZodOptional<z.ZodString>;
         decisionText: z.ZodOptional<z.ZodString>;
         toolUseId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"contact_form_closed">;
+        requestId: z.ZodString;
+        reason: z.ZodEnum<{
+            cancelled: "cancelled";
+            timed_out: "timed_out";
+            answered: "answered";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"contact_record_request">;
+        requestId: z.ZodString;
+        operation: z.ZodEnum<{
+            delete: "delete";
+            create: "create";
+            update: "update";
+        }>;
+        contactId: z.ZodOptional<z.ZodString>;
+        currentDisplayName: z.ZodOptional<z.ZodString>;
+        currentNotes: z.ZodOptional<z.ZodString>;
+        channels: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            address: z.ZodString;
+        }, z.core.$strip>>>;
+        displayName: z.ZodOptional<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
+        notesProposed: z.ZodOptional<z.ZodBoolean>;
+        label: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"contact_request">;
         requestId: z.ZodString;
@@ -1488,6 +1531,7 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         label: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
         role: z.ZodOptional<z.ZodString>;
+        verify: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"contacts_changed">;
     }, z.core.$strip>, z.ZodObject<{
@@ -1907,8 +1951,8 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
             approved: "approved";
             cancelled: "cancelled";
             superseded: "superseded";
-            rejected: "rejected";
             answered: "answered";
+            rejected: "rejected";
         }>;
         kind: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
@@ -2970,6 +3014,34 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     causedByRequestId: z.ZodOptional<z.ZodString>;
     decisionText: z.ZodOptional<z.ZodString>;
     toolUseId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"contact_form_closed">;
+    requestId: z.ZodString;
+    reason: z.ZodEnum<{
+        cancelled: "cancelled";
+        timed_out: "timed_out";
+        answered: "answered";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"contact_record_request">;
+    requestId: z.ZodString;
+    operation: z.ZodEnum<{
+        delete: "delete";
+        create: "create";
+        update: "update";
+    }>;
+    contactId: z.ZodOptional<z.ZodString>;
+    currentDisplayName: z.ZodOptional<z.ZodString>;
+    currentNotes: z.ZodOptional<z.ZodString>;
+    channels: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        address: z.ZodString;
+    }, z.core.$strip>>>;
+    displayName: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    notesProposed: z.ZodOptional<z.ZodBoolean>;
+    label: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"contact_request">;
     requestId: z.ZodString;
@@ -2979,6 +3051,7 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     role: z.ZodOptional<z.ZodString>;
+    verify: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"contacts_changed">;
 }, z.core.$strip>, z.ZodObject<{
@@ -3398,8 +3471,8 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         approved: "approved";
         cancelled: "cancelled";
         superseded: "superseded";
-        rejected: "rejected";
         answered: "answered";
+        rejected: "rejected";
     }>;
     kind: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
@@ -4030,6 +4103,26 @@ export declare interface AssistantEventSubscription {
     readonly connectionId: string;
 }
 
+/**
+ * The `_attachmentId` property as a spreadable fragment, or nothing when there
+ * is no usable id.
+ *
+ * Every producer of a media block faces the same choice: it either knows the
+ * attachment row the block came from, or it does not, and the field has to be
+ * absent rather than present-and-empty in the second case. This helper is the
+ * one place that decision lives, so every producer answers it the same way.
+ * Callers pass whatever id they hold: the source block's own
+ * ({@link ImageContent._attachmentId}) when carrying it across a rebuild, or an
+ * upload's row id when stamping a fresh block.
+ *
+ * Empty counts as absent, matching the read side, which requires a non-empty
+ * string before it will treat the field as an id (see
+ * `daemon/handlers/shared.ts`).
+ */
+export declare function attachmentIdFragment(attachmentId: string | undefined): {
+    _attachmentId?: string;
+};
+
 export declare interface AudioEmbeddingInput {
     type: "audio";
     data: Buffer;
@@ -4744,6 +4837,19 @@ declare type HostProxyCapability = (typeof HOST_PROXY_CAPABILITIES)[number];
 export declare interface ImageContent {
     type: "image";
     source: MediaSource_2;
+    /**
+     * Internal id linking a base64 image block to a row in the attachments table,
+     * the same correlation {@link FileContent._attachmentId} carries. A live turn
+     * sends its uploads inline while persisting them as references, so this is
+     * the only handle on the in-memory copy of an image whose stored form is a
+     * `workspace_ref`; camera-frame retention matches on it. Redundant once the
+     * block is a reference (use `source.attachmentId`).
+     *
+     * Never reaches a provider: every client builds its image payload out of
+     * `source` alone (see the `case "image"` arms of the Anthropic, Gemini, and
+     * both OpenAI clients), so top-level fields are dropped by construction.
+     */
+    _attachmentId?: string;
 }
 
 export declare interface ImageEmbeddingInput {
@@ -5032,11 +5138,12 @@ declare interface LiveVoiceErrorServerFrame extends LiveVoiceServerFrameBase {
      * 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.
+     * than one optional frame (today: `update_config`, `attach_image`,
+     * `attach_frame`, `sight_frame`, and `text`) gets the same code for any of
+     * them, 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;
     /**
@@ -5045,6 +5152,23 @@ declare interface LiveVoiceErrorServerFrame extends LiveVoiceServerFrameBase {
      * from older daemons) means the error is terminal for the session.
      */
     readonly recoverable?: boolean;
+    /**
+     * The attachment the refused frame named, present on `sight_frame`
+     * rejections so the client can retire the exact keep that failed.
+     *
+     * `frameType` alone only narrows a rejection to the keep stream, and that
+     * stream is the one place several sends are routinely outstanding at once:
+     * the camera keeps shooting while a persist waits out a running turn, so a
+     * client holding three unacknowledged keeps cannot tell which of them this
+     * error is about. Naming the id is what turns "a frame failed" into "this
+     * preview comes down".
+     *
+     * Optional, and no other error path populates it: a parse failure has no
+     * id to name, and the other frames carrying an attachment have at most one
+     * in flight, which `frameType` already identifies. Clients must tolerate
+     * an absent id and must not gate any behavior on its presence.
+     */
+    readonly attachmentId?: string;
 }
 
 /**
@@ -5314,6 +5438,21 @@ declare const LLMCallSiteEnum: z.ZodEnum<{
     workflowLeaf: "workflowLeaf";
 }>;
 
+/**
+ * The attachment row a media block came from, whichever of the two shapes it
+ * is in, or undefined for a block that came from none (tool-generated and
+ * assistant-authored media).
+ *
+ * A reference names its row on `source.attachmentId`; an inline block has
+ * nowhere to put it but the top-level `_attachmentId`. Both are the same fact,
+ * so anything asking "which attachment is this?" has to read both or it goes
+ * blind on half the histories. Reading only `_attachmentId` in particular is
+ * the sharp edge: it is absent on every reference block, so a rebuild that
+ * flattens a reference to inline bytes drops the link unless it derives the id
+ * through here first.
+ */
+export declare function mediaBlockAttachmentId(block: ImageContent | FileContent): string | undefined;
+
 declare type MediaSource_2 = Base64MediaSource | WorkspaceRefMediaSource;
 
 export declare interface Message {

package/index.js

@@ -11,6 +11,7 @@ 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 attachmentIdFragment = api.attachmentIdFragment;
 export const buildMessageExcerpt = api.buildMessageExcerpt;
 export const createLiveVoiceConnection = api.createLiveVoiceConnection;
 export const deleteConversation = api.deleteConversation;
@@ -38,6 +39,7 @@ export const lastToolResultUserMessageIndex = api.lastToolResultUserMessageIndex
 export const listCatalogSkills = api.listCatalogSkills;
 export const listConversations = api.listConversations;
 export const listInstalledSkills = api.listInstalledSkills;
+export const mediaBlockAttachmentId = api.mediaBlockAttachmentId;
 export const openTranscriptionSession = api.openTranscriptionSession;
 export const parseMessageMetadata = api.parseMessageMetadata;
 export const persistSystemCard = api.persistSystemCard;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.11.7",
+  "version": "0.11.8-dev.202609020238.afcca64",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",