@mindstudio-ai/agent 0.0.15 → 0.0.17

package/llms.txt

@@ -1,6 +1,6 @@
 # @mindstudio-ai/agent
 
-TypeScript SDK for executing MindStudio workflow steps. Each method calls a specific AI/automation action and returns typed results.
+TypeScript SDK, CLI, and MCP server for executing MindStudio workflow steps. Each method calls a specific AI/automation action and returns typed results.
 
 This file is the complete API reference. No other documentation is needed to use the SDK.
 
@@ -12,6 +12,70 @@ npm install @mindstudio-ai/agent
 
 Requires Node.js >= 18.
 
+## CLI
+
+The package includes a CLI for executing steps from the command line or scripts:
+
+```bash
+# Execute with named flags (kebab-case)
+mindstudio generate-image --prompt "A mountain landscape"
+
+# Execute with JSON input (JSON5-tolerant)
+mindstudio generate-image '{prompt: "A mountain landscape"}'
+
+# Extract a single output field
+mindstudio generate-image --prompt "A sunset" --output-key imageUrl
+
+# List all available methods
+mindstudio list
+
+# Show method details (params, types, output)
+mindstudio info generate-image
+
+# Run via npx without installing
+npx @mindstudio-ai/agent generate-text --message "Hello"
+```
+
+Auth: run `mindstudio login`, set `MINDSTUDIO_API_KEY` env var, or pass `--api-key <key>`.
+Method names are kebab-case on the CLI (camelCase also accepted). Flags are kebab-case (`--video-url` for `videoUrl`).
+Use `--output-key <key>` to extract a single field, `--no-meta` to strip $-prefixed metadata.
+
+### Authentication
+
+```bash
+# Interactive login (opens browser, saves key to ~/.mindstudio/config.json)
+mindstudio login
+
+# Check current auth status
+mindstudio whoami
+
+# Clear stored credentials
+mindstudio logout
+```
+
+Auth resolution order: `--api-key` flag > `MINDSTUDIO_API_KEY` env > `~/.mindstudio/config.json` > `CALLBACK_TOKEN` env.
+
+## MCP server
+
+The package includes an MCP server exposing all methods as tools:
+
+```bash
+mindstudio mcp
+```
+
+MCP client config:
+```json
+{
+  "mcpServers": {
+    "mindstudio": {
+      "command": "npx",
+      "args": ["-y", "@mindstudio-ai/agent", "mcp"],
+      "env": { "MINDSTUDIO_API_KEY": "your-api-key" }
+    }
+  }
+}
+```
+
 ## Setup
 
 ```typescript
@@ -19,20 +83,39 @@ import { MindStudioAgent } from '@mindstudio-ai/agent';
 
 // With API key (or set MINDSTUDIO_API_KEY env var)
 const agent = new MindStudioAgent({ apiKey: 'your-key' });
-
-// Inside MindStudio custom functions, auth is automatic (CALLBACK_TOKEN + REMOTE_HOSTNAME)
-const agent = new MindStudioAgent();
 ```
 
+Your MindStudio API key authenticates all requests. MindStudio routes to the correct AI provider (OpenAI, Google, Anthropic, etc.) server-side — you do NOT need separate provider API keys.
+
 Constructor options:
 ```typescript
 new MindStudioAgent({
-  apiKey?: string,     // Auth token. Falls back to MINDSTUDIO_API_KEY env, then CALLBACK_TOKEN env.
-  baseUrl?: string,    // API base URL. Falls back to MINDSTUDIO_BASE_URL env, then REMOTE_HOSTNAME env, then "https://v1.mindstudio-api.com".
+  apiKey?: string,     // Auth token. Falls back to MINDSTUDIO_API_KEY env var.
+  baseUrl?: string,    // API base URL. Defaults to "https://v1.mindstudio-api.com".
   maxRetries?: number, // Retries on 429 rate limit (default: 3). Uses Retry-After header for delay.
 })
 ```
 
+## Models
+
+MindStudio provides access to models from many providers (OpenAI, Google, Anthropic, Meta, xAI, DeepSeek, etc.) through a single API key. You do NOT need provider-specific API keys.
+
+Use `listModels()` or `listModelsByType("llm_chat")` to discover available models. Pass a model ID to `modelOverride.model` in methods like `generateText` to select a specific model:
+
+```typescript
+const { models } = await agent.listModelsByType('llm_chat');
+const model = models.find(m => m.name.includes("Gemini"));
+
+const { content } = await agent.generateText({
+  message: 'Hello',
+  modelOverride: {
+    model: model.rawName,
+    temperature: 0.7,
+    maxResponseTokens: 1024,
+  },
+});
+```
+
 ## Calling convention
 
 Every method has the signature:
@@ -53,6 +136,8 @@ result.content;              // step-specific output field
 result.$appId;               // string — app ID for this execution
 result.$threadId;            // string — thread ID for this execution
 result.$rateLimitRemaining;  // number | undefined — API calls remaining in rate limit window
+result.$billingCost;         // number | undefined — cost in credits for this call
+result.$billingEvents;       // object[] | undefined — itemized billing events
 ```
 
 ## Thread persistence
@@ -87,7 +172,6 @@ try {
 ```
 
 429 rate limit errors are retried automatically (configurable via `maxRetries`).
-Internal tokens (CALLBACK_TOKEN) are capped at 500 calls — exceeding this throws `call_cap_exceeded`.
 
 ## Low-level access
 
@@ -215,7 +299,7 @@ Fetch the full extracted text contents of a document in a data source.
 #### fetchSlackChannelHistory
 Fetch recent message history from a Slack channel.
 - The user is responsible for connecting their Slack workspace and selecting the channel
