@vellumai/plugin-api 0.11.8-staging.2 → 0.11.9-dev.202609040043.7972a34

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>>;
@@ -301,6 +312,12 @@ declare const AssistantConfigSchema: z.ZodObject<{
                 "your-own": "your-own";
             }>>;
         }, z.core.$strip>>;
+        "figma-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";
@@ -705,7 +722,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
             fallbackProfile: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
         profileOrder: z.ZodDefault<z.ZodArray<z.ZodString>>;
-        callSites: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
+        callSites: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodDefault<z.ZodRecord<z.ZodEnum<{
             mainAgent: "mainAgent";
             subagentSpawn: "subagentSpawn";
             heartbeatAgent: "heartbeatAgent";
@@ -811,7 +828,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
             }>>;
             disableCache: z.ZodOptional<z.ZodBoolean>;
             profile: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
+        }, z.core.$strip>>>>;
         activeProfile: z.ZodOptional<z.ZodString>;
         advisorProfile: z.ZodOptional<z.ZodString>;
         defaultProvider: z.ZodCatch<z.ZodOptional<z.ZodObject<{
@@ -1498,6 +1515,7 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
             delete: "delete";
             create: "create";
             update: "update";
+            merge: "merge";
         }>;
         contactId: z.ZodOptional<z.ZodString>;
         currentDisplayName: z.ZodOptional<z.ZodString>;
@@ -1506,6 +1524,12 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
             type: z.ZodString;
             address: z.ZodString;
         }, z.core.$strip>>>;
+        donorContactId: z.ZodOptional<z.ZodString>;
+        donorDisplayName: z.ZodOptional<z.ZodString>;
+        donorChannels: 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>;
@@ -1521,6 +1545,10 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
         role: z.ZodOptional<z.ZodString>;
         verify: z.ZodOptional<z.ZodBoolean>;
