@mindstudio-ai/agent 0.1.147 → 0.1.149

package/dist/index.d.ts

@@ -1073,7 +1073,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 +1123,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 +1481,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 +1507,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 +1688,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 +5500,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 +5589,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 +5814,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 +6376,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 +6397,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 +6549,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 +6604,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 +7045,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 +7091,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 +7181,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 +8424,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 +8472,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;
@@ -8454,19 +8567,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 +8669,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 +10050,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.
@@ -10877,7 +10999,7 @@ interface StepMethods {
      * - `variables` overrides the composition's `data-composition-variables` defaults, which it reads with `window.__hyperframes.getVariables()`
      * - Whatever the composition loads itself (fonts, scripts, images, video) is fetched as it renders, so each is in the project or at a public URL; a private app file needs a signed URL
      * - fps 24, 30 or 60 (default 30); quality draft, standard or high (default standard); format mp4 (default), webm or mov (both keep transparency), or gif
-     * - One render per call, finishing within 15 minutes
+     * - An mp4, webm or mov renders in chunks of about 10 seconds side by side, so a long video takes little longer than a short one; a call finishes within about 30 minutes, and reports its progress as it goes. A gif renders whole, within 15 minutes
      * - A composition HyperFrames can't render fails with HyperFrames' own reason
      *
      * @example
@@ -11471,18 +11593,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