-- Input: `{ connectionId: string, channelId: string, limit?: number, startDate?: string, endDate?: string, includeImages?: boolean, includeRawMessage?: boolean }`
+- Input: `{ connectionId?: string, channelId: string, limit?: number, startDate?: string, endDate?: string, includeImages?: boolean, includeRawMessage?: boolean }`
 - Output: `{ messages: { from: string, content: string, timestamp?: string, images?: string[], rawMessage?: { app_id?: string, assistant_app_thread?: { first_user_thread_reply?: string, title?: string, title_blocks?: unknown[] }, attachments?: { actions?: unknown[], app_id?: string, app_unfurl_url?: string, author_icon?: string, author_id?: string, author_link?: string, author_name?: string, author_subname?: string, blocks?: unknown[], bot_id?: string, bot_team_id?: string, callback_id?: string, channel_id?: string, channel_name?: string, channel_team?: string, color?: string, fallback?: string, fields?: unknown[], file_id?: string, filename?: string, files?: unknown[], footer?: string, footer_icon?: string, from_url?: string, hide_border?: boolean, hide_color?: boolean, id?: number, image_bytes?: number, image_height?: number, image_url?: string, image_width?: number, indent?: boolean, is_app_unfurl?: boolean, is_file_attachment?: boolean, is_msg_unfurl?: boolean, is_reply_unfurl?: boolean, is_thread_root_unfurl?: boolean, list?: unknown, list_record?: unknown, list_record_id?: string, list_records?: unknown[], list_schema?: unknown[], list_view?: unknown, list_view_id?: string, message_blocks?: unknown[], metadata?: unknown, mimetype?: string, mrkdwn_in?: string[], msg_subtype?: string, original_url?: string, pretext?: string, preview?: unknown, service_icon?: string, service_name?: string, service_url?: string, size?: number, text?: string, thumb_height?: number, thumb_url?: string, thumb_width?: number, title?: string, title_link?: string, ts?: string, url?: string, video_html?: string, video_html_height?: number, video_html_width?: number, video_url?: string }[], blocks?: { accessory?: unknown, alt_text?: string, api_decoration_available?: boolean, app_collaborators?: string[], app_id?: string, author_name?: string, block_id?: string, bot_user_id?: string, button_label?: string, call?: unknown, call_id?: string, description?: unknown, developer_trace_id?: string, dispatch_action?: boolean, element?: unknown, elements?: unknown[], expand?: boolean, external_id?: string, fallback?: string, fields?: unknown[], file?: unknown, file_id?: string, function_trigger_id?: string, hint?: unknown, image_bytes?: number, image_height?: number, image_url?: string, image_width?: number, is_animated?: boolean, is_workflow_app?: boolean, label?: unknown, optional?: boolean, owning_team_id?: string, provider_icon_url?: string, provider_name?: string, sales_home_workflow_app_type?: number, share_url?: string, slack_file?: unknown, source?: string, text?: unknown, thumbnail_url?: string, title?: unknown, title_url?: string, trigger_subtype?: string, trigger_type?: string, type?: unknown, url?: string, video_url?: string, workflow_id?: string }[], bot_id?: string, bot_profile?: { app_id?: string, deleted?: boolean, icons?: unknown, id?: string, name?: string, team_id?: string, updated?: number }, client_msg_id?: string, display_as_bot?: boolean, edited?: { ts?: string, user?: string }, files?: { access?: string, alt_txt?: string, app_id?: string, app_name?: string, attachments?: unknown[], blocks?: unknown[], bot_id?: string, can_toggle_canvas_lock?: boolean, canvas_printing_enabled?: boolean, canvas_template_mode?: string, cc?: unknown[], channel_actions_count?: number, channel_actions_ts?: string, channels?: string[], comments_count?: number, converted_pdf?: string, created?: number, deanimate?: string, deanimate_gif?: string, display_as_bot?: boolean, dm_mpdm_users_with_file_access?: unknown[], duration_ms?: number, edit_link?: string, edit_timestamp?: number, editable?: boolean, editor?: string, editors?: string[], external_id?: string, external_type?: string, external_url?: string, favorites?: unknown[], file_access?: string, filetype?: string, from?: unknown[], groups?: string[], has_more?: boolean, has_more_shares?: boolean, has_rich_preview?: boolean, headers?: unknown, hls?: string, hls_embed?: string, id?: string, image_exif_rotation?: number, ims?: string[], initial_comment?: unknown, is_channel_space?: boolean, is_external?: boolean, is_public?: boolean, is_restricted_sharing_enabled?: boolean, is_starred?: boolean, last_editor?: string, last_read?: number, lines?: number, lines_more?: number, linked_channel_id?: string, list_csv_download_url?: string, list_limits?: unknown, list_metadata?: unknown, media_display_type?: string, media_progress?: unknown, mimetype?: string, mode?: string, mp4?: string, mp4_low?: string, name?: string, non_owner_editable?: boolean, num_stars?: number, org_or_workspace_access?: string, original_attachment_count?: number, original_h?: string, original_w?: string, permalink?: string, permalink_public?: string, pinned_to?: string[], pjpeg?: string, plain_text?: string, pretty_type?: string, preview?: string, preview_highlight?: string, preview_is_truncated?: boolean, preview_plain_text?: string, private_channels_with_file_access_count?: number, private_file_with_access_count?: number, public_url_shared?: boolean, quip_thread_id?: string, reactions?: unknown[], saved?: unknown, sent_to_self?: boolean, shares?: unknown, show_badge?: boolean, simplified_html?: string, size?: number, source_team?: string, subject?: string, subtype?: string, team_pref_version_history_enabled?: boolean, teams_shared_with?: unknown[], template_conversion_ts?: number, template_description?: string, template_icon?: string, template_name?: string, template_title?: string, thumb_1024?: string, thumb_1024_gif?: string, thumb_1024_h?: string, thumb_1024_w?: string, thumb_160?: string, thumb_160_gif?: string, thumb_160_h?: string, thumb_160_w?: string, thumb_360?: string, thumb_360_gif?: string, thumb_360_h?: string, thumb_360_w?: string, thumb_480?: string, thumb_480_gif?: string, thumb_480_h?: string, thumb_480_w?: string, thumb_64?: string, thumb_64_gif?: string, thumb_64_h?: string, thumb_64_w?: string, thumb_720?: string, thumb_720_gif?: string, thumb_720_h?: string, thumb_720_w?: string, thumb_80?: string, thumb_800?: string, thumb_800_gif?: string, thumb_800_h?: string, thumb_800_w?: string, thumb_80_gif?: string, thumb_80_h?: string, thumb_80_w?: string, thumb_960?: string, thumb_960_gif?: string, thumb_960_h?: string, thumb_960_w?: string, thumb_gif?: string, thumb_pdf?: string, thumb_pdf_h?: string, thumb_pdf_w?: string, thumb_tiny?: string, thumb_video?: string, thumb_video_h?: number, thumb_video_w?: number, timestamp?: number, title?: string, title_blocks?: unknown[], to?: unknown[], transcription?: unknown, update_notification?: number, updated?: number, url_private?: string, url_private_download?: string, url_static_preview?: string, user?: string, user_team?: string, username?: string, vtt?: string }[], icons?: { emoji?: string, image_36?: string, image_48?: string, image_64?: string, image_72?: string }, inviter?: string, is_locked?: boolean, latest_reply?: string, metadata?: { event_payload?: unknown, event_type?: string }, parent_user_id?: string, purpose?: string, reactions?: { count?: number, name?: string, url?: string, users?: string[] }[], reply_count?: number, reply_users?: string[], reply_users_count?: number, root?: { bot_id?: string, icons?: unknown, latest_reply?: string, parent_user_id?: string, reply_count?: number, reply_users?: string[], reply_users_count?: number, subscribed?: boolean, subtype?: string, text?: string, thread_ts?: string, ts?: string, type?: string, username?: string }, subscribed?: boolean, subtype?: string, team?: string, text?: string, thread_ts?: string, topic?: string, ts?: string, type?: string, upload?: boolean, user?: string, username?: string, x_files?: string[] } }[] }`
 
 #### generateAsset
