@mindstudio-ai/agent 0.1.110 → 0.1.111

package/dist/index.d.ts

@@ -2238,6 +2238,15 @@ interface Citation {
 }
 /** A metadata value as stored on a document: scalars only. */
 type MetadataValue = string | number | boolean;
+/**
+ * Numeric range over a metadata value (inclusive both ends). Numbers only —
+ * to range on dates, store them as sortable integers at add time (epoch
+ * seconds or `20240315`-style YYYYMMDD) and range on those.
+ */
+interface MetadataRange {
+    gte?: number;
+    lte?: number;
+}
 /**
  * Tags attached to a document when it's added — department, year, doc type,
  * a per-user scope — and matched by {@link SearchFilter.metadata} at query
@@ -2261,10 +2270,11 @@ type SearchMode = 'hybrid' | 'semantic' | 'lexical';
 interface SearchFilter {
     /**
      * Match document metadata set at add time. A scalar must equal; an array
-     * matches any of its values. Keys AND together:
-     * `{ department: 'legal', year: [2025, 2026] }`.
+     * matches any of its values; `{ gte?, lte? }` matches a numeric range. Keys
+     * AND together:
+     * `{ department: 'legal', year: [2025, 2026], publishedAt: { gte: 20250101 } }`.
      */
-    metadata?: Record<string, MetadataValue | MetadataValue[]>;
+    metadata?: Record<string, MetadataValue | MetadataValue[] | MetadataRange>;
     /** Exact filename, or any of several. */
     filename?: string | string[];
     /** Restrict to specific documents (ids from {@link DataSource.documents}). */
