@mindstudio-ai/agent 0.1.5 → 0.1.7

package/README.md

@@ -264,6 +264,47 @@ const result = await agent.runAgent({
 
 `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`.
 
+## Batch execution
+
+Execute multiple steps in parallel in a single request. All steps run server-side in parallel — results come back in the same order as the input. Individual failures don't affect other steps.
+
+```typescript
+const { results, totalBillingCost } = await agent.executeStepBatch([
+  { stepType: 'generateImage', step: { prompt: 'A mountain landscape' } },
+  { stepType: 'textToSpeech', step: { text: 'Welcome to the app' } },
+  { stepType: 'searchGoogle', step: { query: 'TypeScript best practices' } },
+]);
+
+// Each result has: stepType, output?, billingCost?, error?
+for (const r of results) {
+  if (r.error) {
+    console.error(`${r.stepType} failed: ${r.error}`);
+  } else {
+    console.log(`${r.stepType}:`, r.output);
+  }
+}
+```
+
+Maximum 50 steps per batch. Supports `appId` and `threadId` options for thread context.
+
+From the CLI:
+
+```bash
+# Inline JSON array
+mindstudio batch '[
+  {"stepType": "generateImage", "step": {"prompt": "a sunset"}},
+  {"stepType": "searchGoogle", "step": {"query": "cats"}}
+]'
+
+# Piped from a file
+cat steps.json | mindstudio batch
+
+# Strip metadata
+mindstudio batch --no-meta '[...]'
+```
+
+Run `mindstudio batch` with no arguments for full usage help.
+
 ## Thread persistence
 
 Steps execute within threads. Pass `$threadId` and `$appId` from a previous call to maintain state:
@@ -374,6 +415,10 @@ import type {
   ListAgentsResult,
   RunAgentOptions,
   RunAgentResult,
+  BatchStepInput,
+  BatchStepResult,
+  ExecuteStepBatchOptions,
+  ExecuteStepBatchResult,
 } from '@mindstudio-ai/agent';
 ```
 
@@ -411,6 +456,7 @@ Commands:
   whoami                           Show current authentication status
   <method> [json | --flags]        Execute a step method
   exec <method> [json | --flags]   Execute a step method (same as above)
+  batch [json]                     Execute multiple steps in parallel
   list [--json]                    List available methods
   info <method>                    Show method details (params, types, output)
   agents [--json]                  List pre-built agents in your organization

package/dist/cli.js

@@ -682,8 +682,8 @@ var init_metadata = __esm({
       "postToX": {
         stepType: "postToX",
         description: "Create a post on X (Twitter) from the connected account.",
-        usageNotes: "- Requires an X OAuth connection (connectionId).\n- Posts are plain text. Maximum 280 characters.",
-        inputSchema: { "type": "object", "properties": { "text": { "type": "string", "description": "The text content of the post (max 280 characters)" }, "connectionId": { "type": "string", "description": "X (Twitter) OAuth connection ID" } }, "required": ["text"] },
+        usageNotes: "- Requires an X OAuth connection (connectionId).\n- Maximum 280 characters of text.\n- Optionally attach up to 4 media items (images, GIFs, or videos) via mediaUrls.\n- Media URLs must be publicly accessible. The service fetches and uploads them to X.\n- Supported formats: JPEG, PNG, GIF, WEBP, MP4. Images up to 5MB, videos up to 512MB.",
+        inputSchema: { "type": "object", "properties": { "text": { "type": "string", "description": "The text content of the post (max 280 characters)" }, "connectionId": { "type": "string", "description": "X (Twitter) OAuth connection ID" }, "mediaUrls": { "type": "array", "items": { "type": "string" }, "description": "Up to 4 URLs of images, GIFs, or videos to attach to the post" } }, "required": ["text"] },
         outputSchema: { "description": "This step does not produce output data." }
       },
       "postToZapier": {
@@ -1907,6 +1907,69 @@ var init_client = __esm({
           $billingEvents: billingEvents != null ? JSON.parse(billingEvents) : void 0
         };
       }
+      /**
+       * Execute multiple steps in parallel in a single request.
+       *
+       * All steps run in parallel on the server. Results are returned in the same
+       * order as the input. Individual step failures do not affect other steps —
+       * partial success is possible.
+       *
+       * ```ts
+       * const { results } = await agent.executeStepBatch([
+       *   { stepType: 'generateImage', step: { prompt: 'a sunset' } },
+       *   { stepType: 'textToSpeech', step: { text: 'Hello world' } },
+       * ]);
+       * ```
+       */
+      async executeStepBatch(steps, options) {
+        const threadId = options?.threadId ?? (this._reuseThreadId ? this._threadId : void 0);
+        const { data } = await request(this._httpConfig, "POST", "/steps/execute-batch", {
+          steps,
+          ...options?.appId != null && { appId: options.appId },
+          ...threadId != null && { threadId }
+        });
+        const results = await Promise.all(
+          data.results.map(async (r) => {
+            if (r.output != null) {
+              return {
+                stepType: r.stepType,
+                output: r.output,
+                billingCost: r.billingCost,
+                error: r.error
+              };
+            }
+            if (r.outputUrl) {
+              const res = await fetch(r.outputUrl);
+              if (!res.ok) {
+                return {
+                  stepType: r.stepType,
+                  error: `Failed to fetch output from S3: ${res.status} ${res.statusText}`
+                };
+              }
+              const envelope = await res.json();
+              return {
+                stepType: r.stepType,
+                output: envelope.value,
+                billingCost: r.billingCost
+              };
+            }
+            return {
+              stepType: r.stepType,
+              billingCost: r.billingCost,
+              error: r.error
+            };
+          })
+        );
+        if (this._reuseThreadId && data.threadId) {
+          this._threadId = data.threadId;
+        }
+        return {
+          results,
+          totalBillingCost: data.totalBillingCost,
+          appId: data.appId,
+          threadId: data.threadId
+        };
+      }
       /**
        * Get the authenticated user's identity and organization info.
        *
@@ -2211,7 +2274,7 @@ async function startMcpServer(options) {
           capabilities: { tools: {} },
           serverInfo: {
             name: "mindstudio-agent",
-            version: "0.1.5"
+            version: "0.1.7"
           },
           instructions: "Welcome to MindStudio \u2014 a platform with 200+ AI models, 850+ third-party integrations, and pre-built agents.\n\nGetting started:\n1. Call `listAgents` to verify your connection and see available agents.\n2. Call `changeName` to set your display name \u2014 use your name or whatever your user calls you. This is how you'll appear in MindStudio request logs.\n3. 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.\n4. Call `listActions` to discover all available actions.\n\nThen use the tools to generate text, images, video, audio, search the web, work with data sources, run agents, and more.\n\nImportant:\n- AI-powered actions (text generation, image generation, video, audio, etc.) cost money. Before running these, call `estimateActionCost` and confirm with the user before proceeding \u2014 unless they've explicitly told you to go ahead.\n- Not all agents from `listAgents` are configured for API use. Do not try to run an agent just because it appears in the list \u2014 it will likely fail. Only run agents the user specifically asks you to run."
         });
@@ -2264,8 +2327,11 @@ async function startMcpServer(options) {
           } else if (toolName === "listConnections") {
             result = await getAgent().listConnections();
           } else if (toolName === "estimateActionCost") {
+            const meta = await getMetadata();
+            const rawType = args.stepType;
+            const resolved = meta[rawType]?.stepType ?? rawType;
             result = await getAgent().estimateStepCost(
-              args.stepType,
+              resolved,
               args.step,
               {
                 appId: args.appId,
@@ -2292,6 +2358,10 @@ async function startMcpServer(options) {
               extension: ext,
               ...mimeType && { type: mimeType }
             });
+          } else if (toolName === "executeBatch") {
+            result = await getAgent().executeStepBatch(
+              args.steps
+            );
           } else if (toolName === "listAgents") {
             result = await getAgent().listAgents();
           } else if (toolName === "runAgent") {
@@ -2382,7 +2452,8 @@ var init_mcp = __esm({
       changeProfilePicture: "Update the profile picture of the authenticated agent.",
       uploadFile: "Upload a file to the MindStudio CDN.",
       listAgents: "List all pre-built agents in the organization.",
-      runAgent: "Run a pre-built agent and wait for the result."
+      runAgent: "Run a pre-built agent and wait for the result.",
+      executeBatch: "Execute multiple actions in parallel in a single request."
     };
     HELPER_TOOLS = [
       {
@@ -2550,6 +2621,37 @@ var init_mcp = __esm({
           required: ["filePath"]
         }
       },
+      {
+        name: "executeBatch",
+        description: "Execute multiple actions in parallel in a single request. All steps run in parallel on the server. Results are returned in the same order as the input. Individual step failures do not affect other steps \u2014 partial success is possible. Maximum 50 steps per batch.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            steps: {
+              type: "array",
+              description: "Array of steps to execute.",
+              minItems: 1,
+              maxItems: 50,
+              items: {
+                type: "object",
+                properties: {
+                  stepType: {
+                    type: "string",
+                    description: 'The action type name (e.g. "generateImage", "textToSpeech").'
+                  },
+                  step: {
+                    type: "object",
+                    description: "Action input parameters.",
+                    additionalProperties: true
+                  }
+                },
+                required: ["stepType", "step"]
+              }
+            }
+          },
+          required: ["steps"]
+        }
+      },
       {
         name: "listAgents",
         description: "List all pre-built agents in the organization along with org metadata.",
@@ -2603,6 +2705,9 @@ Discover:
   info <action>                        Show action details and parameters
   list-models [--type <t>] [--summary] List available AI models
 
+Batch:
+  batch [json]                         Execute multiple actions in parallel
+
 Pre-built agents:
   agents [--json]                      List agents in your organization
   run-agent <appId> [json | --flags]   Run an agent and wait for result
@@ -2645,6 +2750,7 @@ Examples:
   mindstudio list-actions --summary
   mindstudio info generate-image
   mindstudio list-models --type image_generation
+  mindstudio batch '[{"stepType":"generateImage","step":{"prompt":"a cat"}}]'
   mindstudio run-agent <appId> --query "hello"
   mindstudio agents
   mindstudio mcp
@@ -2700,6 +2806,10 @@ function fatal(message) {
   process.stderr.write(JSON.stringify({ error: { message } }) + "\n");
   process.exit(1);
 }
+function usageBlock(lines) {
+  process.stderr.write("\n" + lines.map((l) => "  " + l).join("\n") + "\n\n");
+  process.exit(1);
+}
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) {
@@ -2971,6 +3081,52 @@ async function cmdRun(appId, variables, options) {
     process.stdout.write(JSON.stringify(result, null, 2) + "\n");
   }
 }
+async function cmdBatch(input, options) {
+  if (!Array.isArray(input)) {
+    fatal(
+      `Batch input must be a JSON array of { stepType, step } objects.
+Example: mindstudio batch '[{"stepType":"generateImage","step":{"prompt":"a cat"}}]'`
+    );
+  }
+  for (let i = 0; i < input.length; i++) {
+    const item = input[i];
+    if (!item || typeof item !== "object" || !item.stepType || !item.step) {
+      fatal(
+        `Invalid step at index ${i}: each entry must have "stepType" and "step" fields.`
+      );
+    }
+  }
+  const { stepMetadata: stepMetadata2 } = await Promise.resolve().then(() => (init_metadata(), metadata_exports));
+  const metaByName = new Map(
+    Object.entries(stepMetadata2).map(([name, m]) => [name, m])
+  );
+  const steps = input.map(
+    (item, i) => {
+      let meta = metaByName.get(item.stepType);
+      if (!meta) {
+        const camel = item.stepType.replace(
+          /-([a-z])/g,
+          (_, c) => c.toUpperCase()
+        );
+        meta = metaByName.get(camel);
+      }
+      if (meta) {
+        return { stepType: meta.stepType, step: item.step };
+      }
+      return { stepType: item.stepType, step: item.step };
+    }
+  );
+  const agent = await createAgent(options);
+  const result = await agent.executeStepBatch(steps, {
+    appId: options.appId,
+    threadId: options.threadId
+  });
+  if (options.noMeta) {
+    process.stdout.write(JSON.stringify(result.results, null, 2) + "\n");
+  } else {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  }
+}
 var MIME_TYPES2 = {
   png: "image/png",
   jpg: "image/jpeg",
@@ -3026,7 +3182,7 @@ function isNewerVersion(current, latest) {
   return false;
 }
 async function checkForUpdate() {
-  const currentVersion = "0.1.5";
+  const currentVersion = "0.1.7";
   if (!currentVersion) return null;
   try {
     const { loadConfig: loadConfig2, saveConfig: saveConfig2 } = await Promise.resolve().then(() => (init_config(), config_exports));
@@ -3055,7 +3211,7 @@ async function checkForUpdate() {
   }
 }
 function printUpdateNotice(latestVersion) {
-  const currentVersion = "0.1.5";
+  const currentVersion = "0.1.7";
   process.stderr.write(
     `
   ${ansi.cyanBright("Update available")} ${ansi.gray(currentVersion + " \u2192")} ${ansi.cyanBold(latestVersion)}
@@ -3130,7 +3286,7 @@ async function cmdLogin(options) {
   process.stderr.write("\n");
   printLogo();
   process.stderr.write("\n");
-  const ver = "0.1.5";
+  const ver = "0.1.7";
   process.stderr.write(
     `  ${ansi.bold("MindStudio Agent")} ${ver ? " " + ansi.gray("v" + ver) : ""}
 `
@@ -3463,10 +3619,82 @@ async function main() {
       });
       return;
     }
+    if (command === "batch") {
+      let input2;
+      const firstArg = positionals[1];
+      if (firstArg && firstArg.startsWith("[")) {
+        try {
+          input2 = parseJson5(firstArg);
+        } catch {
+          fatal(`Invalid JSON input: ${firstArg}`);
+        }
+      } else if (!process.stdin.isTTY) {
+        const raw = (await readStdin()).trim();
+        if (raw) {
+          try {
+            input2 = parseJson5(raw);
+          } catch {
+            fatal(`Invalid JSON on stdin: ${raw}`);
+          }
+        }
+      }
+      if (input2 === void 0) {
+        usageBlock([
+          "batch \u2014 Execute multiple actions in parallel",
+          "",
+          "Usage:",
+          `  mindstudio batch '[{ "stepType": "<action>", "step": { ... } }, ...]'`,
+          "  cat steps.json | mindstudio batch",
+          "",
+          'Each entry needs "stepType" (action name) and "step" (input object).',
+          "Maximum 50 steps per batch. Results come back in the same order.",
+          "Individual failures don't affect other steps.",
+          "",
+          "Options:",
+          "  --app-id <id>      App ID for thread context",
+          "  --thread-id <id>   Thread ID for state persistence",
+          "  --no-meta          Strip top-level metadata from output",
+          "",
+          "Examples:",
+          "  mindstudio batch '[",
+          '    { "stepType": "generateImage", "step": { "prompt": "a sunset" } },',
+          '    { "stepType": "textToSpeech", "step": { "text": "hello world" } }',
+          "  ]'",
+          "",
+          `  echo '[{"stepType":"searchGoogle","step":{"query":"cats"}}]' | mindstudio batch`
+        ]);
+      }
+      await cmdBatch(input2, {
+        apiKey: values["api-key"],
+        baseUrl: values["base-url"],
+        appId: values["app-id"],
+        threadId: values["thread-id"],
+        noMeta: values["no-meta"]
+      });
+      return;
+    }
     if (command === "run-agent") {
       const appId = positionals[1];
       if (!appId)
-        fatal("Missing app ID. Usage: mindstudio run-agent <appId> [json | --flags]");
+        usageBlock([
+          "run-agent \u2014 Run a pre-built agent and wait for the result",
+          "",
+          "Usage:",
+          "  mindstudio run-agent <appId> [json | --flags]",
+          "",
+          "Options:",
+          "  --workflow <name>  Workflow to execute (default: app default)",
+          '  --version <ver>    App version, e.g. "draft" (default: "live")',
+          "  --output-key <key> Extract a single field from the result",
+          "  --no-meta          Strip metadata from output",
+          "",
+          "Examples:",
+          '  mindstudio run-agent abc123 --query "hello"',
+          `  mindstudio run-agent abc123 '{"query": "hello"}'`,
+          "  mindstudio run-agent abc123 --workflow summarize --version draft",
+          "",
+          'Tip: run "mindstudio agents" to list available agent IDs.'
+        ]);
       const runArgv = process.argv.slice(process.argv.indexOf("run-agent") + 2);
       const stepArgs = [];
       for (let i = 0; i < runArgv.length; i++) {
@@ -3515,7 +3743,18 @@ async function main() {
     if (command === "upload") {
       const filePath = positionals[1];
       if (!filePath)
-        fatal("Missing file path. Usage: mindstudio upload <filepath>");
+        usageBlock([
+          "upload \u2014 Upload a file to the MindStudio CDN",
+          "",
+          "Usage:",
+          "  mindstudio upload <filepath>",
+          "",
+          "Returns the permanent public URL for the uploaded file.",
+          "",
+          "Examples:",
+          "  mindstudio upload photo.png",
+          "  mindstudio upload /path/to/document.pdf"
+        ]);
       await cmdUpload(filePath, {
         apiKey: values["api-key"],
         baseUrl: values["base-url"]
@@ -3532,7 +3771,20 @@ async function main() {
       if (command === "list-models-by-type" || command === "list-models-summary-by-type") {
         type = positionals[1];
         if (!type)
-          fatal(`Missing model type. Usage: mindstudio ${command} <type>`);
+          usageBlock([
+            `${command} \u2014 List AI models filtered by type`,
+            "",
+            "Usage:",
+            `  mindstudio ${command} <type>`,
+            "",
+            "Types:",
+            "  llm_chat, image_generation, video_generation,",
+            "  video_analysis, text_to_speech, vision, transcription",
+            "",
+            "Examples:",
+            `  mindstudio ${command} image_generation`,
+            `  mindstudio ${command} llm_chat`
+          ]);
       }
       if (command === "list-models-summary" || command === "list-models-summary-by-type") {
         summary = true;
@@ -3562,9 +3814,22 @@ async function main() {
     if (command === "estimate-cost") {
       const stepMethod = positionals[1];
       if (!stepMethod)
-        fatal(
-          "Missing action name. Usage: mindstudio estimate-cost <action> [json | --flags]"
-        );
+        usageBlock([
+          "estimate-cost \u2014 Estimate the cost of an action before running it",
+          "",
+          "Usage:",
+          "  mindstudio estimate-cost <action> [json | --flags]",
+          "",
+          "Examples:",
+          '  mindstudio estimate-cost generate-image --prompt "a sunset"',
+          `  mindstudio estimate-cost generate-text '{"message": "hello"}'`,
+          "",
+          'Tip: run "mindstudio list-actions" to see available actions.'
+        ]);
+      const allKeys2 = await getAllMethodKeys();
+      const resolvedMethod = resolveMethodOrFail(stepMethod, allKeys2);
+      const { stepMetadata: stepMetadata2 } = await Promise.resolve().then(() => (init_metadata(), metadata_exports));
+      const meta = stepMetadata2[resolvedMethod];
       const costArgv = positionals.slice(2);
       let costInput;
       const firstArg = costArgv[0];
@@ -3577,7 +3842,7 @@ async function main() {
       } else {
         costInput = parseStepFlags(costArgv);
       }
-      await cmdEstimateStepCost(stepMethod, costInput, {
+      await cmdEstimateStepCost(meta.stepType, costInput, {
         apiKey: values["api-key"],
         baseUrl: values["base-url"]
       });
@@ -3586,7 +3851,15 @@ async function main() {
     if (command === "change-name") {
       const name = positionals[1];
       if (!name)
-        fatal("Missing name. Usage: mindstudio change-name <name>");
+        usageBlock([
+          "change-name \u2014 Update your display name",
+          "",
+          "Usage:",
+          "  mindstudio change-name <name>",
+          "",
+          "Examples:",
+          '  mindstudio change-name "My Agent"'
+        ]);
       await cmdChangeName(name, {
         apiKey: values["api-key"],
         baseUrl: values["base-url"]
@@ -3596,9 +3869,17 @@ async function main() {
     if (command === "change-profile-picture") {
       const url = positionals[1];
       if (!url)
-        fatal(
-          "Missing URL. Usage: mindstudio change-profile-picture <url>"
-        );
+        usageBlock([
+          "change-profile-picture \u2014 Update your profile picture",
+          "",
+          "Usage:",
+          "  mindstudio change-profile-picture <url>",
+          "",
+          "Examples:",
+          "  mindstudio change-profile-picture https://example.com/avatar.png",
+          "",
+          'Tip: use "mindstudio upload" to host an image first.'
+        ]);
       await cmdChangeProfilePicture(url, {
         apiKey: values["api-key"],
         baseUrl: values["base-url"]
@@ -3616,13 +3897,48 @@ async function main() {
     if (command === "info") {
       const rawMethod2 = positionals[1];
       if (!rawMethod2)
-        fatal("Missing action name. Usage: mindstudio info <action>");
+        usageBlock([
+          "info \u2014 Show action details and parameters",
+          "",
+          "Usage:",
+          "  mindstudio info <action>",
+          "",
+          "Shows the description, input parameters (with types and",
+          "defaults), and output fields for an action.",
+          "",
+          "Examples:",
+          "  mindstudio info generate-image",
+          "  mindstudio info search-google",
+          "",
+          'Tip: run "mindstudio list-actions" to see available actions.'
+        ]);
       await cmdInfo(rawMethod2);
       return;
     }
     const split = findMethodSplit(process.argv.slice(2));
     if (!split)
-      fatal("Missing action name. Usage: mindstudio <action> [json | --flags]");
+      usageBlock([
+        "Run an action directly",
+        "",
+        "Usage:",
+        "  mindstudio <action> [json | --flags]",
+        "  mindstudio run <action> [json | --flags]",
+        "",
+        "Input can be inline JSON, --flags, or piped via stdin.",
+        "",
+        "Options:",
+        "  --app-id <id>      App ID for thread context",
+        "  --thread-id <id>   Thread ID for state persistence",
+        "  --output-key <key> Extract a single field from the result",
+        "  --no-meta          Strip $-prefixed metadata from output",
+        "",
+        "Examples:",
+        '  mindstudio generate-image --prompt "a sunset"',
+        `  mindstudio search-google '{"query": "cats"}'`,
+        `  echo '{"message":"hello"}' | mindstudio generate-text`,
+        "",
+        'Tip: run "mindstudio list-actions" to see available actions.'
+      ]);
     const { rawMethod, stepArgv } = split;
     const allKeys = await getAllMethodKeys();
     const method = resolveMethodOrFail(rawMethod, allKeys);