@mindstudio-ai/agent 0.1.105 → 0.1.107

package/dist/index.d.ts

@@ -2811,6 +2811,15 @@ interface CrawlerHit {
 interface Analytics {
     /** The general read: metrics × dimensions × filters × time. */
     query(spec: AnalyticsQuerySpec): Promise<AnalyticsQueryResponse>;
+    /**
+     * Up to 10 queries in one round trip, results in request order — the right
+     * shape for a page composed of several reads (KPIs + timeseries + a few
+     * breakdowns), instead of a parallel burst of `query()` calls competing
+     * with each other against the per-app rate limit. Each query in the batch
+     * counts as one read against the limit. One invalid query fails the whole
+     * batch (the error names its index).
+     */
+    batch(specs: AnalyticsQuerySpec[]): Promise<AnalyticsQueryResponse[]>;
     /** Who's on the app right now (Redis presence, no time window). */
     live(): Promise<LiveNow>;
     /**
@@ -2963,9 +2972,12 @@ interface SchemaValidationError {
  * - `{ method }`: SDK method name with default input overrides.
  * - `{ appMethod }`: one of your own app's methods, called as the invoking
  *   user with their roles.
+ * - `{ name, execute }`: an inline function tool, executed right here in your
+ *   process. No platform dispatch, no billing — just your code.
  *
  * 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.
+ * Function tools take no defaults: close over what you need instead.
  */
 type TaskToolConfig = string | {
     method: string;
@@ -2980,6 +2992,22 @@ type TaskToolConfig = string | {
      */
     description?: string;
     defaults?: Record<string, unknown>;
+} | {
+    /** Tool name the model sees. Letters, digits, `_`, `-`; max 64 chars. */
+    name: string;
+    /** What the tool does and when to reach for it — all the model gets. */
+    description: string;
+    /** JSON Schema for the input (tool-definition dialect). Omitted means
+     *  the tool takes no arguments. */
+    inputSchema?: JsonObjectSchema;
+    /**
+     * Runs in this process when the model calls the tool. A thrown error is
+     * fed back to the model as `{ error }` tool output to work around — it
+     * never fails the task. Note: calling `runTask` from inside a function
+     * tool is not depth-capped (the server cap rides the method's token,
+     * which a function tool reuses) — recursion is yours to bound.
+     */
+    execute: (input: Record<string, unknown>) => Promise<unknown> | unknown;
 };
 /** Options shared by both output modes of {@link MindStudioAgent.runTask}. */
 interface RunTaskOptionsBase {
@@ -2987,7 +3015,8 @@ interface RunTaskOptionsBase {
     prompt: string;
     /** Structured input for this task instance. Passed as the user message. */
     input: Record<string, unknown>;
-    /** SDK actions and/or app methods to make available as tools. */
+    /** SDK actions, app methods, and/or inline function tools to make
+     *  available to the model. */
     tools: TaskToolConfig[];
     /**
      * Model ID for the task agent. Must support tool use. Tuned model lines
@@ -3205,8 +3234,12 @@ declare class MindStudioAgent$1 {
      * to produce structured output. The model receives the prompt and tools,
      * calls actions as needed, and returns structured JSON.
      *
-     * 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.
+     * Tools can be SDK actions, your own app's methods, and/or inline functions
+     * defined right in your code, in any combination. App methods run as the
+     * user who invoked the method that started the task, with their roles.
+     * Function tools run in this process — a thrown error is fed back to the
+     * model as tool output, and there are no `defaults` (close over what you
+     * need instead).
      *
      * Prefer `outputSchema` (plain JSON Schema, tool-definition dialect):
      * output is validated every turn with automatic repair, `result.output` is
@@ -3222,6 +3255,12 @@ declare class MindStudioAgent$1 {
      *     'searchGoogle',
      *     'fetchUrl',
      *     { appMethod: 'saveRestaurant', description: 'Persist the researched restaurant.' },
+     *     {
+     *       name: 'checkExisting',
+     *       description: 'Look up whether we already track this restaurant.',
+     *       inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+     *       execute: async (input) => Restaurants.findByName(String(input.name)),
+     *     },
      *   ],
      *   outputSchema: {
      *     type: 'object',
@@ -3534,6 +3573,12 @@ declare class MindStudioAgent$1 {
     /**
      * @internal Transport for the `analytics` namespace —
      * POST /_internal/v2/analytics/<op> with the raw hook token.
+     *
+     * Retries a single 429 after a short jittered backoff: analytics reads are
+     * idempotent and a 429 means the read never executed, so one retry lets a
+     * momentary burst (a page's fan-out racing a live poller) self-heal instead
+     * of surfacing as empty data. Deliberately single-shot and scoped to this
+     * namespace — the other brokered transports keep their semantics.
      */
     private _analyticsRequest;
     /**
@@ -10058,6 +10103,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.
      *
      * @example
      * ```typescript

package/dist/index.js

@@ -2784,6 +2784,10 @@ function createAnalytics(call) {
     query(spec) {
       return call("query", spec);
     },
+    async batch(specs) {
+      const res = await call("query-batch", { queries: specs });
+      return res.results;
+    },
     live() {
       return call("live", {});
     },
@@ -3793,7 +3797,8 @@ var stepMetadata = {
 - connectionId can be a comma-separated list to send to multiple recipients.
 - 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.`,
+- 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"] }
   },
@@ -4241,6 +4246,13 @@ function resolveStepType(name) {
 }
 function mapTools(tools) {
   return tools.map((t) => {
+    if (typeof t === "object" && "execute" in t) {
+      return {
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema ?? { type: "object", properties: {} }
+      };
+    }
     if (typeof t === "object" && "appMethod" in t) {
       return {
         appMethod: t.appMethod,
@@ -4686,10 +4698,18 @@ ${structuredOutputExample}
   const wireTools = mapTools(options.tools);
   const toolKinds = /* @__PURE__ */ new Map();
   const toolDefaults = /* @__PURE__ */ new Map();
+  const functionTools = /* @__PURE__ */ new Map();
+  for (const t of options.tools) {
+    if (typeof t === "object" && "execute" in t) {
+      functionTools.set(t.name, t.execute);
+    }
+  }
   for (const t of wireTools) {
     if ("appMethod" in t) {
       toolKinds.set(t.appMethod, "method");
       if (t.defaults) toolDefaults.set(t.appMethod, t.defaults);
+    } else if ("name" in t) {
+      toolKinds.set(t.name, "function");
     } else {
       toolKinds.set(t.stepType, "step");
       if (t.defaults) toolDefaults.set(t.stepType, t.defaults);
@@ -4818,8 +4838,27 @@ ${structuredOutputExample}
           const startTime = Date.now();
           const defaults = toolDefaults.get(toolCall.name) || {};
           const mergedInput = mergeToolInput(toolCall.input, defaults);
-          const execute = toolKinds.get(toolCall.name) === "method" ? deps.executeMethodTool : deps.executeStepTool;
-          const result = await execute(toolCall.name, mergedInput);
+          const kind = toolKinds.get(toolCall.name);
+          let result;
+          if (kind === "function") {
+            try {
+              const output3 = await functionTools.get(toolCall.name)(
+                mergedInput
+              );
+              result = { output: output3 ?? null, billingCost: 0, isError: false };
+            } catch (err) {
+              result = {
+                output: {
+                  error: err instanceof Error ? err.message : "Function tool execution failed"
+                },
+                billingCost: 0,
+                isError: true
+              };
+            }
+          } else {
+            const execute = kind === "method" ? deps.executeMethodTool : deps.executeStepTool;
+            result = await execute(toolCall.name, mergedInput);
+          }
           toolCallLog.push({
             name: toolCall.name,
             success: !result.isError,
@@ -6070,6 +6109,13 @@ var MindStudioAgent = class {
       );
     } catch (err) {
       if (err instanceof MindStudioError && err.code === TURN_UNAVAILABLE_CODE) {
+        if (options.tools.some((t) => typeof t === "object" && "execute" in t)) {
+          throw new MindStudioError(
+            "[task] This server does not support the per-turn task endpoint required for function tools.",
+            "task_function_tools_unsupported",
+            404
+          );
+        }
         const body = buildTaskRequestBody(options);
         const result = options.onEvent ? await runTaskStream(httpConfig, body, options.onEvent) : await runTaskPoll(httpConfig, body);
         if (options.outputSchema) {
@@ -6655,12 +6701,29 @@ var MindStudioAgent = class {
   /**
    * @internal Transport for the `analytics` namespace —
    * POST /_internal/v2/analytics/<op> with the raw hook token.
+   *
+   * Retries a single 429 after a short jittered backoff: analytics reads are
+   * idempotent and a 429 means the read never executed, so one retry lets a
+   * momentary burst (a page's fan-out racing a live poller) self-heal instead
+   * of surfacing as empty data. Deliberately single-shot and scoped to this
+   * namespace — the other brokered transports keep their semantics.
    */
   async _analyticsRequest(op, body) {
-    return this._brokeredRequest("analytics", op, body, {
+    const call = () => this._brokeredRequest("analytics", op, body, {
       fallbackMessage: "Analytics read failed",
       fallbackCode: "analytics_error"
     });
+    try {
+      return await call();
+    } catch (err) {
+      if (err instanceof MindStudioError && err.status === 429) {
+        await new Promise(
+          (resolve) => setTimeout(resolve, 750 + Math.random() * 750)
+        );
+        return call();
+      }
+      throw err;
+    }
   }
   /**
    * @internal Shared shape for the brokered `/_internal/v2/<ns>/<op>` data