@mindstudio-ai/agent 0.1.36 → 0.1.37

package/dist/index.js

@@ -7,6 +7,18 @@ var MindStudioError = class extends Error {
     this.details = details;
   }
   name = "MindStudioError";
+  toString() {
+    return `MindStudioError [${this.code}] (${this.status}): ${this.message}`;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      status: this.status,
+      ...this.details != null && { details: this.details }
+    };
+  }
 };
 
 // src/http.ts
@@ -52,7 +64,10 @@ async function requestWithRetry(config, method, url, body, attempt) {
         }
         if (body2.code) code = body2.code;
       } catch {
-        if (text && text.length < 500) message = text;
+        if (text) {
+          const stripped = text.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
+          if (stripped) message = stripped.slice(0, 200);
+        }
       }
     } catch {
     }
@@ -85,7 +100,7 @@ var RateLimiter = class {
   async acquire() {
     if (this.callCount >= this.callCap) {
       throw new MindStudioError(
-        `Call cap reached (${this.callCap} calls). Internal tokens are limited to 500 calls per execution.`,
+        `Call cap exceeded (${this.callCap} calls per execution). Reduce the number of API calls or use executeStepBatch() to combine multiple steps.`,
         "call_cap_exceeded",
         429
       );
@@ -152,7 +167,7 @@ function loadConfig() {
 
 // src/auth/index.ts
 var AuthContext = class {
-  /** The current user's ID. */
+  /** The current user's ID, or null for unauthenticated users. */
   userId;
   /** The current user's roles in this app. */
   roles;
@@ -191,9 +206,16 @@ var AuthContext = class {
    * ```
    */
   requireRole(...roles) {
+    if (this.userId == null) {
+      throw new MindStudioError(
+        "No authenticated user",
+        "unauthenticated",
+        401
+      );
+    }
     if (!this.hasRole(...roles)) {
       throw new MindStudioError(
-        `User does not have required role: ${roles.join(", ")}`,
+        `User has role(s) [${this.roles.join(", ") || "none"}] but requires one of: [${roles.join(", ")}]`,
         "forbidden",
         403
       );
@@ -277,11 +299,6 @@ function buildSelect(table, options = {}) {
   if (options.offset != null) sql += ` OFFSET ${options.offset}`;
   return { sql, params: params.length > 0 ? params : void 0 };
 }
-function buildCount(table, where, whereParams) {
-  let sql = `SELECT COUNT(*) as count FROM ${table}`;
-  if (where) sql += ` WHERE ${where}`;
-  return { sql, params: whereParams?.length ? whereParams : void 0 };
-}
 function buildExists(table, where, whereParams, negate) {
   const inner = where ? `SELECT 1 FROM ${table} WHERE ${where}` : `SELECT 1 FROM ${table}`;
   const fn = negate ? "NOT EXISTS" : "EXISTS";
@@ -352,20 +369,20 @@ function compilePredicate(fn) {
   try {
     const source = fn.toString();
     const paramName = extractParamName(source);
-    if (!paramName) return { type: "js", fn };
+    if (!paramName) return { type: "js", fn, reason: "could not extract parameter name" };
     const body = extractBody(source);
-    if (!body) return { type: "js", fn };
+    if (!body) return { type: "js", fn, reason: "could not extract function body" };
     const tokens = tokenize(body);
-    if (tokens.length === 0) return { type: "js", fn };
+    if (tokens.length === 0) return { type: "js", fn, reason: "empty token stream" };
     const parser = new Parser(tokens, paramName, fn);
     const ast = parser.parseExpression();
-    if (!ast) return { type: "js", fn };
-    if (parser.pos < tokens.length) return { type: "js", fn };
+    if (!ast) return { type: "js", fn, reason: "could not parse expression" };
+    if (parser.pos < tokens.length) return { type: "js", fn, reason: "unexpected tokens after expression" };
     const where = compileNode(ast);
-    if (!where) return { type: "js", fn };
+    if (!where) return { type: "js", fn, reason: "could not compile to SQL" };
     return { type: "sql", where };
-  } catch {
-    return { type: "js", fn };
+  } catch (err) {
+    return { type: "js", fn, reason: `compilation error: ${err?.message || "unknown"}` };
   }
 }
 function extractParamName(source) {
@@ -842,6 +859,9 @@ var Query = class _Query {
   _limit;
   _offset;
   _config;
+  /** @internal Pre-compiled WHERE clause (bypasses predicate compiler). Used by Table.get(). */
+  _rawWhere;
+  _rawWhereParams;
   /** @internal Post-process transform applied after row deserialization. */
   _postProcess;
   constructor(config, options) {
@@ -852,6 +872,8 @@ var Query = class _Query {
     this._limit = options?.limit;
     this._offset = options?.offset;
     this._postProcess = options?.postProcess;
+    this._rawWhere = options?.rawWhere;
+    this._rawWhereParams = options?.rawWhereParams;
   }
   _clone(overrides) {
     return new _Query(this._config, {
@@ -860,7 +882,9 @@ var Query = class _Query {
       reversed: overrides.reversed ?? this._reversed,
       limit: overrides.limit ?? this._limit,
       offset: overrides.offset ?? this._offset,
-      postProcess: overrides.postProcess
+      postProcess: overrides.postProcess,
+      rawWhere: this._rawWhere,
+      rawWhereParams: this._rawWhereParams
     });
   }
   // -------------------------------------------------------------------------
@@ -897,33 +921,16 @@ var Query = class _Query {
       postProcess: (rows) => rows[0] ?? null
     });
   }
-  async count() {
-    const compiled = this._compilePredicates();
-    if (compiled.allSql) {
-      const query = buildCount(
-        this._config.tableName,
-        compiled.sqlWhere || void 0
-      );
-      const results = await this._config.executeBatch([query]);
-      const row = results[0]?.rows[0];
-      return row?.count ?? 0;
-    }
-    const rows = await this._fetchAndFilterInJs(compiled);
-    return rows.length;
+  count() {
+    return this._clone({
+      postProcess: (rows) => rows.length
+    });
   }
-  async some() {
-    const compiled = this._compilePredicates();
-    if (compiled.allSql) {
-      const query = buildExists(
-        this._config.tableName,
-        compiled.sqlWhere || void 0
-      );
-      const results = await this._config.executeBatch([query]);
-      const row = results[0]?.rows[0];
-      return row?.result === 1;
-    }
-    const rows = await this._fetchAndFilterInJs(compiled);
-    return rows.length > 0;
+  some() {
+    return this._clone({
+      limit: 1,
+      postProcess: (rows) => rows.length > 0
+    });
   }
   async every() {
     const compiled = this._compilePredicates();
@@ -950,19 +957,19 @@ var Query = class _Query {
   max(accessor) {
     return this.sortBy(accessor).reverse().first();
   }
-  async groupBy(accessor) {
-    const rows = await this._execute();
-    const map = /* @__PURE__ */ new Map();
-    for (const row of rows) {
-      const key = accessor(row);
-      const group = map.get(key);
-      if (group) {
-        group.push(row);
-      } else {
-        map.set(key, [row]);
+  groupBy(accessor) {
+    return this._clone({
+      postProcess: (rows) => {
+        const map = /* @__PURE__ */ new Map();
+        for (const row of rows) {
+          const key = accessor(row);
+          const group = map.get(key);
+          if (group) group.push(row);
+          else map.set(key, [row]);
+        }
+        return map;
       }
-    }
-    return map;
+    });
   }
   // -------------------------------------------------------------------------
   // Batch compilation — used by db.batch() to extract SQL without executing
@@ -976,6 +983,16 @@ var Query = class _Query {
    * all rows and this query can filter them in JS post-fetch.
    */
   _compile() {
+    if (this._rawWhere) {
+      const query = buildSelect(this._config.tableName, {
+        where: this._rawWhere,
+        whereParams: this._rawWhereParams,
+        orderBy: void 0,
+        limit: this._limit,
+        offset: this._offset
+      });
+      return { type: "query", query, fallbackQuery: null, config: this._config, postProcess: this._postProcess };
+    }
     const compiled = this._compilePredicates();
     const sortField = this._sortAccessor ? extractFieldName(this._sortAccessor) : void 0;
     if (compiled.allSql) {
@@ -1054,6 +1071,21 @@ var Query = class _Query {
   // Execution internals
   // -------------------------------------------------------------------------
   async _execute() {
+    if (this._rawWhere) {
+      const query = buildSelect(this._config.tableName, {
+        where: this._rawWhere,
+        whereParams: this._rawWhereParams,
+        limit: this._limit,
+        offset: this._offset
+      });
+      const results = await this._config.executeBatch([query]);
+      return results[0].rows.map(
+        (row) => deserializeRow(
+          row,
+          this._config.columns
+        )
+      );
+    }
     const compiled = this._compilePredicates();
     if (compiled.allSql) {
       const sortField = this._sortAccessor ? extractFieldName(this._sortAccessor) : void 0;
@@ -1104,9 +1136,12 @@ var Query = class _Query {
   }
   async _fetchAndFilterInJs(compiled) {
     const allRows = await this._fetchAllRows();
-    if (compiled.compiled.some((c) => c.type === "js")) {
+    const jsFallbacks = compiled.compiled.filter((c) => c.type === "js");
+    if (jsFallbacks.length > 0) {
+      const reasons = jsFallbacks.map((c) => c.type === "js" ? c.reason : void 0).filter(Boolean);
+      const reasonSuffix = reasons.length > 0 ? ` (${reasons.join("; ")})` : "";
       console.warn(
-        `[mindstudio] Filter on ${this._config.tableName} could not be compiled to SQL \u2014 scanning ${allRows.length} rows in JS`
+        `[mindstudio] Filter on '${this._config.tableName}' could not be compiled to SQL${reasonSuffix} \u2014 scanning ${allRows.length} rows in JS`
       );
     }
     return allRows.filter(
@@ -1179,8 +1214,10 @@ var Mutation = class _Mutation {
    */
   _compile() {
     if (this._executor) {
-      throw new Error(
-        "This operation cannot be batched (e.g. removeAll with a predicate that cannot compile to SQL). Await it separately."
+      throw new MindStudioError(
+        "This operation cannot be batched (e.g. removeAll with a JS-fallback predicate). Await it separately instead of passing to db.batch().",
+        "not_batchable",
+        400
       );
     }
     return {
@@ -1217,58 +1254,61 @@ var Table = class {
     this._config = config;
   }
   // -------------------------------------------------------------------------
-  // Reads — direct
+  // Reads — all return batchable Query objects (lazy until awaited)
   // -------------------------------------------------------------------------
-  async get(id) {
-    const query = buildSelect(this._config.tableName, {
-      where: `id = ?`,
-      whereParams: [id],
-      limit: 1
+  /** Get a single row by ID. Returns null if not found. */
+  get(id) {
+    return new Query(this._config, {
+      rawWhere: "id = ?",
+      rawWhereParams: [id],
+      limit: 1,
+      postProcess: (rows) => rows[0] ?? null
     });
-    const results = await this._config.executeBatch([query]);
-    if (results[0].rows.length === 0) return null;
-    return deserializeRow(
-      results[0].rows[0],
-      this._config.columns
-    );
   }
-  async findOne(predicate) {
+  /** Find the first row matching a predicate. Returns null if none match. */
+  findOne(predicate) {
     return this.filter(predicate).first();
   }
-  async count(predicate) {
+  count(predicate) {
     if (predicate) return this.filter(predicate).count();
-    const query = buildCount(this._config.tableName);
-    const results = await this._config.executeBatch([query]);
-    const row = results[0]?.rows[0];
-    return row?.count ?? 0;
+    return this.toArray().count();
   }
-  async some(predicate) {
+  /** True if any row matches the predicate. */
+  some(predicate) {
     return this.filter(predicate).some();
   }
+  /** True if all rows match the predicate. */
   async every(predicate) {
     return this.filter(predicate).every();
   }
+  /** True if the table has zero rows. */
   async isEmpty() {
     const query = buildExists(this._config.tableName, void 0, void 0, true);
     const results = await this._config.executeBatch([query]);
     const row = results[0]?.rows[0];
     return row?.result === 1;
   }
-  async min(accessor) {
+  /** Row with the minimum value for a field, or null if table is empty. */
+  min(accessor) {
     return this.sortBy(accessor).first();
   }
-  async max(accessor) {
+  /** Row with the maximum value for a field, or null if table is empty. */
+  max(accessor) {
     return this.sortBy(accessor).reverse().first();
   }
-  async groupBy(accessor) {
+  /** Group rows by a field. Returns a Map. */
+  groupBy(accessor) {
     return new Query(this._config).groupBy(accessor);
   }
-  // -------------------------------------------------------------------------
-  // Reads — chainable
-  // -------------------------------------------------------------------------
+  /** Get all rows as an array. */
+  toArray() {
+    return new Query(this._config);
+  }
+  /** Filter rows by a predicate. Returns a chainable Query. */
   filter(predicate) {
     return new Query(this._config).filter(predicate);
   }
+  /** Sort rows by a field. Returns a chainable Query. */
   sortBy(accessor) {
     return new Query(this._config).sortBy(accessor);
   }
@@ -1295,7 +1335,11 @@ var Table = class {
             this._config.columns
           );
         }
-        return void 0;
+        throw new MindStudioError(
+          `Insert into '${this._config.tableName}' succeeded but returned no row. This may indicate a constraint violation.`,
+          "insert_failed",
+          500
+        );
       });
       const result = isArray ? rows : rows[0];
       this._syncRolesIfNeeded(
@@ -1319,6 +1363,13 @@ var Table = class {
       this._config.columns
     );
     return new Mutation(this._config, [query], (results) => {
+      if (!results[0]?.rows[0]) {
+        throw new MindStudioError(
+          `Row not found: no row with ID '${id}' in table '${this._config.tableName}'`,
+          "row_not_found",
+          404
+        );
+      }
       const result = deserializeRow(
         results[0].rows[0],
         this._config.columns
@@ -1333,7 +1384,9 @@ var Table = class {
   }
   remove(id) {
     const query = buildDelete(this._config.tableName, `id = ?`, [id]);
-    return new Mutation(this._config, [query], () => void 0);
+    return new Mutation(this._config, [query], (results) => ({
+      deleted: results[0].changes > 0
+    }));
   }
   /**
    * Remove all rows matching a predicate. Returns the count removed.
@@ -1367,7 +1420,7 @@ var Table = class {
   }
   clear() {
     const query = buildDelete(this._config.tableName);
-    return new Mutation(this._config, [query], () => void 0);
+    return new Mutation(this._config, [query], (results) => results[0].changes);
   }
   /**
    * Insert a row, or update it if a row with the same unique key already
@@ -1385,6 +1438,15 @@ var Table = class {
     this._validateUniqueConstraint(conflictColumns);
     const withDefaults = this._config.defaults ? { ...this._config.defaults, ...data } : data;
     this._checkManagedColumns(withDefaults);
+    for (const col of conflictColumns) {
+      if (!(col in withDefaults)) {
+        throw new MindStudioError(
+          `Upsert on ${this._config.tableName} requires "${col}" in data (conflict key)`,
+          "missing_conflict_key",
+          400
+        );
+      }
+    }
     const query = buildUpsert(
       this._config.tableName,
       withDefaults,
@@ -1392,6 +1454,13 @@ var Table = class {
       this._config.columns
     );
     return new Mutation(this._config, [query], (results) => {
+      if (!results[0]?.rows[0]) {
+        throw new MindStudioError(
+          `Upsert into ${this._config.tableName} returned no row`,
+          "upsert_failed",
+          500
+        );
+      }
       const result = deserializeRow(
         results[0].rows[0],
         this._config.columns
@@ -1543,7 +1612,7 @@ function createDb(databases, executeBatch, authConfig, syncRoles) {
           if (c.type === "query") {
             if (!c.query && c.predicates?.length) {
               console.warn(
-                `[mindstudio] db.batch(): filter on ${c.config.tableName} could not be compiled to SQL \u2014 processing in JS`
+                `[mindstudio] db.batch(): filter on '${c.config.tableName}' could not be compiled to SQL \u2014 processing in JS`
               );
             }
             return Query._processResults(results[0], c);
@@ -3018,9 +3087,14 @@ var stepMetadata = {
   },
   "sendEmail": {
     stepType: "sendEmail",
-    description: "Send an email to one or more configured recipient addresses.",
-    usageNotes: '- Recipient email addresses are resolved from OAuth connections configured by the app creator. The user running the workflow does not specify the recipient directly.\n- If the body is a URL to a hosted HTML file on the CDN, the HTML is fetched and used as the email body.\n- When generateHtml is enabled, the body text is converted to a styled HTML email using an AI model.\n- connectionId can be a comma-separated list to send to multiple recipients.\n- The special connectionId "trigger_email" uses the email address that triggered the workflow.',
-    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)" }, "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": { "type": "string" }, "description": "URLs of files to attach to the email" } }, "required": ["subject", "body"] },
+    description: "Send an email to one or more recipient addresses.",
+    usageNotes: `- Use the "to" field to send to specific email addresses directly. For v2 apps, recipients must be verified users in the app's user table.
+- 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.
+- If the body is a URL to a hosted HTML file on the CDN, the HTML is fetched and used as the email body.
+- When generateHtml is enabled, the body text is converted to a styled HTML email using an AI model.
+- 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.`,
+    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" } }] }, "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": { "type": "string" }, "description": "URLs of files to attach to the email" } }, "required": ["subject", "body"] },
     outputSchema: { "type": "object", "properties": { "recipients": { "type": "array", "items": { "type": "string" }, "description": "Email addresses the message was sent to" } }, "required": ["recipients"] }
   },
   "sendGmailDraft": {
@@ -3342,7 +3416,7 @@ var MindStudioAgent = class {
       const res = await fetch(data.outputUrl);
       if (!res.ok) {
         throw new MindStudioError(
-          `Failed to fetch output from S3: ${res.status} ${res.statusText}`,
+          `Failed to fetch ${stepType} output from S3: ${res.status} ${res.statusText}`,
           "output_fetch_error",
           res.status
         );
@@ -3405,13 +3479,27 @@ var MindStudioAgent = class {
     this._httpConfig.rateLimiter.updateFromHeaders(res.headers);
     if (!res.ok) {
       this._httpConfig.rateLimiter.release();
-      const errorBody = await res.json().catch(() => ({}));
-      throw new MindStudioError(
-        errorBody.message || `${res.status} ${res.statusText}`,
-        errorBody.code || "api_error",
-        res.status,
-        errorBody
-      );
+      let message = `${res.status} ${res.statusText}`;
+      let code = "api_error";
+      let details;
+      try {
+        const text = await res.text();
+        try {
+          const body2 = JSON.parse(text);
+          details = body2;
+          const errMsg = (typeof body2.error === "string" ? body2.error : void 0) ?? (typeof body2.message === "string" ? body2.message : void 0) ?? (typeof body2.details === "string" ? body2.details : void 0);
+          if (errMsg) message = errMsg;
+          else if (body2.error || body2.message || body2.details) {
+            message = JSON.stringify(body2.error ?? body2.message ?? body2.details);
+          }
+          if (body2.code) code = body2.code;
+        } catch {
+          const stripped = text.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
+          if (stripped) message = stripped.slice(0, 200);
+        }
+      } catch {
+      }
+      throw new MindStudioError(`[${stepType}] ${message}`, code, res.status, details);
     }
     const headers = res.headers;
     try {
@@ -3444,7 +3532,7 @@ var MindStudioAgent = class {
               };
             } else if (event.type === "error") {
               throw new MindStudioError(
-                event.error || "Step execution failed",
+                `[${stepType}] ${event.error || "Step execution failed"}`,
                 "step_error",
                 500
               );
@@ -3483,7 +3571,7 @@ var MindStudioAgent = class {
       }
       if (!doneEvent) {
         throw new MindStudioError(
-          "Stream ended without a done event",
+          `[${stepType}] Stream ended unexpectedly without completing. The step execution may have been interrupted.`,
           "stream_error",
           500
         );
@@ -3495,7 +3583,7 @@ var MindStudioAgent = class {
         const s3Res = await fetch(doneEvent.outputUrl);
         if (!s3Res.ok) {
           throw new MindStudioError(
-            `Failed to fetch output from S3: ${s3Res.status} ${s3Res.statusText}`,
+            `Failed to fetch ${stepType} output from S3: ${s3Res.status} ${s3Res.statusText}`,
             "output_fetch_error",
             s3Res.status
           );
@@ -3856,7 +3944,7 @@ var MindStudioAgent = class {
     }
     if (!this._auth) {
       throw new MindStudioError(
-        "Auth context not yet loaded. Call `await agent.ensureContext()` or perform any db operation first (which auto-hydrates context). Inside the MindStudio sandbox, context is loaded automatically.",
+        "Auth context not loaded. Call `await agent.ensureContext()` first, or perform any db operation (which auto-loads context).",
         "context_not_loaded",
         400
       );
@@ -4030,13 +4118,12 @@ var MindStudioAgent = class {
       if (!res.ok) {
         const text = await res.text().catch(() => "");
         console.warn(
-          `[mindstudio] Failed to sync roles for user ${userId}: ${res.status} ${text}`
+          `[mindstudio] Role sync failed for user ${userId} (${res.status}${text ? ": " + text.slice(0, 100) : ""}). Roles were saved to the database but may not be reflected in auth.hasRole() until the next successful write.`
         );
       }
     } catch (err) {
       console.warn(
-        `[mindstudio] Failed to sync roles for user ${userId}:`,
-        err
+        `[mindstudio] Role sync failed for user ${userId}: network error. Roles were saved to the database but may not be reflected in auth.hasRole() until the next successful write.`
       );
     }
   }