@mindstudio-ai/agent 0.0.20 → 0.1.1

package/README.md

@@ -1,8 +1,10 @@
 # @mindstudio-ai/agent
 
-TypeScript SDK, CLI, and MCP server for executing [MindStudio](https://mindstudio.ai) workflow steps directly.
+Every AI model. Every integration. One SDK.
 
-Call any of MindStudio's 120+ built-in actions — AI models, image/video generation, web scraping, integrations, and more — with fully typed inputs and outputs. Use from TypeScript, the command line, or any MCP-compatible AI agent.
+[MindStudio](https://mindstudio.ai) gives you direct access to 200+ AI models and [1,000+ integrations](https://github.com/mindstudio-ai/mscr) — no separate API keys, no setup, no friction. This package is the developer toolkit: a TypeScript SDK, CLI, and MCP server that puts the entire platform at your fingertips.
+
+Generate text, images, video, and audio. Scrape the web. Search Google. Post to Slack. Read from Airtable. Send emails. Process media. Run any of 850+ connector actions across third-party services. All with one API key, fully typed, and ready to use from code, the command line, or any MCP-compatible AI agent.
 
 ## Install
 
@@ -21,27 +23,24 @@ import { MindStudioAgent } from '@mindstudio-ai/agent';
 
 const agent = new MindStudioAgent({ apiKey: 'your-api-key' });
 
-// Generate text with an AI model
+// Generate text with any AI model — OpenAI, Anthropic, Google, and more
 const { content } = await agent.generateText({
   message: 'Summarize this article: ...',
 });
-console.log(content);
 
 // Generate an image
 const { imageUrl } = await agent.generateImage({
   prompt: 'A mountain landscape at sunset',
 });
-console.log(imageUrl);
 
 // Search Google
 const { results } = await agent.searchGoogle({
   query: 'TypeScript best practices',
   exportType: 'json',
 });
-console.log(results);
 ```
 
-Every method is fully typed — your editor will autocomplete available parameters, show enum options, and infer the output shape. Results are returned flat for easy destructuring.
+Every method is fully typed — your editor will autocomplete parameters, show enum options, and infer the output shape. Results are returned flat for easy destructuring.
 
 ### CLI
 
@@ -49,13 +48,13 @@ Every method is fully typed — your editor will autocomplete available paramete
 # Authenticate (opens browser, saves key locally)
 mindstudio login
 
-# Execute a step with named flags
+# Execute with named flags
 mindstudio generate-image --prompt "A mountain landscape at sunset"
 
-# Or with JSON input (JSON5-tolerant: unquoted keys, single quotes, trailing commas)
+# Or with JSON input (JSON5-tolerant)
 mindstudio generate-image '{prompt: "A mountain landscape at sunset"}'
 
-# Just the image URL, no metadata
+# Extract a single output field
 mindstudio generate-image --prompt "A sunset" --output-key imageUrl
 
 # List all available methods
@@ -68,7 +67,7 @@ mindstudio info generate-image
 echo '{"query": "TypeScript best practices"}' | mindstudio search-google
 ```
 
-Run via `npx` without installing globally:
+Run via `npx` without installing:
 
 ```bash
 npx @mindstudio-ai/agent generate-text --message "Hello"
@@ -92,19 +91,19 @@ Add to your MCP client config (Claude Code, Cursor, VS Code, etc.):
 }
 ```
 
-All 120+ step methods are exposed as MCP tools with full JSON Schema input definitions, so your AI agent can discover and call them directly. The MCP server also exposes `listAgents` and `runAgent` tools for running pre-built agents.
+Every action is exposed as an MCP tool with full JSON Schema definitions — your AI agent can discover and call any of them directly.
 
 ## Authentication
 
-The fastest way to authenticate is the interactive login:
+The fastest way to get started:
 
 ```bash
 mindstudio login
 ```
 
-This opens your browser, authenticates with MindStudio, and saves your API key to `~/.mindstudio/config.json`. All subsequent CLI and SDK usage will pick it up automatically.
+Opens your browser, authenticates with MindStudio, and saves your API key to `~/.mindstudio/config.json`. All subsequent usage picks it up automatically.
 
-You can also authenticate via environment variable or constructor parameter:
+You can also authenticate via environment variable or constructor:
 
 ```typescript
 // Pass directly
@@ -115,88 +114,76 @@ const agent = new MindStudioAgent({ apiKey: 'your-api-key' });
 const agent = new MindStudioAgent();
 ```
 
-MindStudio routes to the correct AI provider (OpenAI, Google, Anthropic, etc.) server-side — you do not need separate provider API keys.
+One API key is all you need. MindStudio routes to the correct AI provider (OpenAI, Google, Anthropic, Meta, xAI, DeepSeek, etc.) server-side — no separate provider keys required.
 
 Other auth commands:
 
 ```bash
-# Check current auth status and verify credentials
-mindstudio whoami
-
-# Clear stored credentials
-mindstudio logout
+mindstudio whoami    # Check current auth status
+mindstudio logout    # Clear stored credentials
 ```
 
 Resolution order: constructor `apiKey` > `MINDSTUDIO_API_KEY` env > `~/.mindstudio/config.json` > `CALLBACK_TOKEN` env.
 
-## Thread persistence
+## 200+ AI models
 
-Steps execute within threads. Pass `$threadId` and `$appId` from a previous call to maintain state across calls:
+Direct access to models from every major provider — all through a single API key, billed at cost with no markups.
 
 ```typescript
-const r1 = await agent.generateText({
-  message: 'My name is Alice',
-});
-
-// The model remembers the conversation
-const r2 = await agent.generateText(
-  { message: 'What is my name?' },
-  { threadId: r1.$threadId, appId: r1.$appId },
-);
-```
+// Browse available models
+const { models } = await agent.listModelsSummary();
 
-### Automatic thread reuse
-
-For local debugging or scripts where you want all calls to share a single thread (similar to how MindStudio custom function sandboxes work), enable `reuseThreadId`:
-
-```typescript
-const agent = new MindStudioAgent({ reuseThreadId: true });
+// Filter by type
+const { models: imageModels } = await agent.listModelsSummaryByType('image_generation');
 
-// Or set the environment variable
-// MINDSTUDIO_REUSE_THREAD_ID=true
+// Use a specific model
+const { models: chatModels } = await agent.listModelsByType('llm_chat');
+const gemini = chatModels.find(m => m.name.includes('Gemini'));
 
-await agent.generateText({ message: 'My name is Alice' }); // creates a thread
-await agent.generateText({ message: 'What is my name?' }); // reuses the same thread automatically
+const { content } = await agent.generateText({
+  message: 'Hello',
+  modelOverride: {
+    model: gemini.id,
+    temperature: 0.7,
+    maxResponseTokens: 1024,
+  },
+});
 ```
 
-The thread ID from the first response is captured and sent with all subsequent calls. You can still override it per-call by passing an explicit `threadId` in the options.
-
-## Rate limiting
-
-Rate limiting is handled automatically:
+Model types: `llm_chat`, `image_generation`, `video_generation`, `video_analysis`, `text_to_speech`, `vision`, `transcription`.
 
-- **Concurrency queue** — requests beyond the server's concurrent limit are queued and proceed as slots open up (10 for internal tokens, 20 for API keys)
-- **Auto-retry on 429** — rate-limited responses are retried automatically using the `Retry-After` header (default: 3 retries, configurable via `maxRetries`)
-- **Call cap** — internal tokens are capped at 500 calls per execution; the SDK throws `MindStudioError` with code `call_cap_exceeded` rather than sending requests that will fail
+## 1,000+ integrations
 
-Every result includes `$rateLimitRemaining` so you can throttle proactively:
+850+ connector actions from the open-source [MindStudio Connector Registry (MSCR)](https://github.com/mindstudio-ai/mscr) — across services like ActiveCampaign, Airtable, Apollo, Canva, ElevenLabs, MailChimp, Notion, and more — alongside 140+ built-in actions for AI, media, web, and data processing.
 
 ```typescript
-const result = await agent.generateText({ message: 'Hello' });
-console.log(result.$rateLimitRemaining); // calls remaining in window
-```
+// Browse connectors and their actions
+const { services } = await agent.listConnectors();
+const { action } = await agent.getConnectorAction('slack', 'slack/send-message');
 
-## Billing
+// Check which services are connected in your org
+const { connections } = await agent.listConnections();
 
-Every result includes optional billing metadata:
-
-```typescript
-const result = await agent.generateImage({ prompt: 'A sunset' });
-console.log(result.$billingCost);   // cost in credits for this call
-console.log(result.$billingEvents); // itemized billing events
+// Execute a connector action
+const result = await agent.runFromConnectorRegistry({
+  serviceId: 'slack',
+  actionId: 'slack/send-message',
+  connectionId: 'your-connection-id',
+  // ... action-specific fields from getConnectorAction()
+});
 ```
 
-These fields are `undefined` when the server does not return billing headers.
+Connectors require the user to connect to the third-party service in MindStudio before use. Use `listConnections()` to check what's available.
 
-## Available steps
+## Built-in actions
 
-Every step has a dedicated typed method. A few highlights:
+Every action has a dedicated typed method. A few highlights:
 
 | Method | Description |
 | --- | --- |
-| `generateText()` | Send a message to an AI model |
-| `generateImage()` | Generate an image from a text prompt |
-| `generateVideo()` | Generate a video from a text prompt |
+| `generateText()` | Send a message to any AI model |
+| `generateImage()` | Generate an image from a prompt |
+| `generateVideo()` | Generate a video from a prompt |
 | `generateAsset()` | Generate an HTML/PDF/PNG/video asset |
 | `analyzeImage()` | Analyze an image with a vision model |
 | `textToSpeech()` | Convert text to speech |
@@ -206,9 +193,9 @@ Every step has a dedicated typed method. A few highlights:
 | `httpRequest()` | Make an HTTP request |
 | `sendEmail()` | Send an email |
 | `postToSlackChannel()` | Post to a Slack channel |
-| `runWorkflow()` | Run another MindStudio workflow |
+| `runPackagedWorkflow()` | Run another MindStudio workflow |
 
-...and 100+ more for Google Docs/Sheets/Calendar, YouTube, LinkedIn, HubSpot, Airtable, Notion, Coda, Telegram, media processing, PII detection, and more.
+...and 130+ more for Google Docs/Sheets/Calendar, YouTube, LinkedIn, HubSpot, Airtable, Notion, Coda, Telegram, media processing, PII detection, and more.
 
 All methods show full documentation in your editor's IntelliSense — hover any method to see usage notes, parameter descriptions, and enum options.
 
@@ -239,19 +226,35 @@ const result = await agent.runAgent({
 });
 ```
 
-`runAgent()` always uses async mode internally — it submits the run, then polls for the result until it completes or fails. The poll interval defaults to 1 second and can be configured with `pollIntervalMs`.
+`runAgent()` uses async polling internally — it submits the run, then polls until complete or failed. The poll interval defaults to 1 second and can be configured with `pollIntervalMs`.
 
-## Helpers
+## Thread persistence
+
+Steps execute within threads. Pass `$threadId` and `$appId` from a previous call to maintain state:
 
 ```typescript
-// List all available AI models
-const { models } = await agent.listModels();
+const r1 = await agent.generateText({
+  message: 'My name is Alice',
+});
 
-// Filter by type
-const { models: chatModels } = await agent.listModelsByType('llm_chat');
+// The model remembers the conversation
+const r2 = await agent.generateText(
+  { message: 'What is my name?' },
+  { threadId: r1.$threadId, appId: r1.$appId },
+);
+```
 
-// List available connector services
-const { services } = await agent.listConnectors();
+### Automatic thread reuse
+
+For scripts where all calls should share a single thread:
+
+```typescript
+const agent = new MindStudioAgent({ reuseThreadId: true });
+
+// Or set MINDSTUDIO_REUSE_THREAD_ID=true
+
+await agent.generateText({ message: 'My name is Alice' }); // creates a thread
+await agent.generateText({ message: 'What is my name?' }); // reuses it automatically
 ```
 
 ## Configuration
@@ -274,19 +277,54 @@ const agent = new MindStudioAgent({
 });
 ```
 
+## Rate limiting
+
+Handled automatically:
+
+- **Concurrency queue** — requests beyond the server's concurrent limit are queued and proceed as slots open up
+- **Auto-retry on 429** — rate-limited responses are retried using the `Retry-After` header (default: 3 retries, configurable via `maxRetries`)
+- **Call cap** — internal tokens are capped at 500 calls per execution
+
+Every result includes `$rateLimitRemaining` so you can throttle proactively.
+
+## Billing
+
+Every result includes optional billing metadata:
+
+```typescript
+const result = await agent.generateImage({ prompt: 'A sunset' });
+console.log(result.$billingCost);   // cost in credits for this call
+console.log(result.$billingEvents); // itemized billing events
+```
+
+## Error handling
+
+```typescript
+import { MindStudioAgent, MindStudioError } from '@mindstudio-ai/agent';
+
+try {
+  await agent.generateImage({ prompt: '...' });
+} catch (err) {
+  if (err instanceof MindStudioError) {
+    console.error(err.message); // Human-readable message
+    console.error(err.code);    // "invalid_step_config", "api_error", "call_cap_exceeded", etc.
+    console.error(err.status);  // HTTP status (400, 401, 429, etc.)
+    console.error(err.details); // Raw API error body
+  }
+}
+```
+
 ## Low-level access
 
-For step types not yet in the generated methods, use `executeStep()` directly:
+For step types not yet in the generated methods:
 
 ```typescript
-const result = await agent.executeStep('someNewStep', {
-  param1: 'value',
-});
+const result = await agent.executeStep('someNewStep', { param1: 'value' });
 ```
 
 ## Types
 
-All input/output types are exported for use in your own code:
+All input/output types are exported:
 
 ```typescript
 import type {
@@ -408,7 +446,7 @@ mindstudio generate-text --message "What is my name?" \
 
 ## MCP server
 
-The package includes a built-in [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server. It exposes all step methods and helpers as tools, so any MCP-compatible AI agent (Claude Code, Cursor, Windsurf, VS Code Copilot, etc.) can discover and call them.
+The package includes a built-in [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server. It exposes every action, helper, and agent tool — so any MCP-compatible AI agent (Claude Code, Cursor, Windsurf, VS Code Copilot, etc.) can discover and use the full platform.
 
 Start manually:
 
@@ -456,24 +494,7 @@ The raw OpenAPI spec that this SDK is generated from is available at:
 https://v1.mindstudio-api.com/developer/v2/steps/openapi.json
 ```
 
-This contains full JSON Schema definitions for every step's input and output, descriptions, and usage notes. Useful if you want to build your own tooling, code generators, or integrations.
-
-## Error handling
-
-```typescript
-import { MindStudioAgent, MindStudioError } from '@mindstudio-ai/agent';
-
-try {
-  await agent.generateImage({ prompt: '...' });
-} catch (err) {
-  if (err instanceof MindStudioError) {
-    console.error(err.message); // Human-readable message
-    console.error(err.code);    // Machine-readable code (e.g. "invalid_step_config")
-    console.error(err.status);  // HTTP status (e.g. 400)
-    console.error(err.details); // Raw API error body
-  }
-}
-```
+Full JSON Schema definitions for every step's input and output. Useful for building your own tooling, code generators, or integrations.
 
 ## License