@mindstudio-ai/agent 0.1.148 → 0.1.150

package/dist/index.d.ts

@@ -537,6 +537,15 @@ interface MindStudioModel {
     maxResponseSize?: number;
     /** Accepted input types for this model (text, imageUrl, videoUrl, etc.). */
     inputs?: Record<string, unknown>[];
+    /**
+     * When the platform retires this model (`YYYY-MM-DD`, from 00:00 UTC). Until
+     * then it runs as itself; from then saved calls run on `replacedBy`.
+     */
+    retiresOn?: string;
+    /** The model that runs in this one's place once it has retired. */
+    replacedBy?: string;
+    /** True once the model has retired: a call to it runs on `replacedBy`. */
+    retired?: boolean;
 }
 /** A lightweight AI model summary. */
 interface MindStudioModelSummary {
@@ -547,6 +556,15 @@ interface MindStudioModelSummary {
     type?: ModelType;
     /** Comma-separated tags for the model. */
     tags?: string;
+    /**
+     * When the platform retires this model (`YYYY-MM-DD`, from 00:00 UTC). Until
+     * then it runs as itself; from then saved calls run on `replacedBy`.
+     */
+    retiresOn?: string;
+    /** The model that runs in this one's place once it has retired. */
+    replacedBy?: string;
+    /** True once the model has retired: a call to it runs on `replacedBy`. */
+    retired?: boolean;
 }
 /**
  * Supported model type categories for filtering.
@@ -1073,7 +1091,10 @@ type Accessor<T, R = unknown> = (row: T) => R;
  * queries against the correct database.
  */
 interface TableConfig {
-    /** The managed database ID (from app context metadata). */
+    /**
+     * The managed database ID (from app context metadata). Empty on a lazy
+     * table until its context is loaded (`ready`).
+     */
     databaseId: string;
     /** The SQL table name (as declared in defineTable). */
     tableName: string;
@@ -1120,6 +1141,15 @@ interface TableConfig {
      * @returns Array of results in the same order as the input queries
      */
     executeBatch: (queries: SqlQuery[]) => Promise<SqlResult[]>;
+    /**
+     * Loads the app's context, for a table defined before it was available
+     * (the lazy db's `defineTable`). Such a table's database, columns and
+     * managed columns read the context whenever they're read, so whatever
+     * builds SQL from them awaits this first: built without them, a write
+     * stores a user ID with no `@@user@@` prefix and skips the managed-column
+     * check. Absent on a table made with its context in hand.
+     */
+    ready?: () => Promise<void>;
 }
 /** A single SQL query with optional positional bind params. */
 interface SqlQuery {
@@ -1469,6 +1499,14 @@ interface CompiledQuery<T, TResult = T[]> {
  * then bundles it with other operations into a single round trip. After
  * execution, `_processResults()` deserializes the raw SQL results.
  *
+ * ## SQL is built when it runs
+ *
+ * A Mutation holds a builder rather than its statements, called when it's
+ * compiled or executed. The statements depend on the table's columns (a user
+ * column's `@@user@@` prefix) and managed columns, which a lazy table only
+ * knows once the app's context is loaded (`TableConfig.ready`), and that can
+ * be after the write method was called.
+ *
  * ## Non-batchable mutations
  *
  * Some mutations (e.g. `removeAll` with a JS-fallback predicate) require
@@ -1487,12 +1525,12 @@ declare class Mutation<TResult> implements PromiseLike<TResult> {
     /** @internal */
     private readonly _config;
     /** @internal */
-    private readonly _queries;
+    private readonly _build;
     /** @internal */
     private readonly _processResult;
     /** @internal Non-batchable executor for complex mutations (e.g. removeAll JS fallback). */
     private readonly _executor;
-    constructor(config: TableConfig, queries: SqlQuery[], processResult: (results: SqlResult[]) => TResult);
+    constructor(config: TableConfig, build: () => SqlQuery[], processResult: (results: SqlResult[]) => TResult);
     /**
      * Create a non-batchable mutation that wraps an async executor.
      * Used for operations that require multi-step execution (e.g. removeAll
@@ -1668,10 +1706,11 @@ interface CompiledRawQuery<TResult> {
     processResult: (result: SqlResult) => TResult;
 }
 declare class RawQuery<TResult = Record<string, unknown>[]> implements PromiseLike<TResult> {
+    /** Read when it's compiled: the lazy db's database is known only once its context is. */
     private readonly _databaseId;
     private readonly _executeBatch;
     private readonly _query;
-    constructor(databaseId: string, executeBatch: (queries: SqlQuery[]) => Promise<SqlResult[]>, query: SqlQuery);
+    constructor(databaseId: () => string, executeBatch: (queries: SqlQuery[]) => Promise<SqlResult[]>, query: SqlQuery);
     then<T1 = TResult, T2 = never>(onfulfilled?: ((value: TResult) => T1 | PromiseLike<T1>) | null, onrejected?: ((reason: unknown) => T2 | PromiseLike<T2>) | null): Promise<T1 | T2>;
     catch<T2 = never>(onrejected?: ((reason: unknown) => T2 | PromiseLike<T2>) | null): Promise<TResult | T2>;
     /** @internal Compile for db.batch(). */
@@ -5479,7 +5518,12 @@ interface CreateDataSourceStepInput {
     /** Name for the new data source (supports variable interpolation) */
     name: string;
 }
-type CreateDataSourceStepOutput = unknown;
+interface CreateDataSourceStepOutput {
+    /** ID of the newly created data source */
+    dataSourceId: string;
+    /** Resolved name of the data source */
+    name: string;
+}
 interface CreateGmailDraftStepInput {
     /** Recipient email address(es), comma-separated for multiple */
     to: string;
@@ -5563,14 +5607,22 @@ interface DeleteDataSourceStepInput {
     /** ID of the data source to delete (supports variable interpolation) */
     dataSourceId: string;
 }
-type DeleteDataSourceStepOutput = unknown;
+interface DeleteDataSourceStepOutput {
+    /** ID of the deleted data source */
+    dataSourceId: string;
+}
 interface DeleteDataSourceDocumentStepInput {
     /** ID of the data source containing the document (supports variable interpolation) */
     dataSourceId: string;
     /** ID of the document to delete (supports variable interpolation) */
     documentId: string;
 }
-type DeleteDataSourceDocumentStepOutput = unknown;
+interface DeleteDataSourceDocumentStepOutput {
+    /** ID of the data source */
+    dataSourceId: string;
+    /** ID of the deleted document */
+    documentId: string;
+}
 interface DeleteGmailEmailStepInput {
     /** Gmail message ID to delete (move to trash) */
     messageId: string;
@@ -5780,7 +5832,18 @@ interface FetchDataSourceDocumentStepInput {
     /** ID of the document to fetch (supports variable interpolation) */
     documentId: string;
 }
-type FetchDataSourceDocumentStepOutput = unknown;
+interface FetchDataSourceDocumentStepOutput {
+    /** ID of the document */
+    documentId: string;
+    /** Document name */
+    name: string;
+    /** Full extracted text content */
+    content: string;
+    /** Document summary */
+    summary: string;
+    /** Word count */
+    numWords: number;
+}
 interface FetchGoogleDocStepInput {
     /** Google Document ID (from the document URL) */
     documentId: string;
@@ -6331,13 +6394,16 @@ interface GenerateLipsyncStepInput {
    * 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 */
+    /** The lip sync model to run and its config, whose keys come from the model: the media (`image` or `video`, and `audio`) and the model's options */
     lipsyncModelOverride?: {
         model: string;
         config?: Record<string, unknown>;
     };
 }
-type GenerateLipsyncStepOutput = unknown;
+interface GenerateLipsyncStepOutput {
+    /** URL of the generated lip sync video */
+    videoUrl: string;
+}
 interface GenerateMusicStepInput {
     /** The instructions (prompt) for the music generation */
     text: string;
@@ -6349,7 +6415,10 @@ interface GenerateMusicStepInput {
         config?: Record<string, unknown>;
     };
 }
-type GenerateMusicStepOutput = unknown;
+interface GenerateMusicStepOutput {
+    /** URL of the generated audio file */
+    audioUrl: string;
+}
 interface GeneratePdfStepInput {
     /** The HTML or Markdown source template for the asset */
     source: string;
@@ -6498,7 +6567,15 @@ interface GetGmailAttachmentsStepInput {
     /** Google OAuth connection ID */
     connectionId?: string;
 }
-type GetGmailAttachmentsStepOutput = unknown;
+interface GetGmailAttachmentsStepOutput {
+    /** List of attachments with CDN URLs */
+    attachments: {
+        filename: string;
+        mimeType: string;
+        size: number;
+        url: string;
+    }[];
+}
 interface GetGmailDraftStepInput {
     /** Gmail draft ID to retrieve */
     draftId: string;
@@ -6545,7 +6622,10 @@ interface GetGmailUnreadCountStepInput {
     /** Google OAuth connection ID */
     connectionId?: string;
 }
-type GetGmailUnreadCountStepOutput = unknown;
+interface GetGmailUnreadCountStepOutput {
+    /** Number of unread messages in the inbox */
+    unreadCount: number;
+}
 interface GetGoogleCalendarEventStepInput {
     /** Google OAuth connection ID */
     connectionId?: string;
@@ -6983,7 +7063,25 @@ interface InsertVideoClipsStepOutput {
     videoUrl: string;
 }
 type ListDataSourcesStepInput = Record<string, unknown>;
-type ListDataSourcesStepOutput = unknown;
+interface ListDataSourcesStepOutput {
+    /** All data sources for the current app version */
+    dataSources: ({
+        id: string;
+        name: string;
+        description: string;
+        /** One of: `loaded`, `hibernating`. */
+        status: "loaded" | "hibernating";
+        dateCreated: string;
+        documents: ({
+            id: string;
+            name: string;
+            /** One of: `processing`, `done`, `error`. */
+            status: "processing" | "done" | "error";
+            numWords?: number;
+            dateUploaded: string;
+        })[];
+    })[];
+}
 interface ListGmailDraftsStepInput {
     /** Google OAuth connection ID */
     connectionId?: string;
@@ -7011,7 +7109,14 @@ interface ListGmailLabelsStepInput {
     /** Google OAuth connection ID */
     connectionId?: string;
 }
-type ListGmailLabelsStepOutput = unknown;
+interface ListGmailLabelsStepOutput {
+    /** List of Gmail labels */
+    labels: {
+        id: string;
+        name: string;
+        type: string;
+    }[];
+}
 interface ListGoogleCalendarEventsStepInput {
     /** Google OAuth connection ID */
     connectionId?: string;
@@ -7094,7 +7199,27 @@ interface ListRecentGmailEmailsStepInput {
     /** Maximum number of emails to return (1-100, default: 5) */
     limit: string;
 }
-type ListRecentGmailEmailsStepOutput = unknown;
+interface ListRecentGmailEmailsStepOutput {
+    /** List of recent email messages */
+    emails: {
+        /** Gmail message ID */
+        id: string;
+        /** Email subject line */
+        subject: string;
+        /** Sender email address */
+        from: string;
+        /** Recipient email address */
+        to: string;
+        /** Email date */
+        date: string;
+        /** Plain text body content */
+        plainBody: string;
+        /** HTML body content (if available) */
+        htmlBody: string;
+        /** Comma-separated label IDs applied to the email */
+        labels: string;
+    }[];
+}
 interface LogicStepInput {
     /** Evaluation mode: 'ai' for LLM-based, 'comparison' for operator-based. Default: 'ai' */
     mode?: "ai" | "comparison";
@@ -8317,7 +8442,10 @@ interface SendGmailDraftStepInput {
     /** Google OAuth connection ID */
     connectionId?: string;
 }
-type SendGmailDraftStepOutput = unknown;
+interface SendGmailDraftStepOutput {
+    /** Gmail message ID of the sent email */
+    messageId: string;
+}
 interface SendGmailMessageStepInput {
     /** Recipient email address(es), comma-separated for multiple */
     to: string;
@@ -8362,7 +8490,10 @@ interface SetGmailReadStatusStepInput {
     /** Google OAuth connection ID */
     connectionId?: string;
 }
-type SetGmailReadStatusStepOutput = unknown;
+interface SetGmailReadStatusStepOutput {
+    /** IDs of the updated messages */
+    messageIds: string[];
+}
 interface SetRunTitleStepInput {
     /** The title to assign to the agent run (supports variable interpolation) */
     title: string;
@@ -8438,6 +8569,8 @@ interface TranscribeAudioStepOutput {
     language?: string;
     /** Length of the transcribed audio, when the model reports it. */
     durationSeconds?: number;
+    /** The transcript as an SRT or WebVTT file, when `subtitles` was asked for in the model's config and the model returned segments to time it by. */
+    subtitles?: string;
 }
 interface TrimMediaStepInput {
     /** URL of the source audio or video file to trim */
@@ -8454,19 +8587,21 @@ interface TrimMediaStepOutput {
     mediaUrl: string;
 }
 interface TypesafeEvaluateStepInput {
-    /** The content to evaluate. A string, or a JSON object or array. Text only. */
+    /** The content to evaluate. A string, or a JSON object or array. */
     state: string | Record<string, unknown> | unknown[];
     /** Questions to ask about the state, keyed by an id you choose. */
     questions: Record<string, unknown>;
-    /** Model id or alias. Defaults to jev-latest. jev-preview tracks the newest release. Pin a version such as jev-1.13.0 when a threshold was tuned against that version. */
+    /** Model id or alias. Defaults to jev-latest. jev-preview tracks the newest TypeSafe release. Pin a version such as jev-1.13.0 when a threshold was tuned against that version. clef and clef-flash run Cloudflare Clef, with the same questions and answers. */
     model?: string;
+    /** Images for Clef to read, up to 4. Each entry is a URL or a data URL (PNG, JPEG, or WebP). A Jev call that includes images is rejected. */
+    images?: string[];
 }
 interface TypesafeEvaluateStepOutput {
     /** Versioned model id that answered, such as jev-1.13.0. */
     model: string;
     /** One answer per question, under the same ids. */
     answers: Record<string, unknown>;
-    /** Token counts for the call. Input tokens are what the step bills. */
+    /** Token counts for the call. Input tokens are what the model bills. */
     usage: {
         input_tokens: number;
         output_tokens: number;
@@ -8554,7 +8689,14 @@ interface UploadDataSourceDocumentStepInput {
     /** Display name for the document (supports variable interpolation) */
     fileName: string;
 }
-type UploadDataSourceDocumentStepOutput = unknown;
+interface UploadDataSourceDocumentStepOutput {
+    /** ID of the uploaded document */
+    documentId: string;
+    /** ID of the data source it was uploaded to */
+    dataSourceId: string;
+    /** Resolved file name */
+    fileName: string;
+}
 interface UpscaleImageStepInput {
     /** URL of the image to upscale */
     imageUrl: string;
@@ -9928,7 +10070,7 @@ interface StepMethods {
      */
     generateImage(step: GenerateImageStepInput, options?: StepExecutionOptions): Promise<StepExecutionResult<GenerateImageStepOutput>>;
     /**
-     * Generate a lip sync video from provided audio and image.
+     * Generate a lip sync video from audio and an image or video.
      *
      * @remarks
      * - In foreground mode, the video is displayed to the user. In background mode, the URL is saved to a variable.
@@ -11428,6 +11570,10 @@ interface StepMethods {
      *
      * @remarks
      * - The text field contains the exact words to be spoken (not instructions).
+     * - Voice, delivery and format are set through `speechModelOverride.config`, whose keys are the model's own (look a model up with its id). Delivery direction, where a model takes one, is never spoken: `styleInstruction` on gemini-3.8-flash-tts and gemini-3.8-flash-lite-tts, `instructions` on gpt-realtime-2.1-mini-tts, `voice_instruction` on seed-speech-tts-2.0, `emotion` on cartesia-sonic-3.6 and the MiniMax models.
+     * - Tags in the text act at that point, in each vendor's own syntax: `[laughs]` or `[whispers]` on elevenlabs-tts with Eleven v4 or v3; `<laugh>`, `<sigh>` or `<whispers>` on the Gemini 3.8 models; `[laugh]`, `[pause]` or `<whisper>…</whisper>` on grok-voice-tts; `[laughter]` or `<emotion value="excited"/>` on cartesia-sonic-3.6; `[be happy and upbeat]` on inworld-tts-2.
+     * - A dialogue between voices: set `$mode: 'dialogue'` and name each speaker (`speaker1_name`, `speaker1_voice`, `speaker2_name`, …), then write the text as a script, one `Name: line` per turn. Supported by elevenlabs-tts (Eleven v4 or v3, up to 4 speakers) and the Gemini 3.8 models (exactly 2).
+     * - A text longer than a model takes in one request is spoken in pieces and joined, and then comes back as MP3 whatever format was asked for.
      * - In foreground mode, the audio is displayed to the user. In background mode, the URL is saved to a variable.
      *
      * @example
@@ -11442,12 +11588,20 @@ interface StepMethods {
      * Convert an audio file to text using a transcription model.
      *
      * @remarks
-     * - The prompt field provides optional context to improve transcription accuracy (e.g. language, speaker names, domain).
-     * - Detail beyond the plain transcript is requested through `transcriptionModelOverride.config`, and support varies by model:
-     * - `includeSpeakers: 'yes'` — label each passage with a speaker. Supported by elevenlabs-scribe-v1, elevenlabs-scribe-v2, deepgram-nova-3 and grok-stt. Also switches `text` to a timestamped, speaker-labelled block format.
-     * - `includeWordTimings: 'yes'` — add per-word timings and confidence inside each segment. Supported by elevenlabs-scribe-v1, elevenlabs-scribe-v2, deepgram-nova-3 and whisper-1. Off by default because an hour of speech is roughly ten thousand words.
-     * - `detectLanguage: 'yes'` — detect the spoken language instead of assuming English (deepgram-nova-3 only; Scribe and the whisper models always report it).
-     * - The `segments` output carries timings, confidence and speakers as structured data, so there is no need to slice the audio up to recover them. It is populated for elevenlabs-scribe-v1/v2, deepgram-nova-3, whisper-1 and the DeepInfra-served whisper/voxtral/qwen models, and absent for models that return nothing but text (gpt-transcribe, gpt-4o-transcribe, grok-stt).
+     * - The default model is elevenlabs-scribe-v2: speakers, word timings, key terms and redaction, at any length.
+     * - The prompt field gives context (speaker names, domain) to OpenAI's and DeepInfra's models. Other models ignore it; give them `keyterms` instead.
+     * - Options go in `transcriptionModelOverride.config`, and support varies by model:
+     * - `language` — the spoken language as a code such as `en` or `es`; left out, the model detects it. Every model takes it. deepgram-nova-3 assumes `en` unless told, and also takes `multi` for speech that switches language (billed at its multilingual rate).
+     * - `detectLanguage: 'yes'` — detect the language instead of assuming English (deepgram-nova-3 only).
+     * - `includeSpeakers: 'yes'` — label each passage with a speaker. Supported by elevenlabs-scribe-v2, elevenlabs-scribe-v2-medical, deepgram-nova-3, grok-stt, voxtral-mini-transcribe-2 and gemini-3.5-transcribe; gpt-4o-transcribe-diarize always does. Scribe and Voxtral also switch `text` to a timestamped, speaker-labelled block format; Deepgram, Gemini and gpt-4o-transcribe-diarize to `Speaker N:` lines.
+     * - `numSpeakers` — the most people talking, to help tell them apart (Scribe).
+     * - `keyterms` — a list of names, products and terms the audio contains, so they're spelled right. Supported by gpt-transcribe, Scribe, deepgram-nova-3, grok-stt, voxtral-mini-transcribe-2 and gemini-3.5-transcribe. Billed as an add-on on Scribe and Deepgram.
+     * - `redactPii: 'yes'` — replace names, phone numbers, addresses and other personal information with a label of what was there (Scribe, deepgram-nova-3). Billed as an add-on.
+     * - `includeWordTimings: 'yes'` — add per-word timings and confidence inside each segment. Supported by Scribe, deepgram-nova-3, whisper-1, grok-stt, voxtral-mini-transcribe-2 and gemini-3.5-transcribe. Off by default because an hour of speech is roughly ten thousand words.
+     * - `subtitles: 'srt' | 'vtt'` — also return the transcript as a subtitle file, in the `subtitles` output, timed by the segments. Any model that returns segments.
+     * - gemini-3.5-transcribe can't take `keyterms` together with speakers, word timings or subtitles, and voxtral-mini-transcribe-2 can't take `language` together with word timings or subtitles; either asked for both is refused.
+     * - The `segments` output carries timings, confidence and speakers as structured data, so there is no need to slice the audio up to recover them. It is populated by Scribe, deepgram-nova-3, grok-stt, whisper-1, gpt-4o-transcribe-diarize, voxtral-mini-transcribe-2 (unless given a language), gemini-3.5-transcribe (with word timings or subtitles) and the DeepInfra-served whisper and qwen models, and absent for models that return nothing but text (gpt-transcribe, gpt-4o-transcribe, gpt-4o-mini-transcribe, the DeepInfra-served voxtral models).
+     * - A recording of any length can be transcribed. One longer than a model takes at once (OpenAI's and DeepInfra's models, Gemini) is transcribed in pieces and joined, its timings running from the start of the recording. Speakers can't be followed from one piece to the next, so with speakers on, such a recording is refused; Scribe and Deepgram label speakers at any length.
      * - `confidence` is always 0..1 with higher meaning more confident, whichever model produced it.
      *
      * @example
@@ -11471,18 +11625,19 @@ interface StepMethods {
      */
     trimMedia(step: TrimMediaStepInput, options?: StepExecutionOptions): Promise<StepExecutionResult<TrimMediaStepOutput>>;
     /**
-     * Ask TypeSafe structured questions about text or JSON and get calibrated answers. The model returns a probability, a selected option, or a score. It does not write a reply. Each question is a noul (yes or no, as a probability from 0 to 1), a choice (one option from a set you define, with a probability for each), or a score (a rating against ordered levels). Put every question in the same call. The question id is yours: answers come back under the same ids. The model defaults to Jev (jev-latest).
+     * Ask structured questions about text, JSON, or images and get calibrated answers. The model returns a probability, a selected option, or a score. It does not write a reply. Each question is a noul (yes or no, as a probability from 0 to 1), a choice (one option from a set you define, with a probability for each), or a score (a rating against ordered levels). Put every question in the same call. The question id is yours: answers come back under the same ids. The model defaults to Jev (jev-latest). Pass clef or clef-flash to run Cloudflare Clef with the same questions and answers. Clef and Clef Flash can also read up to 4 images.
      *
      * @remarks
-     * - state is the content to judge: a string, or a JSON object or array (a record, a chat log, application state). Text only. Turn images, audio, and video into text first.
+     * - state is the content to judge: a string, or a JSON object or array (a record, a chat log, application state).
+     * - images is for Clef and Clef Flash. Pass up to 4 PNG, JPEG, or WebP images as URLs. Each file is at most 4 MiB, and 8 MiB together. A call on Jev that includes images is rejected.
      * - questions is a map. The key is an id you choose. It is not shown to the model. The answer comes back under the same id.
      * - A noul asks a yes/no question and returns noul, a probability from 0 (no) to 1 (yes). Optional criteria.true and criteria.false say what a yes and a no mean.
      * - A choice picks one option. criteria is a map of option id to a short description (or null). At most 255 options. The answer includes the winning choice, a probability for every option, and confidence.
      * - A score rates the state on an ordered rubric. criteria is 2 to 10 level descriptions, low to high. The answer's score can land between levels, and includes a probability per level plus confidence.
      * - instructions may be a string, or an object that keeps the question in one field and reference data in the others. Refer to those fields by name in backticks.
      * - Send every question you need in one call. The model reads the state once and answers them together.
-     * - model defaults to jev-latest, the current stable release. jev-preview tracks the newest release. Pin a version such as jev-1.13.0 when a threshold was tuned against that version. The response model field is the version that answered.
-     * - Billed per input token. Output tokens are free.
+     * - model defaults to jev-latest, the current stable TypeSafe release. jev-preview tracks the newest TypeSafe release. Pin a version such as jev-1.13.0 when a threshold was tuned against that version. clef and clef-flash run Cloudflare Clef on the same questions and answers. clef is the larger model. clef-flash is the faster one. @cf/cloudflare/clef and @cf/cloudflare/clef-flash name the same two. Clef accepts at most 64 questions, and a question id may use only letters, digits, underscore, dot, and hyphen, up to 100 characters. The response model field is the version that answered.
+     * - Billed per input token. Output tokens are free. Clef and Clef-flash have their own rates.
      *
      * @example
      * ```typescript