@@ -225,7 +309,7 @@ Generate an HTML asset and export it as a webpage, PDF, or image
 - If PDF or composited image generation are part of the workflow, assistant adds the block and leaves the "source" empty. In a separate step, assistant generates a detailed request for the developer who will write the HTML.
 - Can also auto-generate HTML from a prompt (like a generate text block to generate HTML). In these cases, create a prompt with variables in the dynamicPrompt variable describing, in detail, the document to generate
 - Can either display output directly to user (foreground mode) or save the URL of the asset to a variable (background mode)
-- Input: `{ source: string, sourceType: "html" | "markdown" | "spa" | "raw" | "dynamic" | "customInterface", outputFormat: "pdf" | "png" | "html" | "mp4" | "openGraph", pageSize: "full" | "letter" | "A4" | "custom", testData: object, options?: { pageWidthPx?: number, pageHeightPx?: number, pageOrientation?: "portrait" | "landscape", rehostMedia?: boolean, videoDurationSeconds?: number }, spaSource?: { paths: string[], root: string, zipUrl: string }, rawSource?: string, dynamicPrompt?: string, dynamicSourceModelOverride?: { model: string, temperature: number, maxResponseTokens: number, ignorePreamble?: boolean, userMessagePreprocessor?: { dataSource?: string, messageTemplate?: string, maxResults?: number, enabled?: boolean, shouldInherit?: boolean }, preamble?: string, multiModelEnabled?: boolean, editResponseEnabled?: boolean, config?: object }, transitionControl?: "default" | "native", shareControl?: "default" | "hidden", shareImageUrl?: string, skipAssetCreation?: boolean }`
+- Input: `{ source: string, sourceType: "html" | "markdown" | "spa" | "raw" | "dynamic" | "customInterface", outputFormat: "pdf" | "png" | "html" | "mp4" | "openGraph", pageSize: "full" | "letter" | "A4" | "custom", testData: object, options?: { pageWidthPx?: number, pageHeightPx?: number, pageOrientation?: "portrait" | "landscape", rehostMedia?: boolean, videoDurationSeconds?: number }, spaSource?: { source?: string, lastCompiledSource?: string, files?: object, paths: string[], root: string, zipUrl: string }, rawSource?: string, dynamicPrompt?: string, dynamicSourceModelOverride?: { model: string, temperature: number, maxResponseTokens: number, ignorePreamble?: boolean, userMessagePreprocessor?: { dataSource?: string, messageTemplate?: string, maxResults?: number, enabled?: boolean, shouldInherit?: boolean }, preamble?: string, multiModelEnabled?: boolean, editResponseEnabled?: boolean, config?: object }, transitionControl?: "default" | "native", shareControl?: "default" | "hidden", shareImageUrl?: string, skipAssetCreation?: boolean }`
 - Output: `{ url: string }`
 
 #### generateChart
@@ -370,7 +454,7 @@ Send a message to a Slack channel via a connected bot.
 - The user is responsible for connecting their Slack workspace and selecting the channel
 - Supports both simple text messages and slack blocks messages
 - Text messages can use limited markdown (slack-only fomatting—e.g., headers are just rendered as bold)
-- Input: `{ channelId: string, messageType: "string" | "blocks", message: string, connectionId: string }`
+- Input: `{ channelId: string, messageType: "string" | "blocks", message: string, connectionId?: string }`
 - Output: `unknown`
 
 #### postToZapier
@@ -393,7 +477,7 @@ Execute a SQL query against an external database connected to the workspace.
 - Requires a database connection configured in the workspace.
 - Supports PostgreSQL (including Supabase), MySQL, and MSSQL.
 - Results can be returned as JSON or CSV.
