@mindstudio-ai/agent 0.1.106 → 0.1.108

package/dist/index.js

@@ -102,9 +102,12 @@ function runWithContext(ctx, fn) {
 }
 
 // src/db-ws.ts
-var WS_REQUEST_TIMEOUT_MS = 3e5;
+var DB_WS_SUBPROTOCOL = "ms-db-v2";
+var WS_ACK_TIMEOUT_MS = 2e4;
+var WS_IDLE_TIMEOUT_MS = 3e5;
 var WS_OPEN_TIMEOUT_MS = 5e3;
 var WS_OPEN = 1;
+var WS_CHUNK_CHARS = 256 * 1024;
 var WS_MAX_FRAME_CHARS = 9e5;
 var DbWsTransportError = class extends Error {
   constructor(message, sent = false) {
@@ -117,13 +120,86 @@ function isReadOnlySql(sql) {
   const head = sql.trimStart().slice(0, 8).toUpperCase();
   return head.startsWith("SELECT") || head.startsWith("PRAGMA") || head.startsWith("EXPLAIN");
 }
-var socket = null;
+var conn = null;
 var opening = null;
 var idCounter = 0;
-var pending = /* @__PURE__ */ new Map();
-function getOrOpen(url) {
-  if (socket && socket.readyState === WS_OPEN) {
-    return Promise.resolve(socket);
+function clearPendingTimer(p) {
+  if (p.timer !== null) {
+    clearTimeout(p.timer);
+    p.timer = null;
+  }
+}
+function forget(self, id) {
+  self.pending.delete(id);
+  self.inbound.delete(id);
+  if (self.retired && self.pending.size === 0) {
+    try {
+      self.ws.close();
+    } catch {
+    }
+  }
+}
+function retire(self, reason) {
+  if (self.retired) {
+    return;
+  }
+  self.retired = true;
+  if (conn === self) {
+    conn = null;
+  }
+  try {
+    console.warn(
+      `[mindstudio] db: retiring WebSocket after ${reason}; next query reconnects.`
+    );
+  } catch {
+  }
+  if (self.pending.size === 0) {
+    try {
+      self.ws.close();
+    } catch {
+    }
+  }
+}
+function armIdleTimer(self, id, p) {
+  clearPendingTimer(p);
+  p.timer = setTimeout(() => {
+    forget(self, id);
+    retire(self, "a reply went silent");
+    p.reject(new DbWsTransportError("ws reply went silent", true));
+  }, WS_IDLE_TIMEOUT_MS);
+}
+function deliver(self, msg) {
+  const p = self.pending.get(msg.id);
+  if (!p) {
+    return;
+  }
+  clearPendingTimer(p);
+  forget(self, msg.id);
+  if (msg.error) {
+    p.reject(
+      new MindStudioError(
+        `[db] ${msg.error.message || "Database query failed"}`,
+        msg.error.code || "db_query_error",
+        400,
+        msg.error
+      )
+    );
+  } else {
+    p.resolve(msg.results);
+  }
+}
+function failTransport(self, id, err) {
+  const p = self.pending.get(id);
+  if (!p) {
+    return;
+  }
+  clearPendingTimer(p);
+  forget(self, id);
+  p.reject(err);
+}
+function getOrOpen(url, token) {
+  if (conn && !conn.retired && conn.ws.readyState === WS_OPEN) {
+    return Promise.resolve(conn);
   }
   if (opening) {
     return opening;
@@ -136,17 +212,22 @@ function getOrOpen(url) {
   }
   opening = new Promise((resolve, reject) => {
     let ws;
+    let self = null;
     const fail = (err) => {
       clearTimeout(openTimer);
-      if (socket === ws) {
-        socket = null;
+      if (self) {
+        self.retired = true;
+        if (conn === self) {
+          conn = null;
+        }
+        for (const [, p] of self.pending) {
+          clearPendingTimer(p);
+          p.reject(new DbWsTransportError(err.message, true));
+        }
+        self.pending.clear();
+        self.inbound.clear();
       }
       opening = null;
-      for (const [, p] of pending) {
-        clearTimeout(p.timer);
-        p.reject(new DbWsTransportError(err.message, true));
-      }
-      pending.clear();
       reject(err);
     };
     const openTimer = setTimeout(() => {
@@ -157,16 +238,26 @@ function getOrOpen(url) {
       fail(new DbWsTransportError("ws open timed out"));
     }, WS_OPEN_TIMEOUT_MS);
     try {
-      ws = new WebSocketCtor(url);
+      ws = new WebSocketCtor(url, ["auth", token, DB_WS_SUBPROTOCOL]);
     } catch (err) {
       fail(new DbWsTransportError(err?.message || "ws construct failed"));
       return;
     }
+    self = {
+      ws,
+      pending: /* @__PURE__ */ new Map(),
+      chunked: false,
+      inbound: /* @__PURE__ */ new Map(),
+      acksSeen: false,
+      retired: false
+    };
+    const c = self;
     ws.onopen = () => {
       clearTimeout(openTimer);
-      socket = ws;
+      c.chunked = ws.protocol === DB_WS_SUBPROTOCOL;
+      conn = c;
       opening = null;
-      resolve(ws);
+      resolve(c);
     };
     ws.onmessage = (ev) => {
       let msg;
@@ -177,26 +268,54 @@ function getOrOpen(url) {
       } catch {
         return;
       }
-      if (!msg || msg.t !== "db-result" || msg.id == null) {
+      if (!msg || msg.id == null) {
+        return;
+      }
+      if (msg.t === "db-ack") {
+        c.acksSeen = true;
+        const p = c.pending.get(msg.id);
+        if (p && !p.acked) {
+          p.acked = true;
+          armIdleTimer(c, msg.id, p);
+        }
         return;
       }
-      const p = pending.get(msg.id);
-      if (!p) {
+      if (msg.t === "db-chunk") {
+        const p = c.pending.get(msg.id);
+        if (!p || typeof msg.data !== "string") {
+          return;
+        }
+        const parts = c.inbound.get(msg.id);
+        if (parts) {
+          parts.push(msg.data);
+        } else {
+          c.inbound.set(msg.id, [msg.data]);
+        }
+        armIdleTimer(c, msg.id, p);
         return;
       }
-      clearTimeout(p.timer);
-      pending.delete(msg.id);
-      if (msg.error) {
-        p.reject(
-          new MindStudioError(
-            `[db] ${msg.error.message || "Database query failed"}`,
-            msg.error.code || "db_query_error",
-            400,
-            msg.error
-          )
-        );
-      } else {
-        p.resolve(msg.results);
+      if (msg.t === "db-end") {
+        const parts = c.inbound.get(msg.id);
+        if (!parts) {
+          return;
+        }
+        c.inbound.delete(msg.id);
+        let assembled;
+        try {
+          assembled = JSON.parse(parts.join(""));
+        } catch {
+          failTransport(
+            c,
+            msg.id,
+            new DbWsTransportError("chunked reply did not parse", true)
+          );
+          return;
+        }
+        deliver(c, assembled);
+        return;
+      }
+      if (msg.t === "db-result") {
+        deliver(c, msg);
       }
     };
     ws.onerror = () => fail(new DbWsTransportError("ws error"));
@@ -204,28 +323,59 @@ function getOrOpen(url) {
   });
   return opening;
 }
+function* outboundFrames(id, json) {
+  if (json.length <= WS_CHUNK_CHARS) {
+    yield json;
+    return;
+  }
+  let seq = 0;
+  for (let offset = 0; offset < json.length; offset += WS_CHUNK_CHARS) {
+    yield JSON.stringify({
+      t: "db-chunk",
+      id,
+      seq: seq++,
+      data: json.slice(offset, offset + WS_CHUNK_CHARS)
+    });
+  }
+  yield JSON.stringify({ t: "db-end", id });
+}
 async function executeDbBatchOverWs(url, token, databaseId, queries) {
   const id = ++idCounter;
   const frame = JSON.stringify({ t: "db", id, token, databaseId, queries });
-  if (frame.length > WS_MAX_FRAME_CHARS) {
+  const self = await getOrOpen(url, token);
+  if (!self.chunked && frame.length > WS_MAX_FRAME_CHARS) {
     throw new DbWsTransportError("payload too large for ws");
   }
-  const ws = await getOrOpen(url);
   return await new Promise((resolve, reject) => {
-    const timer = setTimeout(() => {
-      pending.delete(id);
-      reject(new DbWsTransportError("ws execute timed out", true));
-    }, WS_REQUEST_TIMEOUT_MS);
-    pending.set(id, { resolve, reject, timer });
+    const pending = { resolve, reject, timer: null, acked: false };
+    if (self.acksSeen) {
+      pending.timer = setTimeout(() => {
+        forget(self, id);
+        retire(self, "a request went unacknowledged");
+        reject(new DbWsTransportError("ws ack timed out", true));
+      }, WS_ACK_TIMEOUT_MS);
+    } else {
+      armIdleTimer(self, id, pending);
+    }
+    self.pending.set(id, pending);
+    let started = false;
+    let complete = false;
     try {
-      ws.send(frame);
+      for (const out of outboundFrames(id, frame)) {
+        self.ws.send(out);
+        started = true;
+      }
+      complete = true;
     } catch (err) {
-      clearTimeout(timer);
-      pending.delete(id);
+      clearPendingTimer(pending);
+      forget(self, id);
+      if (started) {
+        retire(self, "a partial request upload failed");
+      }
       reject(
         new DbWsTransportError(
           `ws send failed: ${err?.message || "unknown"}`,
-          false
+          complete
         )
       );
     }
@@ -2814,6 +2964,50 @@ function createAnalytics(call) {
   };
 }
 
+// src/email/index.ts
+var iso = (v) => v === void 0 ? void 0 : v instanceof Date ? v.toISOString() : v;
+function createEmail(call) {
+  return {
+    stats(options) {
+      return call("stats", {
+        start: iso(options?.start),
+        end: iso(options?.end),
+        buckets: options?.buckets
+      });
+    },
+    messages(options) {
+      return call("messages", {
+        ...options,
+        start: iso(options?.start),
+        end: iso(options?.end)
+      });
+    },
+    message(messageId) {
+      return call("message", { messageId });
+    },
+    batches(options) {
+      return call("batches", {
+        start: iso(options?.start),
+        end: iso(options?.end),
+        limit: options?.limit,
+        offset: options?.offset
+      });
+    },
+    batch(batchId) {
+      return call("batch", { batchId });
+    },
+    suppressions(options) {
+      return call("suppressions", options ?? {});
+    },
+    suppress(email2) {
+      return call("suppress", { email: email2 });
+    },
+    unsuppress(email2) {
+      return call("unsuppress", { email: email2 });
+    }
+  };
+}
+
 // src/task/index.ts
 import { randomUUID as randomUUID2 } from "crypto";
 
@@ -3797,7 +3991,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"] }
   },
@@ -4245,6 +4440,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,
@@ -4690,10 +4892,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);
@@ -4822,8 +5032,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,
@@ -5491,6 +5720,7 @@ var MindStudioAgent = class {
   _dataSources;
   _voice;
   _analytics;
+  _email;
   /** @internal Auth type — 'internal' for CALLBACK_TOKEN (managed mode), 'apiKey' otherwise. */
   _authType;
   /** @internal Usage source sent on step executions (from MINDSTUDIO_REQUEST_SOURCE).
@@ -6074,6 +6304,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) {
@@ -6528,6 +6765,24 @@ var MindStudioAgent = class {
       this._analyticsRequest.bind(this)
     );
   }
+  /**
+   * Outbound email: the per-recipient delivery log, blast stats, and this app's
+   * unsubscribe list. Sending is the `sendEmail` action, not this namespace.
+   *
+   * @example
+   * ```ts
+   * import { email } from '@mindstudio-ai/agent';
+   *
+   * // A support lookup: did this person get their mail?
+   * const { messages } = await email.messages({ recipient: 'a@b.com' });
+   *
+   * // How did the August newsletter do?
+   * const blast = await email.batch('newsletter-2026-08');
+   * ```
+   */
+  get email() {
+    return this._email ??= createEmail(this._emailRequest.bind(this));
+  }
   /**
    * Jewel surfaces: arrival-shaped triggers (`propose`) and the app-native
    * approval queue (`queue.list` / `queue.resolve`). See {@link JewelsApi}.
@@ -6666,6 +6921,18 @@ var MindStudioAgent = class {
    * of surfacing as empty data. Deliberately single-shot and scoped to this
    * namespace — the other brokered transports keep their semantics.
    */
+  /**
+   * Brokered email transport. No 429 retry, unlike analytics: this namespace
+   * carries writes (suppress / unsuppress), and silently retrying a mutation is a
+   * different risk from retrying an idempotent read. A caller that wants one can
+   * retry a read itself.
+   */
+  async _emailRequest(op, body) {
+    return this._brokeredRequest("email", op, body, {
+      fallbackMessage: "Email API call failed",
+      fallbackCode: "email_error"
+    });
+  }
   async _analyticsRequest(op, body) {
     const call = () => this._brokeredRequest("analytics", op, body, {
       fallbackMessage: "Analytics read failed",
@@ -7570,6 +7837,13 @@ var analytics = new Proxy({}, {
     return typeof value === "function" ? value.bind(target) : value;
   }
 });
+var email = new Proxy({}, {
+  get(_, prop) {
+    const target = mindstudio.email;
+    const value = Reflect.get(target, prop, target);
+    return typeof value === "function" ? value.bind(target) : value;
+  }
+});
 var session = new Proxy(
   {},
   {
@@ -7598,6 +7872,7 @@ export {
   db,
   index_default as default,
   defineJewel,
+  email,
   files,
   getRequestContext,
   mindstudio,