@mindstudio-ai/agent 0.1.81 → 0.1.82

package/dist/index.d.ts

@@ -1302,11 +1302,26 @@ interface Db {
 /**
  * Tool configuration for {@link RunTaskOptions.tools}.
  * - String: SDK method name (e.g. `'searchGoogle'`).
- * - Object: method name with default input overrides that merge with the model's tool call arguments.
+ * - `{ method }`: SDK method name with default input overrides.
+ * - `{ appMethod }`: one of your own app's methods, called as the invoking
+ *   user with their roles.
+ *
+ * Defaults win over whatever the model passes for the same field, including
+ * nested fields — the model decides what to do, you pin how it's done.
  */
 type TaskToolConfig = string | {
     method: string;
     defaults?: Record<string, unknown>;
+} | {
+    appMethod: string;
+    /**
+     * How this method should be framed for *this* task. Falls back to the
+     * method's own description. Worth writing: the same method often serves
+     * different purposes across tasks, and the description is what tells the
+     * model when to reach for it.
+     */
+    description?: string;
+    defaults?: Record<string, unknown>;
 };
 /** Options for {@link MindStudioAgent.runTask}. */
 interface RunTaskOptions {
@@ -1314,7 +1329,7 @@ interface RunTaskOptions {
     prompt: string;
     /** Structured input for this task instance. Passed as the user message. */
     input: Record<string, unknown>;
-    /** SDK method names to make available as tools, with optional default overrides. */
+    /** SDK actions and/or app methods to make available as tools. */
     tools: TaskToolConfig[];
     /** Expected output shape. Pass a JSON string or an object (will be stringified automatically). */
     structuredOutputExample: string | Record<string, unknown>;
@@ -1488,11 +1503,18 @@ declare class MindStudioAgent$1 {
      * to produce structured output. The model receives the prompt and tools,
      * calls actions as needed, and returns JSON matching the output example.
      *
+     * Tools can be SDK actions, your own app's methods, or both. App methods run
+     * as the user who invoked the method that started the task, with their roles.
+     *
      * ```ts
      * const result = await agent.runTask<{ name: string; url: string }>({
-     *   prompt: 'Find canonical info for this restaurant.',
+     *   prompt: 'Find canonical info for this restaurant, then save it.',
      *   input: { restaurantName: 'Tartine Bakery SF' },
-     *   tools: ['searchGoogle', 'fetchUrl'],
+     *   tools: [
+     *     'searchGoogle',
+     *     'fetchUrl',
+     *     { appMethod: 'saveRestaurant', description: 'Persist the researched restaurant.' },
+     *   ],
      *   structuredOutputExample: JSON.stringify({ name: 'Tartine Bakery', url: 'https://tartinebakery.com' }),
      *   model: 'claude-4-6-sonnet',
      * });
@@ -4556,6 +4578,11 @@ interface ScrapeUrlStepOutput {
             /** Open Graph image URL */
             image: string;
         };
+        /** Set when the scrape failed. `text`/`html` still carry the human-readable error so existing callers behave as before, but callers that care — billing, in particular — can tell a failure from real page content. */
+        error?: {
+            code: string;
+            message: string;
+        };
     } | {
         /** Markdown/plain-text content of the scraped page */
         text: string;
@@ -4576,9 +4603,14 @@ interface ScrapeUrlStepOutput {
             /** Open Graph image URL */
             image: string;
         };
+        /** Set when the scrape failed. `text`/`html` still carry the human-readable error so existing callers behave as before, but callers that care — billing, in particular — can tell a failure from real page content. */
+        error?: {
+            code: string;
+            message: string;
+        };
     }[];
-    /** Screenshot URL, only present when screenshot was requested via pageOptions */
-    screenshot?: string;
+    /** Screenshot URL(s), only present when a screenshot was captured */
+    screenshot?: string | string[];
 }
 interface ScrapeXPostStepInput {
     /** Full URL to the X post (e.g. https://x.com/elonmusk/status/1655608985058267139) */
@@ -4606,6 +4638,11 @@ interface ScrapeXPostStepOutput {
             /** Open Graph image URL */
             image: string;
         };
+        /** Set when the scrape failed. `text`/`html` still carry the human-readable error so existing callers behave as before, but callers that care — billing, in particular — can tell a failure from real page content. */
+        error?: {
+            code: string;
+            message: string;
+        };
     };
 }
 interface ScrapeXProfileStepInput {
@@ -4634,6 +4671,11 @@ interface ScrapeXProfileStepOutput {
             /** Open Graph image URL */
             image: string;
         };
+        /** Set when the scrape failed. `text`/`html` still carry the human-readable error so existing callers behave as before, but callers that care — billing, in particular — can tell a failure from real page content. */
+        error?: {
+            code: string;
+            message: string;
+        };
     };
 }
 interface ScreenshotUrlStepInput {

package/dist/index.js

@@ -2785,21 +2785,21 @@ var stepMetadata = {
     description: "Extract text, HTML, or structured content from one or more web pages.",
     usageNotes: '- Accepts a single URL or multiple URLs (as a JSON array, comma-separated, or newline-separated).\n- Output format controls the result shape: "text" returns markdown, "html" returns raw HTML, "json" returns structured scraper data.\n- Can optionally capture a screenshot of each page.',
     inputSchema: { "type": "object", "properties": { "url": { "type": "string", "description": "URL(s) to scrape. Accepts a single URL, JSON array, or comma/newline-separated list" }, "service": { "enum": ["default", "firecrawl"], "type": "string", "description": "Scraping service to use" }, "autoEnhance": { "type": "boolean", "description": "Whether to enable enhanced scraping for social media URLs (e.g. Twitter, LinkedIn)" }, "outputFormat": { "enum": ["text", "json", "html"], "type": "string", "description": "Output format: text returns markdown, html returns raw HTML, json returns structured scraper data" }, "pageOptions": { "type": "object", "properties": { "onlyMainContent": { "type": "boolean", "description": "Whether to extract only the main content of the page, excluding navigation, footers, etc." }, "screenshot": { "type": "boolean", "description": "Whether to capture a screenshot of the page" }, "waitFor": { "type": "number", "description": "Milliseconds to wait before scraping (0 for immediate)" }, "replaceAllPathsWithAbsolutePaths": { "type": "boolean", "description": "Whether to convert relative URLs to absolute URLs in the result" }, "headers": { "type": "object", "properties": {}, "required": [], "description": "Custom HTTP request headers as key-value pairs" }, "removeTags": { "type": "array", "items": { "type": "string" }, "description": "HTML tags to remove from the scraped result" }, "mobile": { "type": "boolean", "description": "Whether to scrape using a mobile user-agent" } }, "required": ["onlyMainContent", "screenshot", "waitFor", "replaceAllPathsWithAbsolutePaths", "headers", "removeTags", "mobile"], "description": "Page-level scraping options (content filtering, screenshots, headers, etc.)" } }, "required": ["url"] },
-    outputSchema: { "type": "object", "properties": { "content": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown/plain-text content of the scraped page" }, "html": { "type": "string", "description": "Raw HTML content of the scraped page" }, "json": { "type": "object", "properties": {}, "required": [], "description": "Structured data extracted from the page" }, "screenshotUrl": { "type": "string", "description": "Screenshot URL of the page (if requested)" }, "metadata": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Page meta description" }, "url": { "type": "string", "description": "Canonical URL" }, "image": { "type": "string", "description": "Open Graph image URL" } }, "required": ["title", "description", "url", "image"], "description": "Page metadata (Open Graph / meta tags)" } }, "required": ["text", "html"] }, { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown/plain-text content of the scraped page" }, "html": { "type": "string", "description": "Raw HTML content of the scraped page" }, "json": { "type": "object", "properties": {}, "required": [], "description": "Structured data extracted from the page" }, "screenshotUrl": { "type": "string", "description": "Screenshot URL of the page (if requested)" }, "metadata": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Page meta description" }, "url": { "type": "string", "description": "Canonical URL" }, "image": { "type": "string", "description": "Open Graph image URL" } }, "required": ["title", "description", "url", "image"], "description": "Page metadata (Open Graph / meta tags)" } }, "required": ["text", "html"] } }] }, "screenshot": { "type": "string", "description": "Screenshot URL, only present when screenshot was requested via pageOptions" } }, "required": ["content"] }
+    outputSchema: { "type": "object", "properties": { "content": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown/plain-text content of the scraped page" }, "html": { "type": "string", "description": "Raw HTML content of the scraped page" }, "json": { "type": "object", "properties": {}, "required": [], "description": "Structured data extracted from the page" }, "screenshotUrl": { "type": "string", "description": "Screenshot URL of the page (if requested)" }, "metadata": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Page meta description" }, "url": { "type": "string", "description": "Canonical URL" }, "image": { "type": "string", "description": "Open Graph image URL" } }, "required": ["title", "description", "url", "image"], "description": "Page metadata (Open Graph / meta tags)" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "description": "Set when the scrape failed. `text`/`html` still carry the human-readable error so existing callers behave as before, but callers that care \u2014 billing, in particular \u2014 can tell a failure from real page content." } }, "required": ["text", "html"] }, { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown/plain-text content of the scraped page" }, "html": { "type": "string", "description": "Raw HTML content of the scraped page" }, "json": { "type": "object", "properties": {}, "required": [], "description": "Structured data extracted from the page" }, "screenshotUrl": { "type": "string", "description": "Screenshot URL of the page (if requested)" }, "metadata": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Page meta description" }, "url": { "type": "string", "description": "Canonical URL" }, "image": { "type": "string", "description": "Open Graph image URL" } }, "required": ["title", "description", "url", "image"], "description": "Page metadata (Open Graph / meta tags)" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "description": "Set when the scrape failed. `text`/`html` still carry the human-readable error so existing callers behave as before, but callers that care \u2014 billing, in particular \u2014 can tell a failure from real page content." } }, "required": ["text", "html"] } }] }, "screenshot": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] } }, "required": ["content"] }
   },
   "scrapeXPost": {
     stepType: "scrapeXPost",
     description: "Scrape data from a single X (Twitter) post by URL.",
     usageNotes: "- Returns structured post data (text, html, optional json/screenshot/metadata).\n- Optionally saves the text content to a variable.",
     inputSchema: { "type": "object", "properties": { "url": { "type": "string", "description": "Full URL to the X post (e.g. https://x.com/elonmusk/status/1655608985058267139)" } }, "required": ["url"] },
-    outputSchema: { "type": "object", "properties": { "post": { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown/plain-text content of the scraped page" }, "html": { "type": "string", "description": "Raw HTML content of the scraped page" }, "json": { "type": "object", "properties": {}, "required": [], "description": "Structured data extracted from the page" }, "screenshotUrl": { "type": "string", "description": "Screenshot URL of the page (if requested)" }, "metadata": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Page meta description" }, "url": { "type": "string", "description": "Canonical URL" }, "image": { "type": "string", "description": "Open Graph image URL" } }, "required": ["title", "description", "url", "image"], "description": "Page metadata (Open Graph / meta tags)" } }, "required": ["text", "html"], "description": "Scraped post data including text, HTML, and optional structured JSON" } }, "required": ["post"] }
+    outputSchema: { "type": "object", "properties": { "post": { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown/plain-text content of the scraped page" }, "html": { "type": "string", "description": "Raw HTML content of the scraped page" }, "json": { "type": "object", "properties": {}, "required": [], "description": "Structured data extracted from the page" }, "screenshotUrl": { "type": "string", "description": "Screenshot URL of the page (if requested)" }, "metadata": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Page meta description" }, "url": { "type": "string", "description": "Canonical URL" }, "image": { "type": "string", "description": "Open Graph image URL" } }, "required": ["title", "description", "url", "image"], "description": "Page metadata (Open Graph / meta tags)" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "description": "Set when the scrape failed. `text`/`html` still carry the human-readable error so existing callers behave as before, but callers that care \u2014 billing, in particular \u2014 can tell a failure from real page content." } }, "required": ["text", "html"], "description": "Scraped post data including text, HTML, and optional structured JSON" } }, "required": ["post"] }
   },
   "scrapeXProfile": {
     stepType: "scrapeXProfile",
     description: "Scrape public profile data from an X (Twitter) account by URL.",
     usageNotes: "- Returns structured profile data.\n- Optionally saves the result to a variable.",
     inputSchema: { "type": "object", "properties": { "url": { "type": "string", "description": "Full URL or username for the X profile (e.g. https://x.com/elonmusk)" } }, "required": ["url"] },
-    outputSchema: { "type": "object", "properties": { "profile": { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown/plain-text content of the scraped page" }, "html": { "type": "string", "description": "Raw HTML content of the scraped page" }, "json": { "type": "object", "properties": {}, "required": [], "description": "Structured data extracted from the page" }, "screenshotUrl": { "type": "string", "description": "Screenshot URL of the page (if requested)" }, "metadata": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Page meta description" }, "url": { "type": "string", "description": "Canonical URL" }, "image": { "type": "string", "description": "Open Graph image URL" } }, "required": ["title", "description", "url", "image"], "description": "Page metadata (Open Graph / meta tags)" } }, "required": ["text", "html"], "description": "Scraped profile data including text, HTML, and optional structured JSON" } }, "required": ["profile"] }
+    outputSchema: { "type": "object", "properties": { "profile": { "type": "object", "properties": { "text": { "type": "string", "description": "Markdown/plain-text content of the scraped page" }, "html": { "type": "string", "description": "Raw HTML content of the scraped page" }, "json": { "type": "object", "properties": {}, "required": [], "description": "Structured data extracted from the page" }, "screenshotUrl": { "type": "string", "description": "Screenshot URL of the page (if requested)" }, "metadata": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title" }, "description": { "type": "string", "description": "Page meta description" }, "url": { "type": "string", "description": "Canonical URL" }, "image": { "type": "string", "description": "Open Graph image URL" } }, "required": ["title", "description", "url", "image"], "description": "Page metadata (Open Graph / meta tags)" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "description": "Set when the scrape failed. `text`/`html` still carry the human-readable error so existing callers behave as before, but callers that care \u2014 billing, in particular \u2014 can tell a failure from real page content." } }, "required": ["text", "html"], "description": "Scraped profile data including text, HTML, and optional structured JSON" } }, "required": ["profile"] }
   },
   "screenshotUrl": {
     stepType: "screenshotUrl",
@@ -3178,6 +3178,13 @@ function resolveStepType(name) {
 }
 function mapTools(tools) {
   return tools.map((t) => {
+    if (typeof t === "object" && "appMethod" in t) {
+      return {
+        appMethod: t.appMethod,
+        ...t.description ? { description: t.description } : {},
+        ...t.defaults ? { defaults: t.defaults } : {}
+      };
+    }
     const method = typeof t === "string" ? t : t.method;
     const stepType = resolveStepType(method);
     const defaults = typeof t === "object" ? t.defaults : void 0;
@@ -4383,11 +4390,18 @@ var MindStudioAgent = class {
    * to produce structured output. The model receives the prompt and tools,
    * calls actions as needed, and returns JSON matching the output example.
    *
+   * Tools can be SDK actions, your own app's methods, or both. App methods run
+   * as the user who invoked the method that started the task, with their roles.
+   *
    * ```ts
    * const result = await agent.runTask<{ name: string; url: string }>({
-   *   prompt: 'Find canonical info for this restaurant.',
+   *   prompt: 'Find canonical info for this restaurant, then save it.',
    *   input: { restaurantName: 'Tartine Bakery SF' },
-   *   tools: ['searchGoogle', 'fetchUrl'],
+   *   tools: [
+   *     'searchGoogle',
+   *     'fetchUrl',
+   *     { appMethod: 'saveRestaurant', description: 'Persist the researched restaurant.' },
+   *   ],
    *   structuredOutputExample: JSON.stringify({ name: 'Tartine Bakery', url: 'https://tartinebakery.com' }),
    *   model: 'claude-4-6-sonnet',
    * });