-- Input: `{ connectionId: string, query: string, outputFormat: "json" | "csv" }`
+- Input: `{ connectionId?: string, query: string, outputFormat: "json" | "csv" }`
 - Output: `{ data: unknown }`
 
 #### redactPII
@@ -503,13 +587,16 @@ Send an email to one or more configured recipient addresses.
 - When generateHtml is enabled, the body text is converted to a styled HTML email using an AI model.
 - connectionId can be a comma-separated list to send to multiple recipients.
 - The special connectionId "trigger_email" uses the email address that triggered the workflow.
-- Input: `{ subject: string, body: string, connectionId: string, generateHtml?: boolean, generateHtmlInstructions?: string, generateHtmlModelOverride?: { model: string, temperature: number, maxResponseTokens: number, ignorePreamble?: boolean, userMessagePreprocessor?: { dataSource?: string, messageTemplate?: string, maxResults?: number, enabled?: boolean, shouldInherit?: boolean }, preamble?: string, multiModelEnabled?: boolean, editResponseEnabled?: boolean, config?: object }, attachments?: string[] }`
+- Input: `{ subject: string, body: string, connectionId?: string, generateHtml?: boolean, generateHtmlInstructions?: string, generateHtmlModelOverride?: { model: string, temperature: number, maxResponseTokens: number, ignorePreamble?: boolean, userMessagePreprocessor?: { dataSource?: string, messageTemplate?: string, maxResults?: number, enabled?: boolean, shouldInherit?: boolean }, preamble?: string, multiModelEnabled?: boolean, editResponseEnabled?: boolean, config?: object }, attachments?: string[] }`
 - Output: `{ recipients: string[] }`
 
 #### sendSMS
-Send an SMS text message to a phone number configured via OAuth connection.
+Send an SMS or MMS message to a phone number configured via OAuth connection.
 - User is responsible for configuring the connection to the number (MindStudio requires double opt-in to prevent spam)
-- Input: `{ body: string, connectionId: string }`
+- If mediaUrls are provided, the message is sent as MMS instead of SMS
+- MMS supports up to 10 media URLs (images, video, audio, PDF) with a 5MB limit per file
+- MMS is only supported on US and Canadian carriers; international numbers will receive SMS only (media silently dropped)
+- Input: `{ body: string, connectionId?: string, mediaUrls?: string[] }`
 - Output: `unknown`
 
 #### setRunTitle
@@ -522,8 +609,24 @@ Explicitly set a variable to a given value.
 - Useful for bootstrapping global variables or setting constants.
 - The variable name and value both support variable interpolation.
 - The type field is a UI hint only (controls input widget in the editor).
-- Input: `{ value: string | string[], type: "imageUrl" | "videoUrl" | "fileUrl" | "plaintext" | "textArray" | "imageUrlArray" | "videoUrlArray" }`
-- Output: `{ variableName: string, value: string | string[] }`
+- Input: `{ value: string | string[] }`
+- Output: `object`
+
+#### telegramEditMessage
+Edit a previously sent Telegram message. Use with the message ID returned by Send Telegram Message.
+- Only text messages sent by the bot can be edited.
+- The messageId is returned by the Send Telegram Message step.
+- Common pattern: send a "Processing..." message, do work, then edit it with the result.
+- Input: `{ botToken: string, chatId: string, messageId: string, text: string }`
+- Output: `unknown`
+
+#### telegramReplyToMessage
+Send a reply to a specific Telegram message. The reply will be visually threaded in the chat.
+- Use the rawMessage.message_id from the incoming trigger variables to reply to the user's message.
+- Especially useful in group chats where replies provide context.
+- Returns the sent message ID, which can be used with Edit Telegram Message.
+- Input: `{ botToken: string, chatId: string, replyToMessageId: string, text: string }`
+- Output: `{ messageId: number }`
 
 #### telegramSendAudio
 Send an audio file to a Telegram chat as music or a voice note via a bot.
@@ -545,8 +648,9 @@ Send an image to a Telegram chat via a bot.
 Send a text message to a Telegram chat via a bot.
 - Messages are sent using MarkdownV2 formatting. Special characters are auto-escaped.
 - botToken format is "botId:token" — both parts are required.
+- Returns the sent message ID, which can be used with Edit Telegram Message to update the message later.
 - Input: `{ botToken: string, chatId: string, text: string }`
-- Output: `unknown`
+- Output: `{ messageId: number }`
 
 #### telegramSendVideo
 Send a video to a Telegram chat via a bot.
@@ -630,7 +734,7 @@ Add an image watermark to a video
 Add a note to an existing contact in ActiveCampaign.
 - Requires an ActiveCampaign OAuth connection (connectionId).
 - The contact must already exist — use the contact ID from a previous create or search step.
-- Input: `{ contactId: string, note: string, connectionId: string }`
+- Input: `{ contactId: string, note: string, connectionId?: string }`
 - Output: `unknown`
 
 #### activeCampaignCreateContact
@@ -638,7 +742,7 @@ Create or sync a contact in ActiveCampaign.
 - Requires an ActiveCampaign OAuth connection (connectionId).
 - If a contact with the email already exists, it may be updated depending on ActiveCampaign settings.
 - Custom fields are passed as a key-value map where keys are field IDs.
-- Input: `{ email: string, firstName: string, lastName: string, phone: string, accountId: string, customFields: object, connectionId: string }`
+- Input: `{ email: string, firstName: string, lastName: string, phone: string, accountId: string, customFields: object, connectionId?: string }`
 - Output: `{ contactId: string }`
 
 ### Airtable
@@ -648,21 +752,21 @@ Create a new record or update an existing record in an Airtable table.
 - If recordId is provided, updates that record. Otherwise, creates a new one.
 - When updating with updateMode "onlySpecified", unspecified fields are left as-is. With "all", unspecified fields are cleared.
 - Array fields (e.g. multipleAttachments) accept arrays of values.
