@mindstudio-ai/agent 0.1.87 → 0.1.89

package/dist/index.d.ts

@@ -1,3 +1,159 @@
+/**
+ * Access level of a file store. `private` (the default) → reads are signed /
+ * session-authorized; `public` → world-readable, CDN-served on the app's own
+ * domain (and resizable via image query params).
+ */
+type FileAccess = 'public' | 'private';
+/** Options for {@link Store.put}. */
+interface PutOptions {
+    /**
+     * Object key within the store (nested paths allowed, e.g. `reports/q1.pdf`).
+     * Omit to auto-generate a UUID key (with `filename`'s extension, if given).
+     */
+    key?: string;
+    /** MIME type stored on the object and returned on read. */
+    contentType?: string;
+    /** Original filename — used only to derive an extension when `key` is omitted. */
+    filename?: string;
+    /**
+     * When true (and no explicit `key`), derive the key from a content hash
+     * (`<sha256>.<ext>`) instead of a random UUID — immutable + idempotent, so
+     * re-uploading identical bytes yields the same key/URL. Ideal for public
+     * assets baked into source.
+     */
+    contentAddressed?: boolean;
+}
+/** Options for {@link Store.list}. */
+interface ListOptions {
+    /** Restrict to keys under this prefix (relative to the store). */
+    prefix?: string;
+    /** Pagination cursor from a previous page. */
+    cursor?: string;
+    /** Max objects per page. */
+    limit?: number;
+}
+/** A stored object plus a ready-to-use URL. */
+interface StoredFile {
+    store: string;
+    key: string;
+    access: FileAccess;
+    size?: number;
+    contentType?: string;
+    updatedAt?: string;
+    /**
+     * Stable, on-domain URL for the app's own frontend — drop straight into
+     * `<img src>`, `fetch`, or `<a download>`. Relative (resolves against the
+     * app's origin); a same-origin logged-in request authorizes automatically
+     * via the app session, so there's nothing to await.
+     */
+    url: string;
+    /**
+     * Mint an ABSOLUTE, signed share URL that works with **no** active session —
+     * email it, or embed it on another site. Expires (default 24h). Private
+     * stores only.
+     */
+    shareUrl(options?: {
+        expiresIn?: number;
+    }): Promise<string>;
+}
+/**
+ * A token for a client-direct upload, from {@link Store.createUploadToken}.
+ * Return it from a backend method and pass it straight to the frontend's
+ * `platform.upload(token, file)` — the browser then POSTs the file directly to
+ * storage (no bytes through the platform).
+ */
+interface UploadToken {
+    /** The object key the upload will land at (within the store). */
+    key: string;
+    /** The stable on-domain URL the file will be readable at once uploaded. */
+    url: string;
+    /** @internal The scoped presigned POST the frontend submits to. */
+    upload: {
+        url: string;
+        fields: Record<string, string>;
+    };
+}
+/** @internal Per-store upload policy carried from `defineStore`. */
+interface StorePolicy {
+    maxSize?: number;
+    contentTypes?: string[];
+}
+/** @internal Transport: `POST /_internal/v2/files/<op>` with the hook token. */
+type FilesTransport = (op: string, body: unknown) => Promise<any>;
+/**
+ * A typed handle to one named file store. Lazy — nothing executes until a
+ * method is awaited, so it's safe to `defineStore()` at module scope and import
+ * the handle into route handlers (same ergonomics as `db.defineTable`).
+ */
+declare class Store {
+    private readonly _store;
+    private readonly _access;
+    private readonly _call;
+    private readonly _policy;
+    constructor(_store: string, _access: FileAccess, _call: FilesTransport, _policy?: StorePolicy);
+    /** The store's name. */
+    get name(): string;
+    /** The store's access level. */
+    get access(): FileAccess;
+    /** Store bytes. Returns a {@link StoredFile} with a ready-to-use `url`. */
+    put(content: Buffer | Uint8Array | string, options?: PutOptions): Promise<StoredFile>;
+    /** Read an object's bytes (backend / trusted context). */
+    get(key: string): Promise<Buffer>;
+    /** Metadata without downloading. Rejects if the object doesn't exist. */
+    head(key: string): Promise<StoredFile>;
+    /** Whether an object exists. */
+    exists(key: string): Promise<boolean>;
+    /** List objects in the store (optionally under `prefix`), one page at a time. */
+    list(options?: ListOptions): Promise<{
+        files: StoredFile[];
+        cursor?: string;
+    }>;
+    /** Delete an object. No-op if it doesn't exist. */
+    delete(key: string): Promise<void>;
+    /**
+     * Mint an ABSOLUTE, signed share URL for a key — works with **no** active
+     * session (email it, or embed it on another site). Expires (default 24h).
+     * Private stores only.
+     *
+     * The same link is available as `file.shareUrl()` on a {@link StoredFile};
+     * this convenience skips the `head()` when you already hold just the key.
+     */
+    shareUrl(key: string, options?: {
+        expiresIn?: number;
+    }): Promise<string>;
+    /**
+     * Mint an {@link UploadToken} for a **client-direct** upload — the browser
+     * POSTs the file straight to storage, so the bytes never pass through the
+     * platform. Return the token from a backend method and hand it to the
+     * frontend's `platform.upload(token, file)`. Works for private + public stores.
+     *
+     * Enforced at upload time by the presigned POST: a max size (this call's
+     * `maxSize`, else the store's, else the platform default) and — when
+     * `contentType` is set — an exact content-type match. When the store declares
+     * `contentTypes`, `contentType` must be one of them.
+     *
+     * Note: a presigned POST can pin exactly ONE content-type per token, so the
+     * *allowlist* is declared on `defineStore({ contentTypes })` and each token
+     * pins one type from it. This is by design, not a per-token limitation.
+     *
+     * @example
+     * ```ts
+     * // backend method
+     * export async function getUploadSlot(input: { contentType: string }) {
+     *   return Uploads.createUploadToken({ contentType: input.contentType, maxSize: 50 * 1024 * 1024 });
+     * }
+     * ```
+     */
+    createUploadToken(options?: {
+        key?: string;
+        contentType?: string;
+        filename?: string;
+        maxSize?: number;
+        expiresIn?: number;
+    }): Promise<UploadToken>;
+    private _toFile;
+}
+
 /** Configuration options for creating a {@link MindStudioAgent}. */
 interface AgentOptions {
     /**
@@ -83,6 +239,33 @@ interface StepExecutionOptions {
      * selection and token info.
      */
     onLog?: (event: StepLogEvent) => void;
+    /**
+     * Send any asset this step generates to one of the app's own file stores
+     * instead of the shared public MindStudio CDN.
+     *
+     * **Optional — the default is fine for most cases.** Omit it and generated
+     * assets keep going to the public CDN, exactly as before. Reach for it when
+     * the asset is user-specific, should be private, or belongs alongside the
+     * app's other files (where it shows up in the app's Files dashboard).
+     *
+     * The store's `access` comes from its `defineStore()`, so a private store
+     * yields a private asset — the returned URL is an on-domain
+     * `/_/files/private/...` link that only an authorized session can load,
+     * rather than a permanent public one.
+     *
+     * v2 apps only.
+     *
+     * @example
+     * ```ts
+     * const Photos = files.defineStore('product-photos', { access: 'public' });
+     *
+     * const { imageUrl } = await agent.generateImage(
+     *   { prompt: 'a red sneaker on concrete' },
+     *   { store: Photos },
+     * );
+     * ```
+     */
+    store?: Store;
 }
 /** Execution metadata returned alongside every step result. */
 interface StepExecutionMeta {
@@ -232,7 +415,7 @@ interface MindStudioModel {
     id?: string;
     /** Display name of the model. */
     name?: string;
-    /** One of: `llm_chat`, `image_generation`, `video_generation`, `video_analysis`, `text_to_speech`, `vision`, `transcription`. */
+    /** See `ModelType` for the full set. */
     type?: ModelType;
     maxTemperature?: number;
     maxResponseSize?: number;
@@ -244,13 +427,20 @@ interface MindStudioModelSummary {
     id?: string;
     /** Display name of the model. */
     name?: string;
-    /** One of: `llm_chat`, `image_generation`, `video_generation`, `video_analysis`, `text_to_speech`, `vision`, `transcription`. */
+    /** See `ModelType` for the full set. */
     type?: ModelType;
     /** Comma-separated tags for the model. */
     tags?: string;
 }
-/** Supported model type categories for filtering. */
-type ModelType = 'llm_chat' | 'image_generation' | 'video_generation' | 'video_analysis' | 'text_to_speech' | 'vision' | 'transcription';
+/**
+ * Supported model type categories for filtering.
+ *
+ * `embedding`, `reranking` and `document_extraction` have no SDK step — the
+ * data-source pipeline chooses those platform-side and reports the result on
+ * `pipeline.embeddingModelId`. They are listed so the catalog can be queried
+ * and described, not so they can be passed to a generate call.
+ */
+type ModelType = 'llm_chat' | 'image_generation' | '3d_generation' | 'video_generation' | 'video_analysis' | 'text_to_speech' | 'music_generation' | 'lipsync' | 'vision' | 'transcription' | 'embedding' | 'reranking' | 'document_extraction';
 /** Role assignment for a user within an app. */
 interface AppRoleAssignment {
     userId: string;
@@ -478,6 +668,12 @@ interface ExecuteStepBatchOptions {
     threadId?: string;
     /** Progress callback, called on each poll while the batch is running. */
     onProgress?: (completedSteps: number, totalSteps: number) => void;
+    /**
+     * Send assets generated by any step in this batch to one of the app's own
+     * file stores instead of the shared public MindStudio CDN. Optional; applies
+     * to every step in the batch. See {@link StepExecutionOptions.store}.
+     */
+    store?: Store;
 }
 /** Result of {@link MindStudioAgent.executeStepBatch}. */
 interface ExecuteStepBatchResult {
@@ -1292,160 +1488,6 @@ interface Db {
     batch(...queries: PromiseLike<unknown>[]): Promise<unknown[]>;
 }
 
-/**
- * Access level of a file store. `private` (the default) → reads are signed /
- * session-authorized; `public` → world-readable, CDN-served on the app's own
- * domain (and resizable via image query params).
- */
-type FileAccess = 'public' | 'private';
-/** Options for {@link Store.put}. */
-interface PutOptions {
-    /**
-     * Object key within the store (nested paths allowed, e.g. `reports/q1.pdf`).
-     * Omit to auto-generate a UUID key (with `filename`'s extension, if given).
-     */
-    key?: string;
-    /** MIME type stored on the object and returned on read. */
-    contentType?: string;
-    /** Original filename — used only to derive an extension when `key` is omitted. */
-    filename?: string;
-    /**
-     * When true (and no explicit `key`), derive the key from a content hash
-     * (`<sha256>.<ext>`) instead of a random UUID — immutable + idempotent, so
-     * re-uploading identical bytes yields the same key/URL. Ideal for public
-     * assets baked into source.
-     */
-    contentAddressed?: boolean;
-}
-/** Options for {@link Store.list}. */
-interface ListOptions {
-    /** Restrict to keys under this prefix (relative to the store). */
-    prefix?: string;
-    /** Pagination cursor from a previous page. */
-    cursor?: string;
-    /** Max objects per page. */
-    limit?: number;
-}
-/** A stored object plus a ready-to-use URL. */
-interface StoredFile {
-    store: string;
-    key: string;
-    access: FileAccess;
-    size?: number;
-    contentType?: string;
-    updatedAt?: string;
-    /**
-     * Stable, on-domain URL for the app's own frontend — drop straight into
-     * `<img src>`, `fetch`, or `<a download>`. Relative (resolves against the
-     * app's origin); a same-origin logged-in request authorizes automatically
-     * via the app session, so there's nothing to await.
-     */
-    url: string;
-    /**
-     * Mint an ABSOLUTE, signed share URL that works with **no** active session —
-     * email it, or embed it on another site. Expires (default 24h). Private
-     * stores only.
-     */
-    shareUrl(options?: {
-        expiresIn?: number;
-    }): Promise<string>;
-}
-/**
- * A token for a client-direct upload, from {@link Store.createUploadToken}.
- * Return it from a backend method and pass it straight to the frontend's
- * `platform.upload(token, file)` — the browser then POSTs the file directly to
- * storage (no bytes through the platform).
- */
-interface UploadToken {
-    /** The object key the upload will land at (within the store). */
-    key: string;
-    /** The stable on-domain URL the file will be readable at once uploaded. */
-    url: string;
-    /** @internal The scoped presigned POST the frontend submits to. */
-    upload: {
-        url: string;
-        fields: Record<string, string>;
-    };
-}
-/** @internal Per-store upload policy carried from `defineStore`. */
-interface StorePolicy {
-    maxSize?: number;
-    contentTypes?: string[];
-}
-/** @internal Transport: `POST /_internal/v2/files/<op>` with the hook token. */
-type FilesTransport = (op: string, body: unknown) => Promise<any>;
-/**
- * A typed handle to one named file store. Lazy — nothing executes until a
- * method is awaited, so it's safe to `defineStore()` at module scope and import
- * the handle into route handlers (same ergonomics as `db.defineTable`).
- */
-declare class Store {
-    private readonly _store;
-    private readonly _access;
-    private readonly _call;
-    private readonly _policy;
-    constructor(_store: string, _access: FileAccess, _call: FilesTransport, _policy?: StorePolicy);
-    /** The store's access level. */
-    get access(): FileAccess;
-    /** Store bytes. Returns a {@link StoredFile} with a ready-to-use `url`. */
-    put(content: Buffer | Uint8Array | string, options?: PutOptions): Promise<StoredFile>;
-    /** Read an object's bytes (backend / trusted context). */
-    get(key: string): Promise<Buffer>;
-    /** Metadata without downloading. Rejects if the object doesn't exist. */
-    head(key: string): Promise<StoredFile>;
-    /** Whether an object exists. */
-    exists(key: string): Promise<boolean>;
-    /** List objects in the store (optionally under `prefix`), one page at a time. */
-    list(options?: ListOptions): Promise<{
-        files: StoredFile[];
-        cursor?: string;
-    }>;
-    /** Delete an object. No-op if it doesn't exist. */
-    delete(key: string): Promise<void>;
-    /**
-     * Mint an ABSOLUTE, signed share URL for a key — works with **no** active
-     * session (email it, or embed it on another site). Expires (default 24h).
-     * Private stores only.
-     *
-     * The same link is available as `file.shareUrl()` on a {@link StoredFile};
-     * this convenience skips the `head()` when you already hold just the key.
-     */
-    shareUrl(key: string, options?: {
-        expiresIn?: number;
-    }): Promise<string>;
-    /**
-     * Mint an {@link UploadToken} for a **client-direct** upload — the browser
-     * POSTs the file straight to storage, so the bytes never pass through the
-     * platform. Return the token from a backend method and hand it to the
-     * frontend's `platform.upload(token, file)`. Works for private + public stores.
-     *
-     * Enforced at upload time by the presigned POST: a max size (this call's
-     * `maxSize`, else the store's, else the platform default) and — when
-     * `contentType` is set — an exact content-type match. When the store declares
-     * `contentTypes`, `contentType` must be one of them.
-     *
-     * Note: a presigned POST can pin exactly ONE content-type per token, so the
-     * *allowlist* is declared on `defineStore({ contentTypes })` and each token
-     * pins one type from it. This is by design, not a per-token limitation.
-     *
-     * @example
-     * ```ts
-     * // backend method
-     * export async function getUploadSlot(input: { contentType: string }) {
-     *   return Uploads.createUploadToken({ contentType: input.contentType, maxSize: 50 * 1024 * 1024 });
-     * }
-     * ```
-     */
-    createUploadToken(options?: {
-        key?: string;
-        contentType?: string;
-        filename?: string;
-        maxSize?: number;
-        expiresIn?: number;
-    }): Promise<UploadToken>;
-    private _toFile;
-}
-
 /**
  * The `files` namespace — typed, private-by-default file storage for MindStudio
  * apps. Think of a store as a CDN-backed bucket the app talks to, not app-defined
@@ -3710,7 +3752,11 @@ interface GenerateImageStepInput {
     generateVariants?: boolean;
     /** Number of variants to generate (max 10) */
     numVariants?: number;
-    /** Whether to add a MindStudio watermark to the generated image */
+    /**
+   * Whether to add a MindStudio watermark to the generated image.
+   *
+   * The watermark is a product mark on assets generated in the MindStudio UI. A step run directly via the SDK or API is producing the app's own asset, so it is never watermarked and this flag has no effect there.
+   */
     addWatermark?: boolean;
 }
 interface GenerateImageStepOutput {
@@ -3720,7 +3766,11 @@ interface GenerateImageStepOutput {
 interface GenerateLipsyncStepInput {
     /** When true, the asset is created but hidden from the user's gallery (tagged as intermediate) */
     intermediateAsset?: boolean;
-    /** Whether to add a MindStudio watermark to the generated video */
+    /**
+   * Whether to add a MindStudio watermark to the generated video.
+   *
+   * The watermark is a product mark on assets generated in the MindStudio UI. A step run directly via the SDK or API is producing the app's own asset, so it is never watermarked and this flag has no effect there.
+   */
     addWatermark?: boolean;
     /** Optional model configuration override. Uses the workflow's default lipsync model if not specified */
     lipsyncModelOverride?: {
@@ -3855,7 +3905,11 @@ interface GenerateVideoStepInput {
     generateVariants?: boolean;
     /** Number of variants to generate (max 10) */
     numVariants?: number;
-    /** Whether to add a MindStudio watermark to the generated video */
+    /**
+   * Whether to add a MindStudio watermark to the generated video.
+   *
+   * The watermark is a product mark on assets generated in the MindStudio UI. A step run directly via the SDK or API is producing the app's own asset, so it is never watermarked and this flag has no effect there.
+   */
     addWatermark?: boolean;
 }
 interface GenerateVideoStepOutput {
@@ -6869,7 +6923,7 @@ interface StepMethods {
      */
     convertPdfToImages(step: ConvertPdfToImagesStepInput, options?: StepExecutionOptions): Promise<StepExecutionResult<ConvertPdfToImagesStepOutput>>;
     /**
-     * Create a new empty vector data source for the current app.
+     * @deprecated Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Create a new empty vector data source for the current app.
      *
      * @remarks
      * - Creates a new data source (vector database) associated with the current app version.
@@ -6951,7 +7005,7 @@ interface StepMethods {
      */
     createGoogleSheet(step: CreateGoogleSheetStepInput, options?: StepExecutionOptions): Promise<StepExecutionResult<CreateGoogleSheetStepOutput>>;
     /**
-     * Delete a vector data source from the current app.
+     * @deprecated Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Delete a vector data source from the current app.
      *
      * @remarks
      * - Soft-deletes a data source (vector database) by marking it as deleted.
@@ -6967,7 +7021,7 @@ interface StepMethods {
      */
     deleteDataSource(step: DeleteDataSourceStepInput, options?: StepExecutionOptions): Promise<StepExecutionResult<DeleteDataSourceStepOutput>>;
     /**
-     * Delete a single document from a data source.
+     * @deprecated Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Delete a single document from a data source.
      *
      * @remarks
      * - Soft-deletes a document by marking it as deleted.
@@ -7226,7 +7280,7 @@ interface StepMethods {
      */
     extractText(step: ExtractTextStepInput, options?: StepExecutionOptions): Promise<StepExecutionResult<ExtractTextStepOutput>>;
     /**
-     * Fetch the full extracted text contents of a document in a data source.
+     * @deprecated Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Fetch the full extracted text contents of a document in a data source.
      *
      * @remarks
      * - Loads a document by ID and returns its full extracted text content.
@@ -7800,7 +7854,7 @@ interface StepMethods {
      */
     insertVideoClips(step: InsertVideoClipsStepInput, options?: StepExecutionOptions): Promise<StepExecutionResult<InsertVideoClipsStepOutput>>;
     /**
-     * List all data sources for the current app.
+     * @deprecated Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. List all data sources for the current app.
      *
      * @remarks
      * - Returns metadata for every data source associated with the current app version.
@@ -8343,7 +8397,7 @@ interface StepMethods {
      */
     queryAppDatabase(step: QueryAppDatabaseStepInput, options?: StepExecutionOptions): Promise<StepExecutionResult<QueryAppDatabaseStepOutput>>;
     /**
-     * Search a vector data source (RAG) and return relevant document chunks.
+     * @deprecated Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Search a vector data source (RAG) and return relevant document chunks.
      *
      * @remarks
      * - Queries a vectorized data source and returns the most relevant chunks.
@@ -9173,7 +9227,7 @@ interface StepMethods {
      */
     updateGoogleSheet(step: UpdateGoogleSheetStepInput, options?: StepExecutionOptions): Promise<StepExecutionResult<UpdateGoogleSheetStepOutput>>;
     /**
-     * Upload a file into an existing data source from a URL or raw text content.
+     * @deprecated Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Upload a file into an existing data source from a URL or raw text content.
      *
      * @remarks
      * - If "file" is a single URL, the file is downloaded from that URL and uploaded.

package/dist/index.js

@@ -1945,6 +1945,10 @@ var Store = class {
     this._call = _call;
     this._policy = _policy;
   }
+  /** The store's name. */
+  get name() {
+    return this._store;
+  }
   /** The store's access level. */
   get access() {
     return this._access;
@@ -2362,7 +2366,7 @@ var stepMetadata = {
   },
   "createDataSource": {
     stepType: "createDataSource",
-    description: "Create a new empty vector data source for the current app.",
+    description: "Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Create a new empty vector data source for the current app.",
     usageNotes: '- Creates a new data source (vector database) associated with the current app version.\n- The data source is created empty \u2014 use the "Upload Data Source Document" block to add documents.\n- Returns the new data source ID which can be used in subsequent blocks.',
     inputSchema: { "type": "object", "properties": { "name": { "type": "string", "description": "Name for the new data source (supports variable interpolation)" } }, "required": ["name"] },
     outputSchema: { "description": "This step does not produce output data." }
@@ -2399,14 +2403,14 @@ var stepMetadata = {
   },
   "deleteDataSource": {
     stepType: "deleteDataSource",
-    description: "Delete a vector data source from the current app.",
+    description: "Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Delete a vector data source from the current app.",
     usageNotes: "- Soft-deletes a data source (vector database) by marking it as deleted.\n- The Milvus partition is cleaned up asynchronously by a background cron job.\n- The data source must belong to the current app version.",
     inputSchema: { "type": "object", "properties": { "dataSourceId": { "type": "string", "description": "ID of the data source to delete (supports variable interpolation)" } }, "required": ["dataSourceId"] },
     outputSchema: { "description": "This step does not produce output data." }
   },
   "deleteDataSourceDocument": {
     stepType: "deleteDataSourceDocument",
-    description: "Delete a single document from a data source.",
+    description: "Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Delete a single document from a data source.",
     usageNotes: "- Soft-deletes a document by marking it as deleted.\n- Requires both the data source ID and document ID.\n- After deletion, reloads vectors into Milvus so the data source reflects the change immediately.",
     inputSchema: { "type": "object", "properties": { "dataSourceId": { "type": "string", "description": "ID of the data source containing the document (supports variable interpolation)" }, "documentId": { "type": "string", "description": "ID of the document to delete (supports variable interpolation)" } }, "required": ["dataSourceId", "documentId"] },
     outputSchema: { "description": "This step does not produce output data." }
@@ -2511,7 +2515,7 @@ var stepMetadata = {
   },
   "fetchDataSourceDocument": {
     stepType: "fetchDataSourceDocument",
-    description: "Fetch the full extracted text contents of a document in a data source.",
+    description: "Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Fetch the full extracted text contents of a document in a data source.",
     usageNotes: '- Loads a document by ID and returns its full extracted text content.\n- The document must have been successfully processed (status "done").\n- Also returns document metadata (name, summary, word count).',
     inputSchema: { "type": "object", "properties": { "dataSourceId": { "type": "string", "description": "ID of the data source containing the document (supports variable interpolation)" }, "documentId": { "type": "string", "description": "ID of the document to fetch (supports variable interpolation)" } }, "required": ["dataSourceId", "documentId"] },
     outputSchema: { "description": "This step does not produce output data." }
@@ -2590,14 +2594,14 @@ var stepMetadata = {
     stepType: "generateImage",
     description: "Generate an image from a text prompt using an AI model.",
     usageNotes: "- Prompts should be descriptive but concise (roughly 3\u20136 sentences).\n- Images are automatically hosted on a CDN.\n- In foreground mode, the image is displayed to the user. In background mode, the URL is saved to a variable.\n- When generateVariants is true with numVariants > 1, multiple images are generated in parallel.\n- In direct execution, foreground mode behaves as background, and userSelect variant behavior behaves as saveAll.",
-    inputSchema: { "type": "object", "properties": { "prompt": { "type": "string", "description": "Text prompt describing the image to generate" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" }, "imageModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": "Image generation model identifier" }, "config": { "type": "object", "properties": {}, "required": [], "description": "Additional model-specific configuration" } }, "required": ["model"], "description": "Optional model configuration override. Uses the workflow's default image model if not specified" }, "generateVariants": { "type": "boolean", "description": "Whether to generate multiple image variants in parallel" }, "numVariants": { "type": "number", "description": "Number of variants to generate (max 10)" }, "addWatermark": { "type": "boolean", "description": "Whether to add a MindStudio watermark to the generated image" } }, "required": ["prompt"] },
+    inputSchema: { "type": "object", "properties": { "prompt": { "type": "string", "description": "Text prompt describing the image to generate" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" }, "imageModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": "Image generation model identifier" }, "config": { "type": "object", "properties": {}, "required": [], "description": "Additional model-specific configuration" } }, "required": ["model"], "description": "Optional model configuration override. Uses the workflow's default image model if not specified" }, "generateVariants": { "type": "boolean", "description": "Whether to generate multiple image variants in parallel" }, "numVariants": { "type": "number", "description": "Number of variants to generate (max 10)" }, "addWatermark": { "type": "boolean", "description": "Whether to add a MindStudio watermark to the generated image.\n\nThe watermark is a product mark on assets generated in the MindStudio UI. A step run directly via the SDK or API is producing the app's own asset, so it is never watermarked and this flag has no effect there." } }, "required": ["prompt"] },
     outputSchema: { "type": "object", "properties": { "imageUrl": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] } }, "required": ["imageUrl"] }
   },
   "generateLipsync": {
     stepType: "generateLipsync",
     description: "Generate a lip sync video from provided audio and image.",
     usageNotes: "- In foreground mode, the video is displayed to the user. In background mode, the URL is saved to a variable.",
-    inputSchema: { "type": "object", "properties": { "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" }, "addWatermark": { "type": "boolean", "description": "Whether to add a MindStudio watermark to the generated video" }, "lipsyncModelOverride": { "type": "object", "properties": { "model": { "type": "string" }, "config": { "type": "object", "properties": {}, "required": [] } }, "required": ["model"], "description": "Optional model configuration override. Uses the workflow's default lipsync model if not specified" } } },
+    inputSchema: { "type": "object", "properties": { "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" }, "addWatermark": { "type": "boolean", "description": "Whether to add a MindStudio watermark to the generated video.\n\nThe watermark is a product mark on assets generated in the MindStudio UI. A step run directly via the SDK or API is producing the app's own asset, so it is never watermarked and this flag has no effect there." }, "lipsyncModelOverride": { "type": "object", "properties": { "model": { "type": "string" }, "config": { "type": "object", "properties": {}, "required": [] } }, "required": ["model"], "description": "Optional model configuration override. Uses the workflow's default lipsync model if not specified" } } },
     outputSchema: { "description": "This step does not produce output data." }
   },
   "generateMusic": {
@@ -2643,7 +2647,7 @@ var stepMetadata = {
     stepType: "generateVideo",
     description: "Generate a video from a text prompt using an AI model.",
     usageNotes: "- Prompts should be descriptive but concise (roughly 3\u20136 sentences).\n- Videos are automatically hosted on a CDN.\n- In foreground mode, the video is displayed to the user. In background mode, the URL is saved to a variable.\n- When generateVariants is true with numVariants > 1, multiple videos are generated in parallel.\n- In direct execution, foreground mode behaves as background, and userSelect variant behavior behaves as saveAll.",
-    inputSchema: { "type": "object", "properties": { "prompt": { "type": "string", "description": "Text prompt describing the video to generate" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" }, "videoModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": "Video generation model identifier" }, "config": { "type": "object", "properties": {}, "required": [], "description": "Additional model-specific configuration" } }, "required": ["model"], "description": "Optional model configuration override. Uses the workflow's default video model if not specified" }, "generateVariants": { "type": "boolean", "description": "Whether to generate multiple video variants in parallel" }, "numVariants": { "type": "number", "description": "Number of variants to generate (max 10)" }, "addWatermark": { "type": "boolean", "description": "Whether to add a MindStudio watermark to the generated video" } }, "required": ["prompt"] },
+    inputSchema: { "type": "object", "properties": { "prompt": { "type": "string", "description": "Text prompt describing the video to generate" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" }, "videoModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": "Video generation model identifier" }, "config": { "type": "object", "properties": {}, "required": [], "description": "Additional model-specific configuration" } }, "required": ["model"], "description": "Optional model configuration override. Uses the workflow's default video model if not specified" }, "generateVariants": { "type": "boolean", "description": "Whether to generate multiple video variants in parallel" }, "numVariants": { "type": "number", "description": "Number of variants to generate (max 10)" }, "addWatermark": { "type": "boolean", "description": "Whether to add a MindStudio watermark to the generated video.\n\nThe watermark is a product mark on assets generated in the MindStudio UI. A step run directly via the SDK or API is producing the app's own asset, so it is never watermarked and this flag has no effect there." } }, "required": ["prompt"] },
     outputSchema: { "type": "object", "properties": { "videoUrl": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] } }, "required": ["videoUrl"] }
   },
   "getGmailAttachments": {
@@ -2788,7 +2792,7 @@ var stepMetadata = {
   },
   "listDataSources": {
     stepType: "listDataSources",
-    description: "List all data sources for the current app.",
+    description: "Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. List all data sources for the current app.",
     usageNotes: "- Returns metadata for every data source associated with the current app version.\n- Each entry includes the data source ID, name, description, status, and document list.",
     inputSchema: { "type": "object", "properties": {}, "required": [] },
     outputSchema: { "description": "This step does not produce output data." }
@@ -3023,7 +3027,7 @@ var stepMetadata = {
   },
   "queryDataSource": {
     stepType: "queryDataSource",
-    description: "Search a vector data source (RAG) and return relevant document chunks.",
+    description: "Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Search a vector data source (RAG) and return relevant document chunks.",
     usageNotes: "- Queries a vectorized data source and returns the most relevant chunks.\n- Useful for retrieval-augmented generation (RAG) workflows.",
     inputSchema: { "type": "object", "properties": { "dataSourceId": { "type": "string", "description": "ID of the vector data source to query" }, "query": { "type": "string", "description": "The search query to run against the data source" }, "maxResults": { "type": "number", "description": "Maximum number of chunks to return (recommended 1-3)" } }, "required": ["dataSourceId", "query", "maxResults"] },
     outputSchema: { "type": "object", "properties": { "text": { "type": "string", "description": "All matching chunks joined with newlines" }, "chunks": { "type": "array", "items": { "type": "string" }, "description": "Individual matching text chunks from the data source" }, "query": { "type": "string", "description": "The resolved search query that was executed" }, "citations": { "type": "array", "items": {}, "description": "Source citations for the matched chunks" }, "latencyMs": { "type": "number", "description": "Query execution time in milliseconds" } }, "required": ["text", "chunks", "query", "citations", "latencyMs"] }
@@ -3380,7 +3384,7 @@ var stepMetadata = {
   },
   "uploadDataSourceDocument": {
     stepType: "uploadDataSourceDocument",
-    description: "Upload a file into an existing data source from a URL or raw text content.",
+    description: "Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Upload a file into an existing data source from a URL or raw text content.",
     usageNotes: '- If "file" is a single URL, the file is downloaded from that URL and uploaded.\n- If "file" is any other string, a .txt document is created from that content and uploaded.\n- The block waits (polls) for processing to complete before transitioning, up to 5 minutes.\n- Once processing finishes, vectors are loaded into Milvus so the data source is immediately queryable.\n- Supported file types (when using a URL) are the same as the data source upload UI (PDF, DOCX, TXT, etc.).',
     inputSchema: { "type": "object", "properties": { "dataSourceId": { "type": "string", "description": "ID of the target data source (supports variable interpolation)" }, "file": { "type": "string", "description": "A URL to download, or raw text content to create a .txt document from (supports variable interpolation)" }, "fileName": { "type": "string", "description": "Display name for the document (supports variable interpolation)" } }, "required": ["dataSourceId", "file", "fileName"] },
     outputSchema: { "description": "This step does not produce output data." }
@@ -4349,7 +4353,8 @@ var MindStudioAgent = class {
       ...options?.appId != null && { appId: options.appId },
       ...threadId != null && { threadId },
       ...this._currentStreamId != null && { streamId: this._currentStreamId },
-      ...this._requestSource != null && { requestSource: this._requestSource }
+      ...this._requestSource != null && { requestSource: this._requestSource },
+      ...assetStoreBody(options?.store)
     });
     const remaining = headers.get("x-ratelimit-remaining");
     const returnedThreadId = asyncData.threadId ?? "";
@@ -4433,7 +4438,8 @@ var MindStudioAgent = class {
       ...options.appId != null && { appId: options.appId },
       ...threadId != null && { threadId },
       ...this._currentStreamId != null && { streamId: this._currentStreamId },
-      ...this._requestSource != null && { requestSource: this._requestSource }
+      ...this._requestSource != null && { requestSource: this._requestSource },
+      ...assetStoreBody(options.store)
     };
     await this._httpConfig.rateLimiter.acquire();
     let res;
@@ -4620,7 +4626,8 @@ var MindStudioAgent = class {
       })),
       ...options?.appId != null && { appId: options.appId },
       ...threadId != null && { threadId },
-      ...this._requestSource != null && { requestSource: this._requestSource }
+      ...this._requestSource != null && { requestSource: this._requestSource },
+      ...assetStoreBody(options?.store)
     });
     const pollUrl = `${this._currentHttpConfig.baseUrl}/developer/v2/steps/execute-batch-async/poll/${asyncData.batchToken}`;
     let pollDelay = 300;
@@ -5651,6 +5658,9 @@ function sleep3(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 applyStepMethods(MindStudioAgent);
+function assetStoreBody(store) {
+  return store ? { assetStore: { store: store.name, access: store.access } } : {};
+}
 function resolveStepType2(name) {
   const meta = stepMetadata[name];
   return meta ? meta.stepType : name;