@mindstudio-ai/agent 0.1.81 → 0.1.83

package/dist/index.js

@@ -1924,6 +1924,173 @@ function resolveTable(databases, tableName, databaseHint) {
   );
 }
 
+// src/files/store.ts
+import { createHash, randomUUID } from "crypto";
+function toBase64(content) {
+  return Buffer.from(
+    typeof content === "string" ? Buffer.from(content) : content
+  ).toString("base64");
+}
+function extensionFor(filename) {
+  if (!filename) {
+    return "";
+  }
+  const dot = filename.lastIndexOf(".");
+  return dot > 0 ? filename.slice(dot) : "";
+}
+var Store = class {
+  constructor(_store, _access, _call, _policy = {}) {
+    this._store = _store;
+    this._access = _access;
+    this._call = _call;
+    this._policy = _policy;
+  }
+  /** The store's access level. */
+  get access() {
+    return this._access;
+  }
+  /** Store bytes. Returns a {@link StoredFile} with a ready-to-use `url`. */
+  async put(content, options) {
+    const ext = extensionFor(options?.filename);
+    const key = options?.key ?? (options?.contentAddressed ? `${createHash("sha256").update(content).digest("hex")}${ext}` : `${randomUUID()}${ext}`);
+    const meta = await this._call("put", {
+      store: this._store,
+      access: this._access,
+      key,
+      body: toBase64(content),
+      ...options?.contentType ? { contentType: options.contentType } : {}
+    });
+    return this._toFile(key, meta);
+  }
+  /** Read an object's bytes (backend / trusted context). */
+  async get(key) {
+    const res = await this._call("get", {
+      store: this._store,
+      access: this._access,
+      key
+    });
+    return Buffer.from(res.body, "base64");
+  }
+  /** Metadata without downloading. Rejects if the object doesn't exist. */
+  async head(key) {
+    const meta = await this._call("head", {
+      store: this._store,
+      access: this._access,
+      key
+    });
+    return this._toFile(key, meta);
+  }
+  /** Whether an object exists. */
+  async exists(key) {
+    try {
+      await this.head(key);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /** List objects in the store (optionally under `prefix`), one page at a time. */
+  async list(options) {
+    const res = await this._call("list", {
+      store: this._store,
+      access: this._access,
+      ...options?.prefix ? { prefix: options.prefix } : {},
+      ...options?.cursor ? { cursor: options.cursor } : {},
+      ...options?.limit ? { limit: options.limit } : {}
+    });
+    return {
+      files: (res.files ?? []).map((f) => this._toFile(f.key, f)),
+      ...res.cursor ? { cursor: res.cursor } : {}
+    };
+  }
+  /** Delete an object. No-op if it doesn't exist. */
+  async delete(key) {
+    await this._call("delete", {
+      store: this._store,
+      access: this._access,
+      key
+    });
+  }
+  /**
+   * Mint an {@link UploadToken} for a **client-direct** upload — the browser
+   * POSTs the file straight to storage, so the bytes never pass through the
+   * platform. Return the token from a backend method and hand it to the
+   * frontend's `platform.upload(token, file)`. Works for private + public stores.
+   *
+   * Enforced at upload time by the presigned POST: a max size (this call's
+   * `maxSize`, else the store's, else the platform default) and — when
+   * `contentType` is set — an exact content-type match. When the store declares
+   * `contentTypes`, `contentType` must be one of them.
+   *
+   * @example
+   * ```ts
+   * // backend method
+   * export async function getUploadSlot(input: { contentType: string }) {
+   *   return Uploads.createUploadToken({ contentType: input.contentType, maxSize: 50 * 1024 * 1024 });
+   * }
+   * ```
+   */
+  async createUploadToken(options) {
+    if (options?.contentType && this._policy.contentTypes && !this._policy.contentTypes.includes(options.contentType)) {
+      throw new MindStudioError(
+        `contentType "${options.contentType}" is not allowed by store "${this._store}".`,
+        "content_type_not_allowed",
+        400
+      );
+    }
+    const key = options?.key ?? `${randomUUID()}${extensionFor(options?.filename)}`;
+    const maxSize = options?.maxSize ?? this._policy.maxSize;
+    const res = await this._call("create-upload", {
+      store: this._store,
+      access: this._access,
+      key,
+      ...options?.contentType ? { contentType: options.contentType } : {},
+      ...maxSize ? { maxSize } : {},
+      ...options?.expiresIn ? { expiresIn: options.expiresIn } : {}
+    });
+    return {
+      key,
+      url: `/_/files/${this._access}/${this._store}/${key}`,
+      upload: { url: res.uploadUrl, fields: res.uploadFields }
+    };
+  }
+  _toFile(key, meta) {
+    const store = this._store;
+    const access = this._access;
+    const call = this._call;
+    return {
+      store,
+      key,
+      access,
+      url: `/_/files/${access}/${store}/${key}`,
+      ...typeof meta?.size === "number" ? { size: meta.size } : {},
+      ...meta?.contentType ? { contentType: meta.contentType } : {},
+      ...meta?.updatedAt ? { updatedAt: meta.updatedAt } : {},
+      async shareUrl(options) {
+        const res = await call("sign", {
+          store,
+          access,
+          key,
+          ...options?.expiresIn ? { expiresIn: options.expiresIn } : {}
+        });
+        return res.url;
+      }
+    };
+  }
+};
+
+// src/files/index.ts
+function createFiles(call) {
+  return {
+    defineStore(name, options) {
+      return new Store(name, options?.access ?? "private", call, {
+        ...options?.maxSize !== void 0 ? { maxSize: options.maxSize } : {},
+        ...options?.contentTypes ? { contentTypes: options.contentTypes } : {}
+      });
+    }
+  };
+}
+
 // src/generated/metadata.ts
 var stepMetadata = {
   "activeCampaignAddNote": {
@@ -2785,21 +2952,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",
@@ -2891,6 +3058,9 @@ var stepMetadata = {
     usageNotes: `- Use the "to" field to send to one or more specific recipient email addresses directly. Allowed recipients depend on the sender: when the app sends from a domain it owns (a verified custom domain or its <slug>.madewithremy.com subdomain) any recipient is allowed; when it falls back to the shared Remy address, recipients must be verified app users or members of the app's organization. (v1 apps cannot use a direct "to" \u2014 they must resolve recipients via a connection.)
 - Alternatively, recipient email addresses can be resolved from OAuth connections configured by the app creator via connectionId. The user running the workflow does not specify the recipient directly.
 - Use "cc" and "bcc" to add visible / hidden recipients (a string or an array). They are subject to the same recipient rules as "to".
+- "to" is optional only in the sense that recipients can come from elsewhere \u2014 omit it and supply "cc"/"bcc" for a hidden-list send, or omit all three and recipients are resolved from an OAuth connection. Naming nobody at all is an error.
+- Bcc-only sends are supported: with no "to" or "cc", the To: header is addressed to the app's own sender address (the standard "undisclosed recipients" pattern) so recipients can't see each other. The returned "recipients" reflects that auto-filled address.
+- Every recipient counts toward the app's daily outbound cap, including cc and bcc.
 - The sender defaults automatically: v2 apps send from the app's own identity \u2014 its verified custom domain if set, else its platform subdomain (noreply@<slug>.madewithremy.com), else the default Remy address.
 - Optionally set "from" to a custom handle, but ONLY if the app has a custom domain or subdomain: a bare handle ("support" \u2192 support@<app-domain>), a full "support@your-domain.com", or "Name <support@your-domain.com>". The domain must be one the app owns, or the step fails.
 - If the body is a URL to a hosted HTML file on the CDN, the HTML is fetched and used as the email body.
@@ -3178,6 +3348,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;
@@ -3926,6 +4103,8 @@ var MindStudioAgent = class {
   _auth;
   /** @internal Cached Db namespace instance, created during context hydration. */
   _db;
+  /** @internal Cached Files namespace instance (lazy; no context hydration needed). */
+  _files;
   /** @internal Auth type — 'internal' for CALLBACK_TOKEN (managed mode), 'apiKey' otherwise. */
   _authType;
   /** @internal Usage source sent on step executions (from MINDSTUDIO_REQUEST_SOURCE).
@@ -4383,11 +4562,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',
    * });
@@ -4795,6 +4981,54 @@ var MindStudioAgent = class {
       });
     }
   }
+  /**
+   * The `files` namespace — typed, private-by-default file storage (the twin of
+   * `db`). No context hydration needed: the hook token identifies the app
+   * server-side and stores are code-defined (access travels per call).
+   *
+   * @example
+   * ```ts
+   * const Uploads = agent.files.defineStore('uploads');
+   * const f = await Uploads.put(buffer, { contentType: 'image/png' });
+   * return { url: f.url };
+   * ```
+   */
+  get files() {
+    return this._files ??= createFiles(this._filesRequest.bind(this));
+  }
+  /**
+   * @internal Transport for the `files` namespace — POST /_internal/v2/files/<op>
+   * with the raw hook token (mirrors `_executeDbBatch`).
+   */
+  async _filesRequest(op, body) {
+    const url = `${this._currentHttpConfig.baseUrl}/_internal/v2/files/${op}`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: this._token
+      },
+      body: JSON.stringify(body)
+    });
+    if (res.status === 204) {
+      return void 0;
+    }
+    const text = await res.text();
+    let json;
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+      }
+    }
+    if (!res.ok) {
+      const rawMsg = json?.errorMessage ?? (typeof json?.error === "string" ? json.error : json?.error?.message);
+      const message = typeof rawMsg === "string" ? rawMsg : `File operation failed: ${res.status} ${res.statusText}`;
+      const code = json?.errorString ?? json?.code ?? "file_error";
+      throw new MindStudioError(message, code, res.status);
+    }
+    return json;
+  }
   /**
    * @internal Execute a batch of SQL queries against a managed database.
    * Used as the `executeBatch` callback for Table/Query instances.
@@ -5461,6 +5695,16 @@ var db = new Proxy(
     }
   }
 );
+var files = new Proxy(
+  {},
+  {
+    get(_, prop) {
+      const target = mindstudio.files;
+      const value = Reflect.get(target, prop, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  }
+);
 var stream = (data) => mindstudio.stream(data);
 var resolveUser = (userId) => mindstudio.resolveUser(userId);
 var reportIssue = (input) => mindstudio.reportIssue(input);
@@ -5476,6 +5720,7 @@ export {
   blockTypeAliases,
   db,
   index_default as default,
+  files,
   getRequestContext,
   mindstudio,
   monacoSnippets,