@mindstudio-ai/agent 0.0.16 → 0.0.18

package/llms.txt

@@ -36,10 +36,25 @@ mindstudio info generate-image
 npx @mindstudio-ai/agent generate-text --message "Hello"
 ```
 
-Auth: set `MINDSTUDIO_API_KEY` env var or pass `--api-key <key>`.
+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:
@@ -68,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:
@@ -138,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
 
@@ -218,6 +251,37 @@ Scan text for personally identifiable information using Microsoft Presidio.
 - Input: `{ input: string, language: string, entities: string[], detectedStepId?: string, notDetectedStepId?: string, outputLogVariable?: string | null }`
 - Output: `{ detected: boolean, detections: { entity_type: string, start: number, end: number, score: number }[] }`
 
+#### discordEditMessage
+Edit a previously sent Discord channel message. Use with the message ID returned by Send Discord Message.
+- Only messages sent by the bot can be edited.
+- The messageId is returned by the Send Discord Message step.
+- Optionally attach a file by providing a URL to attachmentUrl. The file is downloaded and uploaded to Discord.
+- When editing with an attachment, the new attachment replaces any previous attachments on the message.
+- URLs in the text are automatically embedded by Discord (link previews for images, videos, etc.).
+- Input: `{ botToken: string, channelId: string, messageId: string, text: string, attachmentUrl?: string }`
+- Output: `unknown`
+
+#### discordSendFollowUp
+Send a follow-up message to a Discord slash command interaction.
+- Requires the applicationId and interactionToken from the Discord trigger variables.
+- Follow-up messages appear as new messages in the channel after the initial response.
+- Returns the sent message ID.
+- Interaction tokens expire after 15 minutes.
+- Optionally attach a file by providing a URL to attachmentUrl. The file is downloaded and uploaded to Discord.
+- URLs in the text are automatically embedded by Discord (link previews for images, videos, etc.).
+- Input: `{ applicationId: string, interactionToken: string, text: string, attachmentUrl?: string }`
+- Output: `{ messageId: string }`
+
+#### discordSendMessage
+Send a message to Discord — either edit the loading message or send a new channel message.
+- mode "edit" replaces the loading message (interaction response) with the final result. Uses applicationId and interactionToken from trigger variables. No bot permissions required.
+- mode "send" sends a new message to a channel. Uses botToken and channelId from trigger variables. Returns a messageId that can be used with Edit Discord Message.
+- Optionally attach a file by providing a URL to attachmentUrl. The file is downloaded and uploaded to Discord.
+- URLs in the text are automatically embedded by Discord (link previews for images, videos, etc.).
+- Interaction tokens expire after 15 minutes.
+- Input: `{ mode: "edit" | "send", text: string, applicationId?: string, interactionToken?: string, botToken?: string, channelId?: string, attachmentUrl?: string }`
+- Output: `{ messageId?: string }`
+
 #### downloadVideo
 Download a video file
 - Works with YouTube, TikTok, etc., by using ytdlp behind the scenes
@@ -372,12 +436,13 @@ List all data sources for the current app.
 - Output: `unknown`
 
 #### logic
-Use an AI model to evaluate which condition from a list is most true, given a context prompt.
-- This is "fuzzy" logic evaluated by an AI model, not computational logic. The model picks the most accurate statement.
-- All possible cases must be specified — there is no default/fallback case.
+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.
+- In AI mode, the model picks the most accurate statement from the list. All possible cases must be specified.
+- In comparison mode, the context is the left operand and each case's condition is the right operand. First matching case wins. Use operator "default" as a fallback.
 - Requires at least two cases.
-- In workflow mode, transitions to the destinationStepId of the winning case. In direct execution, returns the winning case ID and condition.
-- Input: `{ context: string, cases: ({ id: string, condition: string, destinationStepId?: string } | string)[] }`
+- Each case can transition to a step in the current workflow (destinationStepId) or jump to another workflow (destinationWorkflowId).
+- Input: `{ mode?: "ai" | "comparison", context: string, cases: ({ id: string, condition: string, operator?: "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "exists" | "not_exists" | "contains" | "not_contains" | "default", destinationStepId?: string, destinationWorkflowId?: string } | string)[], modelOverride?: { 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 } }`
 - Output: `{ selectedCase: number }`
 
 #### makeDotComRunScenario
@@ -558,9 +623,12 @@ Send an email to one or more configured recipient addresses.
 - 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
@@ -576,6 +644,22 @@ Explicitly set a variable to a given value.
 - 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.
 - "audio" mode sends as a standard audio file. "voice" mode sends as a voice message (re-uploads the file for large file support).
@@ -596,8 +680,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.

package/package.json

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