@@ -2297,7 +2307,16 @@ interface SearchExplain {
     matchedVia: 'dense' | 'lexical' | 'both';
 }
 interface SearchHit {
-    /** Provider relevance score. Comparable within a response, not across them. */
+    /**
+     * Relevance of this hit. Comparable within a response, not across them —
+     * the scale depends on how the search ran (check {@link SearchRan}):
+     * cosine similarity in `semantic` mode, an RRF rank reciprocal in `hybrid`
+     * (small numbers that are not similarities), keyword-overlap weight in
+     * `lexical`. When reranking ran, it's the reranker's 0–1 relevance instead,
+     * with the retrieval value preserved as `retrievalScore` — so rerank-on
+     * `score` is the one scale that's stable across modes, and the right place
+     * for quality cutoffs.
+     */
     score: number;
     /** The matched chunk, prefixed with its heading path for context. */
     text: string;
@@ -2367,7 +2386,14 @@ interface SearchRan {
 interface SearchOptions {
     /** Results to return. Default 5, capped at 50. */
     topK?: number;
-    /** Drop hits below this score. Provider-specific scale — measure before using. */
+    /**
+     * Floor on the RETRIEVAL score — applied to the retrieval branch, never to
+     * the fused hybrid score or the reranker's score. In `semantic` and
+     * `hybrid` modes it's a cosine floor on the embedding branch; in `lexical`,
+     * a keyword-overlap floor. The scale depends on the embedding model, so
+     * measure before using — and with reranking on, prefer cutting on each
+     * hit's returned `score` (the reranker's 0–1 relevance) instead.
+     */
     scoreThreshold?: number;
     /**
      * Narrow the search to matching chunks before ranking — by document
@@ -2950,6 +2976,17 @@ interface EmailStats {
         counts: Record<string, number>;
     }>;
 }
+/**
+ * Lifecycle of a QUEUED send. Large and marketing sends are accepted
+ * immediately and delivered in the background, so a blast can legitimately be
+ * observed mid-flight:
+ *
+ * `accepted` — queued, nothing delivered yet. `sending` — delivery in
+ * progress. `completed` — every recipient was handed to the provider.
+ * `partial` — finished, but some recipients were not sent to. `failed` —
+ * finished and nothing was sent.
+ */
+type EmailBatchLifecycle = 'accepted' | 'sending' | 'completed' | 'partial' | 'failed';
 /**
  * One blast, aggregated.
  *
@@ -2963,6 +3000,17 @@ interface EmailBatch {
     recipients: number;
     accepted: number;
     counts: Record<EmailMessageStatus, number>;
+    /**
+     * Delivery lifecycle, when the send was QUEUED. `null` means the send was
+     * delivered inline (small transactional sends) and already finished — treat
+     * null as done, never as unknown.
+     */
+    status: EmailBatchLifecycle | null;
+    /** Delivery-chunk progress, when queued. Null otherwise. */
+    chunksTotal: number | null;
+    chunksDone: number | null;
+    /** Recipients not yet attempted, when queued. Null otherwise. */
+    pending: number | null;
 }
 interface EmailSuppression {
     id: string;
@@ -3129,10 +3177,16 @@ interface Email {
      * And a non-empty `suppressed` in the result is a **success**, not a failure: it
      * lists people who had unsubscribed and were therefore skipped.
      *
-     * Delivery is synchronous today: this resolves once the mail has been handed to
-     * the provider, so a large marketing list takes a while. Outcomes (delivered,
-     * bounced, complained) arrive later — read them with
-     * `email.messages({ batchId })`.
+     * Delivery is split from acceptance: small transactional sends deliver before
+     * this resolves; marketing and large sends are QUEUED — this resolves once the
+     * send is accepted, and delivery continues in the background. Track progress
+     * with `email.batch(batchId)` (`status`, `pending`, chunk counts); outcomes
+     * (delivered, bounced, complained) arrive later on `email.messages({ batchId })`.
+     *
+     * Throws `outbound_daily_cap_exceeded` (429) over the app's daily recipient
+     * quota — check `email.quota()` before a big send — and `sending_paused` (409)
+     * when the app's sending is paused for reputation or by support; a 409 will
+     * not succeed on retry.
      *
      * @example
      * ```ts
@@ -3184,7 +3238,7 @@ interface Email {
     }>;
     /** One message, including bounce diagnostics. */
     message(messageId: string): Promise<EmailMessage>;
-    /** One row per blast, newest first. */
+    /** One row per blast, newest first, with delivery lifecycle where queued. */
     batches(options?: EmailWindowOptions & {
         limit?: number;
         offset?: number;
@@ -3192,7 +3246,11 @@ interface Email {
         batches: EmailBatch[];
         total: number;
     }>;
-    /** Stats for a single blast — the id you passed to `sendEmail`, or the one it returned. */
+    /**
+     * Stats and delivery progress for a single blast — the id you passed to
+     * `email.send()`, or the one it returned. Poll this to watch a queued send
+     * drain (`status`, `pending`, chunk counts).
+     */
     batch(batchId: string): Promise<EmailBatch>;
     /** Your app's unsubscribe list, newest first. */
     suppressions(options?: {
@@ -7377,6 +7435,8 @@ interface SendEmailStepInput {
     references?: string[];
     /** `marketing` (default) adds one-click unsubscribe headers and skips recipients who unsubscribed from this app. Use `transactional` for receipts, alerts and password resets: no unsubscribe header, never suppressed, and cc/bcc preserved on a single message. */
     category?: "transactional" | "marketing";
+    /** Groups this send's per-recipient rows into one blast, so per-campaign stats are readable afterwards. Pass your own campaign id (1-64 printable chars) to join our delivery stats onto your own tables with no mapping; omit it and one is generated. Either way it comes back in the output. */
+    batchId?: string;
 }
 interface SendEmailStepOutput {
     /** To addresses the message was sent to. */
@@ -7389,6 +7449,8 @@ interface SendEmailStepOutput {
     from: string;
     /** Recipients skipped because they unsubscribed from this app. Always empty for a `transactional` send. */
     suppressed: string[];
+    /** Groups this send's per-recipient rows into one blast — the caller's `batchId` if supplied, otherwise a generated one. Returned unconditionally so an app can read per-blast stats back without having had to pass anything. */
+    batchId: string;
 }
 interface SendGmailDraftStepInput {
     /** Gmail draft ID to send */
@@ -10476,6 +10538,7 @@ interface StepMethods {
      * Send an email to one or more recipient addresses.
      *
      * @remarks
+     * - If you are writing a backend method for a v2 app, prefer mindstudio.email.send({...}) — it takes the same fields, returns the batchId you read stats back with, and sits alongside email.messages / email.batch / email.suppress. This action remains fully supported and runs the same code; it is also the only way to use connectionId or generateHtml.
      * - 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" — 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".
@@ -10496,7 +10559,7 @@ interface StepMethods {
      * - The special connectionId "trigger_email" uses the email address that triggered the workflow.
      * - Sends default to category "marketing": every message carries a one-click unsubscribe header pointing at the app's own domain, and recipients who previously unsubscribed from this app are skipped and returned in "suppressed". Because the unsubscribe link is per-recipient, a marketing send delivers one separate message per recipient and cc/bcc are folded into that list.
      * - Set category to "transactional" for receipts, alerts, password resets and anything a recipient must not be able to opt out of. Transactional sends carry no unsubscribe header, ignore the unsubscribe list, and keep cc/bcc on a single message — use it whenever cc/bcc semantics matter.
-     * - The subject is stored verbatim in the app's delivery log, which every workspace member can read for 90 days. Never put a secret in the subject — no one-time codes, no magic-link tokens, no password-reset tokens. Put those in the body, which is never stored.
+     * - The subject is stored verbatim in the app's delivery log, which every workspace member can read for 90 days. Never put a secret in the subject — no one-time codes, no magic-link tokens, no password-reset tokens. Put those in the body of a "transactional" send: a small transactional send is delivered immediately and its body is never stored. A "marketing" send, or any large send, is queued for delivery, which means its body is held in internal storage until the send finishes — so do not put a secret in the body of one of those either.
      *
      * @example
      * ```typescript

package/dist/index.js

@@ -4036,7 +4036,8 @@ var stepMetadata = {
   "sendEmail": {
     stepType: "sendEmail",
     description: "Send an email to one or more recipient addresses.",
-    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.)
+    usageNotes: `- If you are writing a backend method for a v2 app, prefer mindstudio.email.send({...}) \u2014 it takes the same fields, returns the batchId you read stats back with, and sits alongside email.messages / email.batch / email.suppress. This action remains fully supported and runs the same code; it is also the only way to use connectionId or generateHtml.
+- 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.
@@ -4056,9 +4057,9 @@ var stepMetadata = {
 - The special connectionId "trigger_email" uses the email address that triggered the workflow.
 - Sends default to category "marketing": every message carries a one-click unsubscribe header pointing at the app's own domain, and recipients who previously unsubscribed from this app are skipped and returned in "suppressed". Because the unsubscribe link is per-recipient, a marketing send delivers one separate message per recipient and cc/bcc are folded into that list.
 - Set category to "transactional" for receipts, alerts, password resets and anything a recipient must not be able to opt out of. Transactional sends carry no unsubscribe header, ignore the unsubscribe list, and keep cc/bcc on a single message \u2014 use it whenever cc/bcc semantics matter.
-- The subject is stored verbatim in the app's delivery log, which every workspace member can read for 90 days. Never put a secret in the subject \u2014 no one-time codes, no magic-link tokens, no password-reset tokens. Put those in the body, which is never stored.`,
-    inputSchema: { "type": "object", "properties": { "subject": { "type": "string", "description": "Email subject line" }, "body": { "type": "string", "description": "Email body content (plain text, markdown, HTML, or a CDN URL to an HTML file)" }, "to": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "cc": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "bcc": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "connectionId": { "type": "string", "description": "OAuth connection ID(s) for the recipient(s), comma-separated for multiple" }, "generateHtml": { "type": "boolean", "description": "When true, auto-convert the body text into a styled HTML email using AI" }, "generateHtmlInstructions": { "type": "string", "description": "Natural language instructions for the HTML generation style" }, "generateHtmlModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": 'Model identifier (e.g. "gpt-4", "claude-3-opus")' }, "temperature": { "type": "number", "description": "Sampling temperature for the model (0-2)" }, "maxResponseTokens": { "type": "number", "description": "Maximum number of tokens in the model's response" }, "ignorePreamble": { "type": "boolean", "description": "Whether to skip the system preamble/instructions" }, "userMessagePreprocessor": { "type": "object", "properties": { "dataSource": { "type": "string", "description": "Data source identifier for the preprocessor" }, "messageTemplate": { "type": "string", "description": "Template string applied to user messages before sending to the model" }, "maxResults": { "type": "number", "description": "Maximum number of results to include from the data source" }, "enabled": { "type": "boolean", "description": "Whether the preprocessor is active" }, "shouldInherit": { "type": "boolean", "description": "Whether child steps should inherit this preprocessor configuration" } }, "description": "Preprocessor applied to user messages before sending to the model" }, "preamble": { "type": "string", "description": "System preamble/instructions for the model" }, "multiModelEnabled": { "type": "boolean", "description": "Whether multi-model candidate generation is enabled" }, "editResponseEnabled": { "type": "boolean", "description": "Whether the user can edit the model's response" }, "config": { "type": "object", "properties": {}, "required": [], "description": "Additional model-specific configuration" } }, "required": ["model", "temperature", "maxResponseTokens"], "description": "Model settings override for HTML generation" }, "attachments": { "type": "array", "items": { "anyOf": [{ "type": "string" }, { "type": "object", "properties": { "url": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" } }, "required": ["url"] }] }, "description": "Files to attach: each entry is a URL string, or an object `{ url, filename?, contentType? }` to control the displayed filename and MIME type." }, "from": { "type": "string", "description": "Custom sender handle \u2014 only for apps with a custom domain or subdomain. Bare handle (`support`), full `support@your-domain.com`, or `Name <support@your-domain.com>`. Must resolve to a domain the app owns." }, "bodyType": { "enum": ["auto", "html", "markdown", "text"], "type": "string", "description": "How to interpret `body`: `auto` (default \u2014 detect HTML, else render markdown), `html` (send as-is), `markdown` (render to HTML), or `text` (send as plain text only, no HTML part). Every send includes a text/plain alternative." }, "text": { "type": "string", "description": "Explicit text/plain alternative body. Auto-derived from `body` if omitted." }, "replyTo": { "type": "string", "description": "Reply-To address for the email." }, "inReplyTo": { "type": "string", "description": "Message-ID this email replies to, for inbox threading (In-Reply-To header)." }, "references": { "type": "array", "items": { "type": "string" }, "description": "Prior Message-IDs in the thread, for inbox threading (References header)." }, "category": { "enum": ["transactional", "marketing"], "type": "string", "description": "`marketing` (default) adds one-click unsubscribe headers and skips recipients who unsubscribed from this app. Use `transactional` for receipts, alerts and password resets: no unsubscribe header, never suppressed, and cc/bcc preserved on a single message." } }, "required": ["subject", "body"] },
-    outputSchema: { "type": "object", "properties": { "recipients": { "type": "array", "items": { "type": "string" }, "description": "To addresses the message was sent to." }, "cc": { "type": "array", "items": { "type": "string" }, "description": "Cc addresses on the message (empty if none)." }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "Bcc addresses on the message (empty if none)." }, "from": { "type": "string", "description": "The resolved sender address the message went out as (auto-selected when no `from` is given)." }, "suppressed": { "type": "array", "items": { "type": "string" }, "description": "Recipients skipped because they unsubscribed from this app. Always empty for a `transactional` send." } }, "required": ["recipients", "cc", "bcc", "from", "suppressed"] }
+- The subject is stored verbatim in the app's delivery log, which every workspace member can read for 90 days. Never put a secret in the subject \u2014 no one-time codes, no magic-link tokens, no password-reset tokens. Put those in the body of a "transactional" send: a small transactional send is delivered immediately and its body is never stored. A "marketing" send, or any large send, is queued for delivery, which means its body is held in internal storage until the send finishes \u2014 so do not put a secret in the body of one of those either.`,
+    inputSchema: { "type": "object", "properties": { "subject": { "type": "string", "description": "Email subject line" }, "body": { "type": "string", "description": "Email body content (plain text, markdown, HTML, or a CDN URL to an HTML file)" }, "to": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "cc": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "bcc": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "connectionId": { "type": "string", "description": "OAuth connection ID(s) for the recipient(s), comma-separated for multiple" }, "generateHtml": { "type": "boolean", "description": "When true, auto-convert the body text into a styled HTML email using AI" }, "generateHtmlInstructions": { "type": "string", "description": "Natural language instructions for the HTML generation style" }, "generateHtmlModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": 'Model identifier (e.g. "gpt-4", "claude-3-opus")' }, "temperature": { "type": "number", "description": "Sampling temperature for the model (0-2)" }, "maxResponseTokens": { "type": "number", "description": "Maximum number of tokens in the model's response" }, "ignorePreamble": { "type": "boolean", "description": "Whether to skip the system preamble/instructions" }, "userMessagePreprocessor": { "type": "object", "properties": { "dataSource": { "type": "string", "description": "Data source identifier for the preprocessor" }, "messageTemplate": { "type": "string", "description": "Template string applied to user messages before sending to the model" }, "maxResults": { "type": "number", "description": "Maximum number of results to include from the data source" }, "enabled": { "type": "boolean", "description": "Whether the preprocessor is active" }, "shouldInherit": { "type": "boolean", "description": "Whether child steps should inherit this preprocessor configuration" } }, "description": "Preprocessor applied to user messages before sending to the model" }, "preamble": { "type": "string", "description": "System preamble/instructions for the model" }, "multiModelEnabled": { "type": "boolean", "description": "Whether multi-model candidate generation is enabled" }, "editResponseEnabled": { "type": "boolean", "description": "Whether the user can edit the model's response" }, "config": { "type": "object", "properties": {}, "required": [], "description": "Additional model-specific configuration" } }, "required": ["model", "temperature", "maxResponseTokens"], "description": "Model settings override for HTML generation" }, "attachments": { "type": "array", "items": { "anyOf": [{ "type": "string" }, { "type": "object", "properties": { "url": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" } }, "required": ["url"] }] }, "description": "Files to attach: each entry is a URL string, or an object `{ url, filename?, contentType? }` to control the displayed filename and MIME type." }, "from": { "type": "string", "description": "Custom sender handle \u2014 only for apps with a custom domain or subdomain. Bare handle (`support`), full `support@your-domain.com`, or `Name <support@your-domain.com>`. Must resolve to a domain the app owns." }, "bodyType": { "enum": ["auto", "html", "markdown", "text"], "type": "string", "description": "How to interpret `body`: `auto` (default \u2014 detect HTML, else render markdown), `html` (send as-is), `markdown` (render to HTML), or `text` (send as plain text only, no HTML part). Every send includes a text/plain alternative." }, "text": { "type": "string", "description": "Explicit text/plain alternative body. Auto-derived from `body` if omitted." }, "replyTo": { "type": "string", "description": "Reply-To address for the email." }, "inReplyTo": { "type": "string", "description": "Message-ID this email replies to, for inbox threading (In-Reply-To header)." }, "references": { "type": "array", "items": { "type": "string" }, "description": "Prior Message-IDs in the thread, for inbox threading (References header)." }, "category": { "enum": ["transactional", "marketing"], "type": "string", "description": "`marketing` (default) adds one-click unsubscribe headers and skips recipients who unsubscribed from this app. Use `transactional` for receipts, alerts and password resets: no unsubscribe header, never suppressed, and cc/bcc preserved on a single message." }, "batchId": { "type": "string", "description": "Groups this send's per-recipient rows into one blast, so per-campaign stats are readable afterwards. Pass your own campaign id (1-64 printable chars) to join our delivery stats onto your own tables with no mapping; omit it and one is generated. Either way it comes back in the output." } }, "required": ["subject", "body"] },
+    outputSchema: { "type": "object", "properties": { "recipients": { "type": "array", "items": { "type": "string" }, "description": "To addresses the message was sent to." }, "cc": { "type": "array", "items": { "type": "string" }, "description": "Cc addresses on the message (empty if none)." }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "Bcc addresses on the message (empty if none)." }, "from": { "type": "string", "description": "The resolved sender address the message went out as (auto-selected when no `from` is given)." }, "suppressed": { "type": "array", "items": { "type": "string" }, "description": "Recipients skipped because they unsubscribed from this app. Always empty for a `transactional` send." }, "batchId": { "type": "string", "description": "Groups this send's per-recipient rows into one blast \u2014 the caller's `batchId` if supplied, otherwise a generated one. Returned unconditionally so an app can read per-blast stats back without having had to pass anything." } }, "required": ["recipients", "cc", "bcc", "from", "suppressed", "batchId"] }
   },
   "sendGmailDraft": {
     stepType: "sendGmailDraft",
@@ -7817,7 +7818,7 @@ var monacoSnippets = {
   "searchXPosts": { fields: [["query", "string"], ["scope", ["recent", "all"]], ["options", "object"]], outputKeys: ["posts"] },
   "searchYoutube": { fields: [["query", "string"], ["limitPages", "string"], ["filter", "string"], ["filterType", "string"]], outputKeys: ["results"] },
   "searchYoutubeTrends": { fields: [["bp", ["now", "music", "gaming", "films"]], ["hl", "string"], ["gl", "string"]], outputKeys: [] },
-  "sendEmail": { fields: [["subject", "string"], ["body", "string"]], outputKeys: ["recipients", "cc", "bcc", "from", "suppressed"] },
+  "sendEmail": { fields: [["subject", "string"], ["body", "string"]], outputKeys: ["recipients", "cc", "bcc", "from", "suppressed", "batchId"] },
   "sendGmailDraft": { fields: [["draftId", "string"]], outputKeys: [] },
   "sendGmailMessage": { fields: [["to", "string"], ["subject", "string"], ["message", "string"], ["messageType", ["plain", "html", "markdown"]]], outputKeys: ["messageId"] },
   "sendSlackDirectMessage": { fields: [["slackUserId", "string"], ["messageType", ["string", "blocks"]], ["message", "string"]], outputKeys: [] },