-- Input: `{ connectionId: string, baseId: string, tableId: string, recordId?: string, updateMode?: "onlySpecified" | "all", fields: unknown, recordData: object }`
+- Input: `{ connectionId?: string, baseId: string, tableId: string, recordId?: string, updateMode?: "onlySpecified" | "all", fields: unknown, recordData: object }`
 - Output: `{ recordId: string }`
 
 #### airtableDeleteRecord
 Delete a record from an Airtable table by its record ID.
 - Requires an active Airtable OAuth connection (connectionId).
 - Silently succeeds if the record does not exist.
-- Input: `{ connectionId: string, baseId: string, tableId: string, recordId: string }`
+- Input: `{ connectionId?: string, baseId: string, tableId: string, recordId: string }`
 - Output: `{ deleted: boolean }`
 
 #### airtableGetRecord
 Fetch a single record from an Airtable table by its record ID.
 - Requires an active Airtable OAuth connection (connectionId).
 - If the record is not found, returns a string message instead of a record object.
-- Input: `{ connectionId: string, baseId: string, tableId: string, recordId: string }`
+- Input: `{ connectionId?: string, baseId: string, tableId: string, recordId: string }`
 - Output: `{ record: { id: string, createdTime: string, fields: object } | null }`
 
 #### airtableGetTableRecords
@@ -670,7 +774,7 @@ Fetch multiple records from an Airtable table with optional pagination.
 - Requires an active Airtable OAuth connection (connectionId).
 - Default limit is 100 records. Maximum is 1000.
 - When outputFormat is 'csv', the variable receives CSV text. The direct execution output always returns parsed records.
-- Input: `{ connectionId: string, baseId: string, tableId: string, outputFormat?: "json" | "csv", limit?: number }`
+- Input: `{ connectionId?: string, baseId: string, tableId: string, outputFormat?: "json" | "csv", limit?: number }`
 - Output: `{ records: { id: string, createdTime: string, fields: object }[] }`
 
 ### Apollo
@@ -699,7 +803,7 @@ Create a new page or update an existing page in a Coda document.
 - If pageData.pageId is provided, updates that page. Otherwise, creates a new one.
 - Page content is provided as markdown and converted to Coda's canvas format.
 - When updating, insertionMode controls how content is applied (default: 'append').
-- Input: `{ connectionId: string, pageData: { docId: string, pageId?: string, name: string, subtitle: string, iconName: string, imageUrl: string, parentPageId?: string, pageContent: string | unknown, contentUpdate?: unknown, insertionMode?: string } }`
+- Input: `{ connectionId?: string, pageData: { docId: string, pageId?: string, name: string, subtitle: string, iconName: string, imageUrl: string, parentPageId?: string, pageContent: string | unknown, contentUpdate?: unknown, insertionMode?: string } }`
 - Output: `{ pageId: string }`
 
 #### codaCreateUpdateRow
@@ -707,7 +811,7 @@ Create a new row or update an existing row in a Coda table.
 - Requires a Coda OAuth connection (connectionId).
 - If rowId is provided, updates that row. Otherwise, creates a new one.
 - Row data keys are column IDs. Empty values are excluded.
-- Input: `{ connectionId: string, docId: string, tableId: string, rowId?: string, rowData: object }`
+- Input: `{ connectionId?: string, docId: string, tableId: string, rowId?: string, rowData: object }`
 - Output: `{ rowId: string }`
 
 #### codaFindRow
@@ -715,7 +819,7 @@ Search for a row in a Coda table by matching column values.
 - Requires a Coda OAuth connection (connectionId).
 - Returns the first row matching all specified column values, or null if no match.
 - Search criteria in rowData are ANDed together.
-- Input: `{ connectionId: string, docId: string, tableId: string, rowData: object }`
+- Input: `{ connectionId?: string, docId: string, tableId: string, rowData: object }`
 - Output: `{ row: { id: string, values: object } | null }`
 
 #### codaGetPage
@@ -723,7 +827,7 @@ Export and read the contents of a page from a Coda document.
 - Requires a Coda OAuth connection (connectionId).
 - Page export is asynchronous on Coda's side — there may be a brief delay while it processes.
 - If a page was just created in a prior step, there is an automatic 20-second retry if the first export attempt fails.
-- Input: `{ connectionId: string, docId: string, pageId: string, outputFormat?: "html" | "markdown" }`
+- Input: `{ connectionId?: string, docId: string, pageId: string, outputFormat?: "html" | "markdown" }`
 - Output: `{ content: string }`
 
 #### codaGetTableRows
@@ -731,7 +835,7 @@ Fetch rows from a Coda table with optional pagination.
 - Requires a Coda OAuth connection (connectionId).
 - Default limit is 10000 rows. Rows are fetched in pages of 500.
 - When outputFormat is 'csv', the variable receives CSV text. The direct execution output always returns parsed rows.
-- Input: `{ connectionId: string, docId: string, tableId: string, limit?: number | string, outputFormat?: "json" | "csv" }`
+- Input: `{ connectionId?: string, docId: string, tableId: string, limit?: number | string, outputFormat?: "json" | "csv" }`
 - Output: `{ rows: { id: string, values: object }[] }`
 
 ### Facebook
@@ -746,44 +850,98 @@ Get all the posts for a Facebook page
 - Input: `{ pageUrl: string }`
 - Output: `{ data: unknown }`
 
