@vellumai/plugin-api 0.10.7-dev.202607081046.662cc92 → 0.10.7-dev.202607081138.e95f760

package/index.d.ts

@@ -508,6 +508,33 @@ declare interface BackgroundToolStarted {
     startedAt: number;
 }
 
+/**
+ * Media payload for an image or file content block. One unified type covers
+ * both blocks and both storage forms:
+ *
+ * - `base64` — the bytes travel inline with the block. This is the runtime
+ *   shape the provider transforms consume and the shape produced for a live
+ *   (in-flight) turn.
+ * - `workspace_ref` — the bytes live somewhere in the workspace, not inline.
+ *   This is the shape PERSISTED into `messages.content`, keeping large blobs
+ *   out of the DB row and the lexical index. It is resolved back to inline
+ *   bytes at the provider send boundary (`providers/media-resolve.ts`); any
+ *   consumer that needs the raw bytes from stored content resolves it with
+ *   `resolveMediaSourceData(source)`.
+ *
+ * `filename` is optional on both arms (present for file blocks and for
+ * generated-media references). For references, `sizeBytes` (and, for images,
+ * `width`/`height`) are captured at persist time so size-only consumers — the
+ * per-turn token estimator especially — can cost the block without reading the
+ * file back off disk.
+ */
+declare interface Base64MediaSource {
+    type: "base64";
+    media_type: string;
+    data: string;
+    filename?: string;
+}
+
 /**
  * A single assistant event wrapping an outbound message payload.
  *
@@ -1494,20 +1521,15 @@ declare interface ExecutorTelemetryStamp {
 
 export declare interface FileContent {
     type: "file";
-    source: {
-        type: "base64";
-        media_type: string;
-        data: string;
-        filename: string;
-    };
+    source: MediaSource_2;
     extracted_text?: string;
     /**
-     * Internal id linking this block to a row in the attachments table.
-     * Set when the file block originates from a persisted user-message
-     * attachment so downstream consumers (DB joins, inline-chip
-     * positioning) can correlate the block back to its attachment id.
-     * Stripped by `daemon/handlers/shared.ts` before sending to the
-     * model.
+     * Internal id linking a base64 file block to a row in the attachments table
+     * so consumers (DB joins, inline-chip positioning) can correlate the block
+     * back to its attachment. Redundant once the block is a reference (use
+     * `source.attachmentId`); retained only while file media is still persisted
+     * inline as base64, and removed when file uploads move to references.
+     * Stripped by `daemon/handlers/shared.ts` before sending to the model.
      */
     _attachmentId?: string;
 }
@@ -2263,11 +2285,7 @@ declare interface IdentityGetResponse {
 
 export declare interface ImageContent {
     type: "image";
-    source: {
-        type: "base64";
-        media_type: string;
-        data: string;
-    };
+    source: MediaSource_2;
 }
 
 declare type _InboxServerMessages = ContactsInviteResponse | AssistantInboxEscalationResponse;
@@ -2446,6 +2464,8 @@ declare const LLMCallSiteEnum: z.ZodEnum<{
     workflowLeaf: "workflowLeaf";
 }>;
 
+declare type MediaSource_2 = Base64MediaSource | WorkspaceRefMediaSource;
+
 declare interface MemoryRecalled {
     type: "memory_recalled";
     provider: string;
@@ -3368,6 +3388,17 @@ declare const RelationshipStateUpdatedEventSchema: z.ZodObject<{
     updatedAt: z.ZodString;
 }, z.core.$strip>;
 
+/**
+ * Resolve a media source to inline base64, reading a reference source back from
+ * its workspace location. Returns `null` when a reference can no longer be
+ * read. For consumers that hold an individual in-memory block (image
+ * captioning, media retry) and need its bytes outside the provider transform.
+ */
+export declare function resolveMediaSourceData(source: MediaSource_2): {
+    data: string;
+    media_type: string;
+} | null;
+
 export declare enum RiskLevel {
     Low = "low",
     Medium = "medium",
@@ -5442,6 +5473,31 @@ declare interface WorkspaceFilesListResponse {
     }>;
 }
 
+/**
+ * A reference to bytes stored in the workspace rather than inlined. The bytes
+ * live in the workspace attachment store, addressed by `attachmentId`, and are
+ * read back at the provider send boundary. User uploads are attachment rows
+ * already; tool-result media is materialized into attachment rows before it is
+ * referenced, so a single `attachmentId` resolves every case and needs no
+ * fallback locator.
+ *
+ * `sizeBytes` (and, for images, `width`/`height`) are the persist-time hints
+ * that let size-only consumers cost the block without a disk read.
+ */
+declare interface WorkspaceRefMediaSource {
+    type: "workspace_ref";
+    media_type: string;
+    /** Attachment row id; resolves to bytes via the attachment store. */
+    attachmentId: string;
+    /** Byte length of the referenced file. */
+    sizeBytes: number;
+    filename?: string;
+    /** Decoded pixel width, when the reference is an image. */
+    width?: number;
+    /** Decoded pixel height, when the reference is an image. */
+    height?: number;
+}
+
 declare type _WorkspaceServerMessages = WorkspaceFilesListResponse | WorkspaceFileReadResponse | IdentityGetResponse | ToolPermissionSimulateResponse | ToolNamesListResponse | IdentityChangedEvent;
 
 export { }

package/index.js

@@ -7,3 +7,4 @@ export const doesSupportVision = api.doesSupportVision;
 export const getConfiguredProvider = api.getConfiguredProvider;
 export const getModelProfiles = api.getModelProfiles;
 export const isMaxTokensStopReason = api.isMaxTokensStopReason;
+export const resolveMediaSourceData = api.resolveMediaSourceData;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.10.7-dev.202607081046.662cc92",
+  "version": "0.10.7-dev.202607081138.e95f760",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",