@mindstudio-ai/agent 0.0.19 → 0.1.0

package/llms.txt

@@ -1,6 +1,6 @@
 # @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+ integrations including 850+ third-party connectors 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.
 
@@ -98,9 +98,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 +109,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,
   },
@@ -243,6 +243,16 @@ Delete a single document from a data source.
 - Input: `{ dataSourceId: string, documentId: string }`
 - Output: `unknown`
 
+#### detectChanges
+Detect changes between runs by comparing current input against previously stored state. Routes execution based on whether a change occurred.
+- Persists state across runs using a global variable keyed to the step ID.
+- Two modes: "comparison" (default) uses strict string inequality; "ai" uses an LLM to determine if a meaningful change occurred.
+- First run always treats the value as "changed" since there is no previous state.
+- Each mode supports transitions to different steps/workflows for the "changed" and "unchanged" paths.
+- AI mode bills normally for the LLM call.
+- Input: `{ mode: "ai" | "comparison", input: string, prompt?: 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 }, previousValueVariable?: string, changedStepId?: string, changedWorkflowId?: string, unchangedStepId?: string, unchangedWorkflowId?: string }`
+- Output: `{ hasChanged: boolean, currentValue: string, previousValue: string, isFirstRun: boolean }`
+
 #### detectPII
 Scan text for personally identifiable information using Microsoft Presidio.
 - In workflow mode, transitions to detectedStepId if PII is found, notDetectedStepId otherwise.
@@ -251,6 +261,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
@@ -405,12 +446,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
@@ -499,6 +541,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.
@@ -1250,12 +1302,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
   }[]
 }
 ```
@@ -1265,12 +1315,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)`
@@ -1278,5 +1355,42 @@ 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+ third-party service integrations.
+
+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
+  }[]
+}
 ```

package/package.json

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