+### Gmail
+
+#### deleteGmailEmail
+Move an email to trash in the connected Gmail account (recoverable delete).
+- Requires a Google OAuth connection with Gmail modify scope.
+- Uses trash (recoverable) rather than permanent delete.
+- Input: `{ messageId: string, connectionId?: string }`
+- Output: `unknown`
+
+#### getGmailDraft
+Retrieve a specific draft from Gmail by draft ID.
+- Requires a Google OAuth connection with Gmail readonly scope.
+- Returns the draft content including subject, recipients, sender, and body.
+- Input: `{ draftId: string, connectionId?: string }`
+- Output: `{ draftId: string, messageId: string, subject: string, to: string, from: string, body: string }`
+
+#### getGmailEmail
+Retrieve a specific email from Gmail by message ID.
+- Requires a Google OAuth connection with Gmail readonly scope.
+- Returns the email subject, sender, recipient, date, body (plain text preferred, falls back to HTML), and labels.
+- Input: `{ messageId: string, connectionId?: string }`
+- Output: `{ messageId: string, subject: string, from: string, to: string, date: string, body: string, labels: string }`
+
+#### listGmailDrafts
+List drafts in the connected Gmail account.
+- Requires a Google OAuth connection with Gmail readonly scope.
+- Returns up to 50 drafts (default 10).
+- The variable receives text or JSON depending on exportType.
+- Input: `{ connectionId?: string, limit?: string, exportType: "json" | "text" }`
+- Output: `{ drafts: { draftId: string, messageId: string, subject: string, to: string, snippet: string }[] }`
+
+#### replyToGmailEmail
+Reply to an existing email in Gmail. The reply is threaded under the original message.
+- Requires a Google OAuth connection with Gmail compose and readonly scopes.
+- The reply is sent to the original sender and threaded under the original message.
+- messageType controls the body format: "plain", "html", or "markdown".
+- Input: `{ messageId: string, message: string, messageType: "plain" | "html" | "markdown", connectionId?: string }`
+- Output: `{ messageId: string }`
+
 ### Google
 
 #### createGoogleDoc
 Create a new Google Document and optionally populate it with content.
 - textType determines how the text field is interpreted: "plain" for plain text, "html" for HTML markup, "markdown" for Markdown.
-- Input: `{ title: string, text: string, connectionId: string, textType: "plain" | "html" | "markdown" }`
+- Input: `{ title: string, text: string, connectionId?: string, textType: "plain" | "html" | "markdown" }`
 - Output: `{ documentUrl: string }`
 
 #### createGoogleSheet
 Create a new Google Spreadsheet and populate it with CSV data.
-- Input: `{ title: string, text: string, connectionId: string }`
+- Input: `{ title: string, text: string, connectionId?: string }`
 - Output: `{ spreadsheetUrl: string }`
 
+#### deleteGoogleSheetRows
+Delete a range of rows from a Google Spreadsheet.
+- Requires a Google OAuth connection with Drive scope.
+- startRow and endRow are 1-based row numbers (inclusive).
+- If sheetName is omitted, operates on the first sheet.
+- Input: `{ documentId: string, sheetName?: string, startRow: string, endRow: string, connectionId?: string }`
+- Output: `unknown`
+
 #### fetchGoogleDoc
 Fetch the contents of an existing Google Document.
 - exportType controls the output format: "html" for HTML markup, "markdown" for Markdown, "json" for structured JSON, "plain" for plain text.
-- Input: `{ documentId: string, connectionId: string, exportType: "html" | "markdown" | "json" | "plain" }`
+- Input: `{ documentId: string, connectionId?: string, exportType: "html" | "markdown" | "json" | "plain" }`
 - Output: `{ content: string }`
 
 #### fetchGoogleSheet
 Fetch contents of a Google Spreadsheet range.
 - range uses A1 notation (e.g. "Sheet1!A1:C10"). Omit to fetch the entire first sheet.
 - exportType controls the output format: "csv" for comma-separated values, "json" for structured JSON.
-- Input: `{ spreadsheetId: string, range: string, connectionId: string, exportType: "csv" | "json" }`
+- Input: `{ spreadsheetId: string, range: string, connectionId?: string, exportType: "csv" | "json" }`
 - Output: `{ content: string }`
 
+#### getGoogleSheetInfo
+Get metadata about a Google Spreadsheet including sheet names, row counts, and column counts.
+- Requires a Google OAuth connection with Drive scope.
+- Returns the spreadsheet title and a list of all sheets with their dimensions.
+- Input: `{ documentId: string, connectionId?: string }`
+- Output: `{ title: string, sheets: { sheetId: number, title: string, rowCount: number, columnCount: number }[] }`
+
 #### updateGoogleDoc
 Update the contents of an existing Google Document.
 - operationType controls how content is applied: "addToTop" prepends, "addToBottom" appends, "overwrite" replaces all content.
 - textType determines how the text field is interpreted: "plain" for plain text, "html" for HTML markup, "markdown" for Markdown.
-- Input: `{ documentId: string, connectionId: string, text: string, textType: "plain" | "html" | "markdown", operationType: "addToTop" | "addToBottom" | "overwrite" }`
+- Input: `{ documentId: string, connectionId?: string, text: string, textType: "plain" | "html" | "markdown", operationType: "addToTop" | "addToBottom" | "overwrite" }`
 - Output: `{ documentUrl: string }`
 
 #### updateGoogleSheet
 Update a Google Spreadsheet with new data.
 - operationType controls how data is written: "addToBottom" appends rows, "overwrite" replaces all data, "range" writes to a specific cell range.
 - Data should be provided as CSV in the text field.
-- Input: `{ text: string, connectionId: string, spreadsheetId: string, range: string, operationType: "addToBottom" | "overwrite" | "range" }`
+- Input: `{ text: string, connectionId?: string, spreadsheetId: string, range: string, operationType: "addToBottom" | "overwrite" | "range" }`
 - Output: `{ spreadsheetUrl: string }`
 
 ### Google Calendar
@@ -794,21 +952,21 @@ Create a new event on a Google Calendar.
 - Date/time values must be ISO 8601 format (e.g. "2025-07-02T10:00:00-07:00").
 - Attendees are specified as one email address per line in a single string.
 - Set addMeetLink to true to automatically attach a Google Meet video call.
