@mindstudio-ai/agent 0.1.4 → 0.1.6

package/llms.txt

@@ -6,19 +6,19 @@ This file is the complete API reference. No other documentation is needed to use
 
 ## Recommended workflow
 
-There are 150+ methods available. Do NOT try to read or load them all at once. Follow this discovery flow:
+There are 150+ actions available. Do NOT try to read or load them all at once. Follow this discovery flow:
 
 1. **Identify yourself** — Call `changeName` to set your display name (use your name or whatever your user calls you). If you have a profile picture or icon, call `uploadFile` to upload it, then `changeProfilePicture` with the returned URL. This helps users identify your requests in their logs.
-2. **Discover** — Call `listSteps` (MCP tool) or `mindstudio list --summary` (CLI) to get a compact `{ method: description }` map of everything available (~3k tokens).
-3. **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.
-4. **Call it** — Invoke the method with the required parameters. All step methods share the same calling convention (see below).
+2. **Discover** — Call `listActions` (MCP tool) or `mindstudio list-actions --summary` (CLI) to get a compact `{ action: description }` map of everything available (~3k tokens).
+3. **Drill in** — Once you identify the right action, look up its full signature in the reference below, or call `mindstudio info <action>` (CLI) for parameter details.
+4. **Call it** — Invoke the action with the required parameters. All actions 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.
+- **OAuth third-party integrations** (Slack, Google, HubSpot, etc.): These are optional OAuth connectors from the MindStudio Connector Registry — for most tasks, use actions directly instead. If you need a third-party integration: 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. **Important:** Not all agents are configured for API use. Do not try to run an agent just because it appears in the list — only run agents the user specifically asks you to run.
-- **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**: AI-powered steps (text generation, image generation, video, audio, etc.) cost money. Call `estimateStepCost(stepType, stepInput)` before running these and confirm with the user before proceeding — unless they've explicitly given permission to go ahead. Non-AI steps (data lookups, connectors, etc.) are generally free.
+- **Model selection**: Call `listModelsSummary()` or `listModelsSummaryByType("llm_chat")` to browse models, then pass the model ID as `modelOverride.model` to actions like `generateText`. Use the summary endpoints (not `listModels`) to keep token usage low.
+- **Cost estimation**: AI-powered actions (text generation, image generation, video, audio, etc.) cost money. Call `estimateStepCost(stepType, stepInput)` before running these and confirm with the user before proceeding — unless they've explicitly given permission to go ahead. Non-AI actions (data lookups, OAuth connectors, etc.) are generally free.
 
 ## Install
 
@@ -200,11 +200,39 @@ try {
 
 ## Low-level access
 
-For step types not covered by generated methods:
+For action types not covered by generated methods:
 ```typescript
 const result = await agent.executeStep('stepType', { ...params });
 ```
 
+## Batch execution
+
+Execute multiple steps in parallel in a single request. Maximum 50 steps per batch.
+Individual step failures do not affect other steps — partial success is possible.
+
+```typescript
+const result = await agent.executeStepBatch([
+  { stepType: 'generateImage', step: { prompt: 'a sunset' } },
+  { stepType: 'textToSpeech', step: { text: 'hello world' } },
+], { appId?, threadId? });
+
+// Result:
+result.results;          // BatchStepResult[] — same order as input
+result.results[0].stepType;  // string
+result.results[0].output;    // object | undefined (step output on success)
+result.results[0].error;     // string | undefined (error message on failure)
+result.results[0].billingCost; // number | undefined (cost on success)
+result.totalBillingCost;  // number | undefined
+result.appId;            // string
+result.threadId;         // string
+```
+
+CLI:
+```bash
+mindstudio batch '[{"stepType":"generateImage","step":{"prompt":"a cat"}}]'
+cat steps.json | mindstudio batch
+```
+
 ## Methods
 
 All methods below are called on a `MindStudioAgent` instance (`agent.methodName(...)`).
@@ -1320,8 +1348,11 @@ Update the content of an existing Notion page.
 #### postToX
 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 }`
+- Maximum 280 characters of text.
+- Optionally attach up to 4 media items (images, GIFs, or videos) via mediaUrls.
+- Media URLs must be publicly accessible. The service fetches and uploads them to X.
+- Supported formats: JPEG, PNG, GIF, WEBP, MP4. Images up to 5MB, videos up to 512MB.
+- Input: `{ text: string, connectionId?: string, mediaUrls?: string[] }`
 - Output: `unknown`
 
 #### searchXPosts
@@ -1443,7 +1474,7 @@ List AI models (summary) filtered by type.
 - Output: same as `listModelsSummary()`
 
 #### `listConnectors()`
-List available connector services (Slack, Google, HubSpot, etc.) and their actions.
+List available OAuth connector services (Slack, Google, HubSpot, etc.) and their actions. These are third-party integrations — for most tasks, use actions directly instead.
 
 Output:
 ```typescript
@@ -1458,7 +1489,7 @@ Output:
 ```
 
 #### `getConnector(serviceId)`
-Get details for a single connector service by ID.
+Get details for a single OAuth connector service by ID.
 
 Output:
 ```typescript
@@ -1473,7 +1504,7 @@ Output:
 ```
 
 #### `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.
+Get the full configuration for an OAuth connector action, including all input fields needed to call it via `runFromConnectorRegistry`. OAuth connectors are sourced from the open-source MindStudio Connector Registry (MSCR) with 850+ actions across third-party services.
 
 Output:
 ```typescript
@@ -1489,7 +1520,7 @@ Output:
 ```
 
 #### `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.
+List OAuth connections for the organization (authenticated third-party service links). Use the returned connection IDs when calling OAuth connector actions. Connectors require the user to connect to the third-party service in MindStudio before they can be used.
 
 Output:
 ```typescript
@@ -1509,8 +1540,8 @@ Estimate the cost of executing a step before running it. Pass the same step conf
 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.
+- `stepType`: string — The action name (e.g. `"generateText"`).
+- `step`: object — Optional action input parameters for more accurate estimates.
 - `options`: `{ appId?: string, workflowId?: string }` — Optional context for pricing.
 
 Output:

package/package.json

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