@mindstudio-ai/agent 0.0.20 → 0.1.1

package/llms.txt

@@ -1,9 +1,24 @@
 # @mindstudio-ai/agent
 
-TypeScript SDK, CLI, and MCP server for executing MindStudio workflow steps. Each method calls a specific AI/automation action and returns typed results.
+TypeScript SDK, CLI, and MCP server for MindStudio. One API key gives you access to 200+ AI models (OpenAI, Anthropic, Google, Meta, xAI, DeepSeek, etc.) and 1,000+ actions including 850+ connector actions across third-party services from the open-source MindStudio Connector Registry (https://github.com/mindstudio-ai/mscr). No separate provider API keys required.
 
 This file is the complete API reference. No other documentation is needed to use the SDK.
 
+## Recommended workflow
+
+There are 150+ methods available. Do NOT try to read or load them all at once. Follow this discovery flow:
+
+1. **Discover** — Call `listSteps` (MCP tool) or `mindstudio list --summary` (CLI) to get a compact `{ method: description }` map of everything available (~3k tokens).
+2. **Drill in** — Once you identify the right method, look up its full signature in the Methods reference below, or call `mindstudio info <method>` (CLI) for parameter details.
+3. **Call it** — Invoke the method with the required parameters. All step methods share the same calling convention (see below).
+
+For specific use cases:
+
+- **Third-party integrations** (Slack, Google, HubSpot, etc.): Call `listConnectors()` to browse services → `getConnectorAction(serviceId, actionId)` for input fields → execute via `runFromConnectorRegistry`. Requires an OAuth connection set up in MindStudio first — call `listConnections()` to check available connections.
+- **Pre-built agents**: Call `listAgents()` to see what's available → `runAgent({ appId })` to execute one. Agents are full workflows built in MindStudio — they can combine multiple steps, have custom logic, and maintain their own state.
+- **Model selection**: Call `listModelsSummary()` or `listModelsSummaryByType("llm_chat")` to browse models, then pass the model ID as `modelOverride.model` to methods like `generateText`. Use the summary endpoints (not `listModels`) to keep token usage low.
+- **Cost estimation**: Call `estimateStepCost(stepType, stepInput)` before expensive calls to preview pricing.
+
 ## Install
 
 ```bash
@@ -26,7 +41,10 @@ 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
+# List all methods (compact JSON — best for LLM discovery)
+mindstudio list --summary
+
+# List all methods (human-readable table)
 mindstudio list
 
 # Show method details (params, types, output)
@@ -57,7 +75,7 @@ Auth resolution order: `--api-key` flag > `MINDSTUDIO_API_KEY` env > `~/.mindstu
 
 ## MCP server
 
-The package includes an MCP server exposing all methods as tools:
+The package includes an MCP server exposing all methods as tools. Start by calling the `listSteps` tool to discover available methods.
 
 ```bash
 mindstudio mcp
@@ -98,9 +116,9 @@ new MindStudioAgent({
 
 ## 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.
+Direct access to 200+ AI models from every major provider — all through a single API key, billed at cost with no markups.
 
-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:
+Use `listModels()` or `listModelsByType()` for full model details, or `listModelsSummary()` / `listModelsSummaryByType()` for a lightweight list (id, name, type, tags) suitable for LLM context windows. Pass a model ID to `modelOverride.model` in methods like `generateText` to select a specific model:
 
 ```typescript
 const { models } = await agent.listModelsByType('llm_chat');
@@ -109,7 +127,7 @@ const model = models.find(m => m.name.includes("Gemini"));
 const { content } = await agent.generateText({
   message: 'Hello',
   modelOverride: {
-    model: model.rawName,
+    model: model.id,
     temperature: 0.7,
     maxResponseTokens: 1024,
   },
@@ -227,6 +245,14 @@ Create a new empty vector data source for the current app.
 - Input: `{ name: string }`
 - Output: `unknown`
 
+#### createGmailDraft
+Create a draft email in the connected Gmail account.
+- Requires a Google OAuth connection with Gmail compose scope.
+- The draft appears in the user's Gmail Drafts folder but is not sent.
+- messageType controls the body format: "plain" for plain text, "html" for raw HTML, "markdown" for auto-converted markdown.
+- Input: `{ to: string, subject: string, message: string, connectionId?: string, messageType: "plain" | "html" | "markdown" }`
+- Output: `{ draftId: string }`
+
 #### deleteDataSource
 Delete a vector data source from the current app.
 - Soft-deletes a data source (vector database) by marking it as deleted.
@@ -408,6 +434,23 @@ Generate a video from a text prompt using an AI model.
 - Input: `{ prompt: string, skipAssetCreation?: boolean, videoModelOverride?: { model: string, config?: object }, generateVariants?: boolean, numVariants?: number, addWatermark?: boolean }`
 - Output: `{ videoUrl: string | string[] }`
 
+#### getGmailAttachments
+Download attachments from a Gmail email and re-host them on CDN.
+- Requires a Google OAuth connection with Gmail readonly scope.
+- Attachments are uploaded to CDN and returned as URLs.
+- Attachments larger than 25MB are skipped.
+- Use the message ID from Search Gmail Emails, List Recent Gmail Emails, or Get Gmail Email steps.
+- Input: `{ messageId: string, connectionId?: string }`
+- Output: `unknown`
+
+#### getGmailUnreadCount
+Get the number of unread emails in the connected Gmail inbox.
+- Requires a Google OAuth connection with Gmail readonly scope.
+- Returns the unread message count for the inbox label.
+- This is a lightweight call that does not fetch any email content.
+- Input: `{ connectionId?: string }`
+- Output: `unknown`
+
 #### getMediaMetadata
 Get info about a media file
 - Input: `{ mediaUrl: string }`
@@ -445,6 +488,22 @@ List all data sources for the current app.
 - Input: `object`
 - Output: `unknown`
 
+#### listGmailLabels
+List all labels in the connected Gmail account. Use these label IDs or names with the Update Gmail Labels step.
+- Requires a Google OAuth connection with Gmail readonly scope.
+- Returns both system labels (INBOX, SENT, TRASH, etc.) and user-created labels.
+- Label type is "system" for built-in labels or "user" for custom labels.
+- Input: `{ connectionId?: string }`
+- Output: `unknown`
+
+#### listRecentGmailEmails
+List recent emails from the connected Gmail inbox.
+- Requires a Google OAuth connection with Gmail readonly scope.
+- Returns up to 100 emails (default 5), ordered by most recent first.
+- Functionally equivalent to Search Gmail Emails with an "in:inbox" query.
+- Input: `{ connectionId?: string, exportType: "json" | "text", limit: string }`
+- Output: `unknown`
+
 #### logic
 Route execution to different branches based on AI evaluation, comparison operators, or workflow jumps.
 - Supports two modes: "ai" (default) uses an AI model to pick the most accurate statement; "comparison" uses operator-based checks.
@@ -541,6 +600,16 @@ Resize a video file
 - Input: `{ videoUrl: string, mode: "fit" | "exact", maxWidth?: number, maxHeight?: number, width?: number, height?: number, strategy?: "pad" | "crop", skipAssetCreation?: boolean }`
 - Output: `{ videoUrl: string }`
 
+#### runFromConnectorRegistry
+Run a raw API connector to a third-party service
+- Use the /developer/v2/helpers/connectors endpoint to list available services and actions.
+- Use /developer/v2/helpers/connectors/{serviceId}/{actionId} to get the full input configuration for an action.
+- Use /developer/v2/helpers/connections to list your available OAuth connections.
+- The actionId format is "serviceId/actionId" (e.g., "slack/send-message").
+- Pass a __connectionId to authenticate the request with a specific OAuth connection, otherwise the default will be used (if configured).
+- Input: `{ actionId: string, displayName: string, icon: string, configurationValues: object, __connectionId?: string }`
+- Output: `{ data: object }`
+
 #### runPackagedWorkflow
 Run a packaged workflow ("custom block")
 - From the user's perspective, packaged workflows are just ordinary blocks. Behind the scenes, they operate like packages/libraries in a programming language, letting the user execute custom functionality.
@@ -585,6 +654,16 @@ Scrape public profile data from an X (Twitter) account by URL.
 - Input: `{ url: string }`
 - Output: `{ profile: { text: string, html: string, json?: object, screenshotUrl?: string, metadata?: { title: string, description: string, url: string, image: string } } }`
 
+#### searchGmailEmails
+Search for emails in the connected Gmail account using a Gmail search query. To list recent inbox emails, pass an empty query string.
+- Requires a Google OAuth connection with Gmail readonly scope.
+- Uses Gmail search syntax (e.g. "from:user@example.com", "subject:invoice", "is:unread").
+- To list recent inbox emails, use an empty query string or "in:inbox".
+- Returns up to 100 emails (default 5). The variable receives text or JSON depending on exportType.
+- The direct execution output always returns structured email objects.
+- Input: `{ query: string, connectionId?: string, exportType: "json" | "text", limit: string }`
+- Output: `{ emails: { id: string, subject: string, from: string, to: string, date: string, plainBody: string, htmlBody: string, labels: string }[] }`
+
 #### searchGoogle
 Search the web using Google and return structured results.
 - Defaults to us/english, but can optionally specify country and/or language.
@@ -632,6 +711,21 @@ Send an email to one or more configured recipient addresses.
 - 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[] }`
 
+#### sendGmailDraft
+Send an existing draft from the connected Gmail account.
+- Requires a Google OAuth connection with Gmail compose scope.
+- The draft is sent and removed from the Drafts folder.
+- Use the draft ID returned by the Create Gmail Draft or List Gmail Drafts steps.
+- Input: `{ draftId: string, connectionId?: string }`
+- Output: `unknown`
+
+#### sendGmailMessage
+Send an email from the connected Gmail account.
+- Requires a Google OAuth connection with Gmail compose scope.
+- messageType controls the body format: "plain" for plain text, "html" for raw HTML, "markdown" for auto-converted markdown.
+- Input: `{ to: string, subject: string, message: string, connectionId?: string, messageType: "plain" | "html" | "markdown" }`
+- Output: `{ messageId: string }`
+
 #### sendSMS
 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)
@@ -641,6 +735,14 @@ Send an SMS or MMS message to a phone number configured via OAuth connection.
 - Input: `{ body: string, connectionId?: string, mediaUrls?: string[] }`
 - Output: `unknown`
 
+#### setGmailReadStatus
+Mark one or more Gmail emails as read or unread.
+- Requires a Google OAuth connection with Gmail modify scope.
+- Accepts one or more message IDs as a comma-separated string or array.
+- Set markAsRead to true to mark as read, false to mark as unread.
+- Input: `{ messageIds: string, markAsRead: boolean, connectionId?: string }`
+- Output: `unknown`
+
 #### setRunTitle
 Set the title of the agent run for the user's history
 - Input: `{ title: string }`
@@ -723,6 +825,14 @@ Trim an audio or video clip
 - Input: `{ inputUrl: string, start?: number | string, duration?: string | number, skipAssetCreation?: boolean }`
 - Output: `{ mediaUrl: string }`
 
+#### updateGmailLabels
+Add or remove labels on Gmail messages, identified by message IDs or a search query.
+- Requires a Google OAuth connection with Gmail modify scope.
+- Provide either a query (Gmail search syntax) or explicit messageIds to target messages.
+- Label IDs can be label names or Gmail label IDs — names are resolved automatically.
+- Input: `{ query: string, connectionId?: string, messageIds: string, addLabelIds: string, removeLabelIds: string }`
+- Output: `{ updatedMessageIds: string[] }`
+
 #### uploadDataSourceDocument
 Upload a file into an existing data source from a URL or raw text content.
 - If "file" is a single URL, the file is downloaded from that URL and uploaded.
@@ -1292,12 +1402,10 @@ Output:
   models: {
     id: string;
     name: string;            // Display name
-    rawName: string;          // Full provider model identifier
     type: "llm_chat" | "image_generation" | "video_generation" | "video_analysis" | "text_to_speech" | "vision" | "transcription";
-    publisher: string;
     maxTemperature: number;
     maxResponseSize: number;
-    contextWindow: number;
+    inputs: object[];        // Accepted input types
   }[]
 }
 ```
@@ -1307,12 +1415,39 @@ List AI models filtered by type.
 - `modelType`: `"llm_chat"` | `"image_generation"` | `"video_generation"` | `"video_analysis"` | `"text_to_speech"` | `"vision"` | `"transcription"`
 - Output: same as `listModels()`
 
+#### `listModelsSummary()`
+List all available AI models (summary). Returns only id, name, type, and tags. Suitable for display or consumption inside a model context window.
+
+Output:
+```typescript
+{
+  models: {
+    id: string;
+    name: string;
+    type: "llm_chat" | "image_generation" | "video_generation" | "video_analysis" | "text_to_speech" | "vision" | "transcription";
+    tags: string;            // Comma-separated tags
+  }[]
+}
+```
+
+#### `listModelsSummaryByType(modelType)`
+List AI models (summary) filtered by type.
+- `modelType`: `"llm_chat"` | `"image_generation"` | `"video_generation"` | `"video_analysis"` | `"text_to_speech"` | `"vision"` | `"transcription"`
+- Output: same as `listModelsSummary()`
+
 #### `listConnectors()`
-List available connector services (Slack, Google, HubSpot, etc.).
+List available connector services (Slack, Google, HubSpot, etc.) and their actions.
 
 Output:
 ```typescript
-{ services: Array<{ service: object, actions: object[] }> }
+{
+  services: {
+    id: string;
+    name: string;
+    icon: string;
+    actions: { id: string; name: string }[];
+  }[]
+}
 ```
 
 #### `getConnector(serviceId)`
@@ -1320,5 +1455,68 @@ Get details for a single connector service by ID.
 
 Output:
 ```typescript
-{ service: object }
+{
+  service: {
+    id: string;
+    name: string;
+    icon: string;
+    actions: { id: string; name: string }[];
+  }
+}
+```
+
+#### `getConnectorAction(serviceId, actionId)`
+Get the full configuration for a connector action, including all input fields needed to call it via `runFromConnectorRegistry`. Connectors are sourced from the open-source MindStudio Connector Registry (MSCR) with 850+ connector actions across third-party services.
+
+Output:
+```typescript
+{
+  action: {
+    id: string;
+    name: string;
+    description: string;
+    quickHelp: string;
+    configuration: { title: string; items: { label: string; helpText: string; variable: string; type: string; defaultValue: string; placeholder: string; selectOptions?: object }[] }[];
+  }
+}
+```
+
+#### `listConnections()`
+List OAuth connections for the organization. Use the returned connection IDs when calling connector actions. Connectors require the user to connect to the third-party service in MindStudio before they can be used.
+
+Output:
+```typescript
+{
+  connections: {
+    id: string;       // Connection ID to pass to connector actions
+    provider: string; // Integration provider (e.g. slack, google)
+    name: string;     // Display name or account identifier
+  }[]
+}
+```
+
+#### `estimateStepCost(stepType, step?, options?)`
+Estimate the cost of executing a step before running it. Pass the same step config you would use for execution.
+
+```typescript
+const estimate = await agent.estimateStepCost('generateText', { message: 'Hello' });
+```
+
+- `stepType`: string — The step method name (e.g. `"generateText"`).
+- `step`: object — Optional step input parameters for more accurate estimates.
+- `options`: `{ appId?: string, workflowId?: string }` — Optional context for pricing.
+
+Output:
+```typescript
+{
+  costType?: string;  // "free" when the step has no cost
+  estimates?: {
+    eventType: string;       // Billing event type
+    label: string;           // Human-readable cost label
+    unitPrice: number;       // Price per unit in billing units
+    unitType: string;        // What constitutes a unit (e.g. "token", "request")
+    estimatedCost?: number;  // Estimated total cost, or null if not estimable
+    quantity: number;        // Number of billable units
+  }[]
+}
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/agent",
-  "version": "0.0.20",
+  "version": "0.1.1",
   "description": "TypeScript SDK for MindStudio direct step execution",
   "type": "module",
   "main": "./dist/index.js",