-- Input: `{ connectionId: string, summary: string, description?: string, location?: string, startDateTime: string, endDateTime: string, attendees?: string, addMeetLink?: boolean, calendarId?: string }`
+- Input: `{ connectionId?: string, summary: string, description?: string, location?: string, startDateTime: string, endDateTime: string, attendees?: string, addMeetLink?: boolean, calendarId?: string }`
 - Output: `{ eventId: string, htmlLink: string }`
 
 #### deleteGoogleCalendarEvent
 Retrieve a specific event from a Google Calendar by event ID.
 - Requires a Google OAuth connection with Calendar events scope.
 - The variable receives JSON or XML-like text depending on exportType. The direct execution output always returns the structured event.
-- Input: `{ connectionId: string, eventId: string, calendarId?: string }`
+- Input: `{ connectionId?: string, eventId: string, calendarId?: string }`
 - Output: `unknown`
 
 #### getGoogleCalendarEvent
 Retrieve a specific event from a Google Calendar by event ID.
 - Requires a Google OAuth connection with Calendar events scope.
 - The variable receives JSON or XML-like text depending on exportType. The direct execution output always returns the structured event.
-- Input: `{ connectionId: string, eventId: string, exportType: "json" | "text", calendarId?: string }`
+- Input: `{ connectionId?: string, eventId: string, exportType: "json" | "text", calendarId?: string }`
 - Output: `{ event: { id?: string | null, status?: string | null, htmlLink?: string | null, created?: string | null, updated?: string | null, summary?: string | null, description?: string | null, location?: string | null, organizer?: { displayName?: string | null, email?: string | null } | null, start?: { dateTime?: string | null, timeZone?: string | null } | null, end?: { dateTime?: string | null, timeZone?: string | null } | null, attendees?: ({ displayName?: string | null, email?: string | null, responseStatus?: string | null })[] | null } }`
 
 #### listGoogleCalendarEvents
@@ -816,7 +974,15 @@ List upcoming events from a Google Calendar, ordered by start time.
 - Requires a Google OAuth connection with Calendar events scope.
 - Only returns future events (timeMin = now).
 - The variable receives JSON or XML-like text depending on exportType. The direct execution output always returns structured events.
-- Input: `{ connectionId: string, limit: number, exportType: "json" | "text", calendarId?: string }`
+- Input: `{ connectionId?: string, limit: number, exportType: "json" | "text", calendarId?: string }`
+- Output: `{ events: ({ id?: string | null, status?: string | null, htmlLink?: string | null, created?: string | null, updated?: string | null, summary?: string | null, description?: string | null, location?: string | null, organizer?: { displayName?: string | null, email?: string | null } | null, start?: { dateTime?: string | null, timeZone?: string | null } | null, end?: { dateTime?: string | null, timeZone?: string | null } | null, attendees?: ({ displayName?: string | null, email?: string | null, responseStatus?: string | null })[] | null })[] }`
+
+#### searchGoogleCalendarEvents
+Search for events in a Google Calendar by keyword, date range, or both.
+- Requires a Google OAuth connection with Calendar events scope.
+- Supports keyword search via "query" and date filtering via "timeMin"/"timeMax" (ISO 8601 format).
+- Unlike "List Events" which only shows future events, this allows searching past events too.
+- Input: `{ query?: string, timeMin?: string, timeMax?: string, calendarId?: string, limit?: number, exportType: "json" | "text", connectionId?: string }`
 - Output: `{ events: ({ id?: string | null, status?: string | null, htmlLink?: string | null, created?: string | null, updated?: string | null, summary?: string | null, description?: string | null, location?: string | null, organizer?: { displayName?: string | null, email?: string | null } | null, start?: { dateTime?: string | null, timeZone?: string | null } | null, end?: { dateTime?: string | null, timeZone?: string | null } | null, attendees?: ({ displayName?: string | null, email?: string | null, responseStatus?: string | null })[] | null })[] }`
 
 #### updateGoogleCalendarEvent
@@ -824,9 +990,35 @@ Update an existing event on a Google Calendar. Only specified fields are changed
 - Requires a Google OAuth connection with Calendar events scope.
 - Fetches the existing event first, then applies only the provided updates. Omitted fields are left unchanged.
 - Attendees are specified as one email address per line, and replace the entire attendee list.
-- Input: `{ connectionId: string, eventId: string, summary?: string, description?: string, location?: string, startDateTime?: string, endDateTime?: string, attendees?: string, calendarId?: string }`
+- Input: `{ connectionId?: string, eventId: string, summary?: string, description?: string, location?: string, startDateTime?: string, endDateTime?: string, attendees?: string, calendarId?: string }`
 - Output: `{ eventId: string, htmlLink: string }`
 
+### Google Drive
+
+#### getGoogleDriveFile
+Download a file from Google Drive and rehost it on the CDN. Returns a public CDN URL.
+- Requires a Google OAuth connection with Drive scope.
+- Google-native files (Docs, Sheets, Slides) cannot be downloaded — use dedicated steps instead.
+- Maximum file size: 200MB.
+- The file is downloaded and re-uploaded to the CDN; the returned URL is publicly accessible.
+- Input: `{ fileId: string, connectionId?: string }`
+- Output: `{ url: string, name: string, mimeType: string, size: number }`
+
+#### listGoogleDriveFiles
+List files in a Google Drive folder.
+- Requires a Google OAuth connection with Drive scope.
+- If folderId is omitted, lists files in the root folder.
+- Returns file metadata including name, type, size, and links.
+- Input: `{ folderId?: string, limit?: number, connectionId?: string, exportType: "json" | "text" }`
+- Output: `{ files: { id: string, name: string, mimeType: string, size: string, webViewLink: string, createdTime: string, modifiedTime: string }[] }`
+
+#### searchGoogleDrive
+Search for files in Google Drive by keyword.
+- Requires a Google OAuth connection with Drive scope.
+- Searches file content and names using Google Drive's fullText search.
+- Input: `{ query: string, limit?: number, connectionId?: string, exportType: "json" | "text" }`
+- Output: `{ files: { id: string, name: string, mimeType: string, size: string, webViewLink: string, createdTime: string, modifiedTime: string }[] }`
+
 ### HubSpot
 
 #### hubspotCreateCompany