+        contactId: z.ZodOptional<z.ZodString>;
+        contactDisplayName: z.ZodOptional<z.ZodString>;
+        displayName: z.ZodOptional<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"contacts_changed">;
     }, z.core.$strip>, z.ZodObject<{
@@ -1579,15 +1607,6 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
         profile: z.ZodNullable<z.ZodString>;
         sessionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         expiresAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    }, z.core.$strip>, z.ZodObject<{
-        type: z.ZodLiteral<"conversation_list_invalidated">;
-        reason: z.ZodEnum<{
-            deleted: "deleted";
-            created: "created";
-            renamed: "renamed";
-            reordered: "reordered";
-            seen_changed: "seen_changed";
-        }>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"conversation_notice">;
         conversationId: z.ZodString;
@@ -2617,9 +2636,7 @@ export declare class AssistantEventHub {
      *   it receive the event; untargeted events go to all
      * - if `targetInterfaceId` is set, only client subscribers whose
      *   `interfaceId` matches receive the event; process subscribers and
-     *   non-matching clients are skipped. Used to narrow legacy
-     *   broadcasts (e.g. `conversation_list_invalidated`) to a specific
-     *   client surface during a migration window.
+     *   non-matching clients are skipped.
      *
      * Fanout is isolated: a throwing or rejecting subscriber does not abort
      * delivery to remaining subscribers.
@@ -2752,6 +2769,7 @@ declare const AssistantEventPublishOptionsSchema: z.ZodObject<{
         ios: "ios";
         macos: "macos";
         windows: "windows";
+        linux: "linux";
         cli: "cli";
         "chrome-extension": "chrome-extension";
         route: "route";
@@ -3018,6 +3036,7 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         delete: "delete";
         create: "create";
         update: "update";
+        merge: "merge";
     }>;
     contactId: z.ZodOptional<z.ZodString>;
     currentDisplayName: z.ZodOptional<z.ZodString>;
@@ -3026,6 +3045,12 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodString;
         address: z.ZodString;
     }, z.core.$strip>>>;
+    donorContactId: z.ZodOptional<z.ZodString>;
+    donorDisplayName: z.ZodOptional<z.ZodString>;
+    donorChannels: 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>;
@@ -3041,6 +3066,10 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     role: z.ZodOptional<z.ZodString>;
     verify: z.ZodOptional<z.ZodBoolean>;
+    contactId: z.ZodOptional<z.ZodString>;
+    contactDisplayName: z.ZodOptional<z.ZodString>;
+    displayName: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"contacts_changed">;
 }, z.core.$strip>, z.ZodObject<{
@@ -3099,15 +3128,6 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     profile: z.ZodNullable<z.ZodString>;
     sessionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     expiresAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"conversation_list_invalidated">;
-    reason: z.ZodEnum<{
-        deleted: "deleted";
-        created: "created";
-        renamed: "renamed";
-        reordered: "reordered";
-        seen_changed: "seen_changed";
-    }>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"conversation_notice">;
     conversationId: z.ZodString;
@@ -4286,7 +4306,7 @@ declare interface CliCommandHelp {
  * than polluting the interface vocabulary. Drives only the per-turn
  * `client_os` context line (e.g. app-builder mobile-first for `ios`/`android`).
  */
-declare const CLIENT_OS_VALUES: readonly ["web", "ios", "macos", "windows", "android"];
+declare const CLIENT_OS_VALUES: readonly ["web", "ios", "macos", "windows", "linux", "android"];
 
 declare interface ClientEntry extends BaseSubscriberEntry {
     type: "client";
@@ -4573,8 +4593,12 @@ export declare class CredentialStoreError 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.
+ * The presence states a desktop client may report. Single runtime source for
+ * the daemon's stored type, the client route's wire enum, and the Electron
+ * presence monitor.
+ *
+ * Member order is load-bearing: the route feeds this tuple to `z.enum`, so
+ * reordering rewrites the generated `assistant/openapi.yaml`.
  */
 declare const DESKTOP_PRESENCE_STATES: readonly ["active", "idle", "away"];
 
@@ -4816,8 +4840,8 @@ export declare const HOOKS: {
 
 /**
  * Host proxy capabilities that an interface can support. macOS supports all
- * of them, Windows withholds app control, and chrome-extension supports only
- * host_browser through the Chrome DevTools Protocol proxy.
+ * of them, Windows and Linux withhold app control, and chrome-extension
+ * supports only host_browser through the Chrome DevTools Protocol proxy.
  */
 declare const HOST_PROXY_CAPABILITIES: readonly ["host_bash", "host_file", "host_cu", "host_browser", "host_app_control", "host_ui_snapshot"];
 
@@ -4935,7 +4959,7 @@ declare interface InsertedMessage {
     deduplicated: boolean;
 }
 
-declare const INTERFACE_IDS: readonly ["macos", "windows", "ios", "cli", "telegram", "phone", "web", "whatsapp", "slack", "email", "chrome-extension", "a2a", "discord", "route", "plugin"];
+declare const INTERFACE_IDS: readonly ["macos", "windows", "linux", "ios", "cli", "telegram", "phone", "web", "whatsapp", "slack", "email", "chrome-extension", "a2a", "discord", "route", "plugin"];
 
 declare type InterfaceId = (typeof INTERFACE_IDS)[number];
 
@@ -5141,6 +5165,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;
 }
 
 /**
@@ -5484,8 +5525,8 @@ declare const messageMetadataSchema: z.ZodObject<{
         discord: "discord";
         plugin: "plugin";
     }>>;
-    userMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"phone" | "telegram" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "plugin" | "web" | "ios" | "macos" | "windows" | "cli" | "chrome-extension" | "route" | null, string>> & z.ZodType<"phone" | "telegram" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "plugin" | "web" | "ios" | "macos" | "windows" | "cli" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"phone" | "telegram" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "plugin" | "web" | "ios" | "macos" | "windows" | "cli" | "chrome-extension" | "route", string>>>;
-    assistantMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"phone" | "telegram" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "plugin" | "web" | "ios" | "macos" | "windows" | "cli" | "chrome-extension" | "route" | null, string>> & z.ZodType<"phone" | "telegram" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "plugin" | "web" | "ios" | "macos" | "windows" | "cli" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"phone" | "telegram" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "plugin" | "web" | "ios" | "macos" | "windows" | "cli" | "chrome-extension" | "route", string>>>;
+    userMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"phone" | "telegram" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "plugin" | "web" | "ios" | "macos" | "windows" | "linux" | "cli" | "chrome-extension" | "route" | null, string>> & z.ZodType<"phone" | "telegram" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "plugin" | "web" | "ios" | "macos" | "windows" | "linux" | "cli" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"phone" | "telegram" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "plugin" | "web" | "ios" | "macos" | "windows" | "linux" | "cli" | "chrome-extension" | "route", string>>>;
+    assistantMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"phone" | "telegram" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "plugin" | "web" | "ios" | "macos" | "windows" | "linux" | "cli" | "chrome-extension" | "route" | null, string>> & z.ZodType<"phone" | "telegram" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "plugin" | "web" | "ios" | "macos" | "windows" | "linux" | "cli" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"phone" | "telegram" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "plugin" | "web" | "ios" | "macos" | "windows" | "linux" | "cli" | "chrome-extension" | "route", string>>>;
     client: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     clientOsFromRequest: z.ZodOptional<z.ZodBoolean>;
     subagentNotification: z.ZodOptional<z.ZodObject<{
@@ -5552,6 +5593,7 @@ declare const messageMetadataSchema: z.ZodObject<{
     attachmentStoredPaths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     memoryInjectedBlock: z.ZodOptional<z.ZodString>;
     memoryV3InjectedBlock: z.ZodOptional<z.ZodString>;
+    memoryV3SpotlightBlock: z.ZodOptional<z.ZodString>;
     turnContextBlock: z.ZodOptional<z.ZodString>;
     pkbSystemReminderBlock: z.ZodOptional<z.ZodString>;
     workspaceBlock: z.ZodOptional<z.ZodString>;
@@ -6735,10 +6777,7 @@ export declare interface SendMessageConfig {
     /**
      * 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).
+     * on it could never be read back across turns.
      *
      * The flag describes the turn, not the request, so it holds for every
      * request the turn makes, including tool-loop iterations, whose trailing
@@ -7683,6 +7722,7 @@ declare const ToolDefinitionSchema: z.ZodObject<{
         macos: "macos";
         windows: "windows";
         android: "android";
+        linux: "linux";
     }>>>;
     execute: z.ZodOptional<z.ZodCustom<(input: Record<string, unknown>, context: ToolContext) => Promise<ToolExecutionResult>, (input: Record<string, unknown>, context: ToolContext) => Promise<ToolExecutionResult>>>;
     exclusive: z.ZodOptional<z.ZodBoolean>;

package/package.json

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