@@ -834,7 +1026,7 @@ Create a new company or update an existing one in HubSpot. Matches by domain.
 - Requires a HubSpot OAuth connection (connectionId).
 - If a company with the given domain already exists, it is updated. Otherwise, a new one is created.
 - Property values are type-checked against enabledProperties before being sent to HubSpot.
-- Input: `{ connectionId: string, company: { domain: string, name: string }, enabledProperties: ({ label: string, value: string, type: "string" | "number" | "bool" })[] }`
+- Input: `{ connectionId?: string, company: { domain: string, name: string }, enabledProperties: ({ label: string, value: string, type: "string" | "number" | "bool" })[] }`
 - Output: `{ companyId: string }`
 
 #### hubspotCreateContact
@@ -843,7 +1035,7 @@ Create a new contact or update an existing one in HubSpot. Matches by email addr
 - If a contact with the given email already exists, it is updated. Otherwise, a new one is created.
 - If companyDomain is provided, the contact is associated with that company (creating the company if needed).
 - Property values are type-checked against enabledProperties before being sent to HubSpot.
-- Input: `{ connectionId: string, contact: { email: string, firstname: string, lastname: string }, enabledProperties: ({ label: string, value: string, type: "string" | "number" | "bool" })[], companyDomain: string }`
+- Input: `{ connectionId?: string, contact: { email: string, firstname: string, lastname: string }, enabledProperties: ({ label: string, value: string, type: "string" | "number" | "bool" })[], companyDomain: string }`
 - Output: `{ contactId: string }`
 
 #### hubspotGetCompany
@@ -852,7 +1044,7 @@ Look up a HubSpot company by domain name or company ID.
 - Returns null if the company is not found.
 - When searching by domain, performs a search query then fetches the full company record.
 - Use additionalProperties to request specific HubSpot properties beyond the defaults.
-- Input: `{ connectionId: string, searchBy: "domain" | "id", companyDomain: string, companyId: string, additionalProperties: string[] }`
+- Input: `{ connectionId?: string, searchBy: "domain" | "id", companyDomain: string, companyId: string, additionalProperties: string[] }`
 - Output: `{ company: { id: string, properties: object, createdAt: string, updatedAt: string, archived: boolean } | null }`
 
 #### hubspotGetContact
@@ -860,7 +1052,7 @@ Look up a HubSpot contact by email address or contact ID.
 - Requires a HubSpot OAuth connection (connectionId).
 - Returns null if the contact is not found.
 - Use additionalProperties to request specific HubSpot properties beyond the defaults.
-- Input: `{ connectionId: string, searchBy: "email" | "id", contactEmail: string, contactId: string, additionalProperties: string[] }`
+- Input: `{ connectionId?: string, searchBy: "email" | "id", contactEmail: string, contactId: string, additionalProperties: string[] }`
 - Output: `{ contact: { id: string, properties: object, createdAt: string, updatedAt: string, archived: boolean } | null }`
 
 ### Hunter.io
@@ -936,7 +1128,7 @@ Create a post on LinkedIn from the connected account.
 - Requires a LinkedIn OAuth connection (connectionId).
 - Supports text posts, image posts, and video posts.
 - Visibility controls who can see the post.
-- Input: `{ message: string, visibility: "PUBLIC" | "CONNECTIONS", videoUrl?: string, descriptionText?: string, titleText?: string, imageUrl?: string, connectionId: string }`
+- Input: `{ message: string, visibility: "PUBLIC" | "CONNECTIONS", videoUrl?: string, descriptionText?: string, titleText?: string, imageUrl?: string, connectionId?: string }`
 - Output: `unknown`
 
 ### Meta Threads
@@ -953,7 +1145,7 @@ Create a new page in Notion as a child of an existing page.
 - Requires a Notion OAuth connection (connectionId).
 - Content is provided as markdown and converted to Notion blocks (headings, paragraphs, lists, code, quotes).
 - The page is created as a child of the specified parent page (pageId).
-- Input: `{ pageId: string, content: string, title: string, connectionId: string }`
+- Input: `{ pageId: string, content: string, title: string, connectionId?: string }`
 - Output: `{ pageId: string, pageUrl: string }`
 
 #### notionUpdatePage
@@ -961,7 +1153,7 @@ Update the content of an existing Notion page.
 - Requires a Notion OAuth connection (connectionId).
 - Content is provided as markdown and converted to Notion blocks.
 - "append" mode adds content to the end of the page. "overwrite" mode deletes all existing blocks first.
-- Input: `{ pageId: string, content: string, mode: "append" | "overwrite", connectionId: string }`
+- Input: `{ pageId: string, content: string, mode: "append" | "overwrite", connectionId?: string }`
 - Output: `{ pageId: string, pageUrl: string }`
 
 ### X
@@ -970,7 +1162,7 @@ Update the content of an existing Notion page.
 Create a post on X (Twitter) from the connected account.
 - Requires an X OAuth connection (connectionId).
 - Posts are plain text. Maximum 280 characters.
-- Input: `{ text: string, connectionId: string }`
+- Input: `{ text: string, connectionId?: string }`
 - Output: `unknown`
 
 #### searchXPosts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/agent",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "TypeScript SDK for MindStudio direct step execution",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,6 +12,9 @@
       "default": "./dist/index.js"
     }
   },
+  "bin": {
+    "mindstudio": "./dist/cli.js"
+  },
   "files": [
     "dist",
     "llms.txt"