@mindstudio-ai/agent 0.1.7 → 0.1.9

package/dist/index.js

@@ -137,6 +137,1334 @@ function loadConfig() {
   }
 }
 
+// src/auth/index.ts
+var AuthContext = class {
+  /** The current user's ID. */
+  userId;
+  /** The current user's roles in this app. */
+  roles;
+  /** All role assignments for this app (all users, all roles). */
+  _roleAssignments;
+  constructor(ctx) {
+    this.userId = ctx.userId;
+    this._roleAssignments = ctx.roleAssignments;
+    this.roles = ctx.roleAssignments.filter((a) => a.userId === ctx.userId).map((a) => a.roleName);
+  }
+  /**
+   * Check if the current user has **any** of the given roles.
+   * Returns true if at least one matches.
+   *
+   * @example
+   * ```ts
+   * if (auth.hasRole(Roles.admin, Roles.approver)) {
+   *   // user is an admin OR an approver
+   * }
+   * ```
+   */
+  hasRole(...roles) {
+    return roles.some((r) => this.roles.includes(r));
+  }
+  /**
+   * Require the current user to have at least one of the given roles.
+   * Throws a `MindStudioError` with code `'forbidden'` and status 403
+   * if the user lacks all of the specified roles.
+   *
+   * Use this at the top of route handlers to gate access.
+   *
+   * @example
+   * ```ts
+   * auth.requireRole(Roles.admin);
+   * // code below only runs if user is an admin
+   * ```
+   */
+  requireRole(...roles) {
+    if (!this.hasRole(...roles)) {
+      throw new MindStudioError(
+        `User does not have required role: ${roles.join(", ")}`,
+        "forbidden",
+        403
+      );
+    }
+  }
+  /**
+   * Get all user IDs that have the given role in this app.
+   * Synchronous — scans the preloaded role assignments.
+   *
+   * @example
+   * ```ts
+   * const reviewers = auth.getUsersByRole(Roles.reviewer);
+   * // ['user-id-1', 'user-id-2', ...]
+   * ```
+   */
+  getUsersByRole(role) {
+    return this._roleAssignments.filter((a) => a.roleName === role).map((a) => a.userId);
+  }
+};
+var Roles = new Proxy(
+  {},
+  {
+    get(_, prop) {
+      if (typeof prop === "string") return prop;
+      return void 0;
+    }
+  }
+);
+
+// src/db/sql.ts
+function escapeValue(val) {
+  if (val === null || val === void 0) return "NULL";
+  if (typeof val === "boolean") return val ? "1" : "0";
+  if (typeof val === "number") return String(val);
+  if (typeof val === "string") return `'${val.replace(/'/g, "''")}'`;
+  const json = JSON.stringify(val);
+  return `'${json.replace(/'/g, "''")}'`;
+}
+function serializeValue(val, columnName, columns) {
+  const col = columns.find((c) => c.name === columnName);
+  if (col?.type === "user" && typeof val === "string") {
+    return escapeValue(`@@user@@${val}`);
+  }
+  return escapeValue(val);
+}
+var USER_PREFIX = "@@user@@";
+function deserializeRow(row, columns) {
+  const result = {};
+  for (const [key, value] of Object.entries(row)) {
+    const col = columns.find((c) => c.name === key);
+    if (col?.type === "user" && typeof value === "string" && value.startsWith(USER_PREFIX)) {
+      result[key] = value.slice(USER_PREFIX.length);
+    } else if (col?.type === "json" && typeof value === "string") {
+      try {
+        result[key] = JSON.parse(value);
+      } catch {
+        result[key] = value;
+      }
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function buildSelect(table, options = {}) {
+  let sql = `SELECT * FROM ${table}`;
+  if (options.where) sql += ` WHERE ${options.where}`;
+  if (options.orderBy) sql += ` ORDER BY ${options.orderBy}${options.desc ? " DESC" : " ASC"}`;
+  if (options.limit != null) sql += ` LIMIT ${options.limit}`;
+  if (options.offset != null) sql += ` OFFSET ${options.offset}`;
+  return sql;
+}
+function buildCount(table, where) {
+  let sql = `SELECT COUNT(*) as count FROM ${table}`;
+  if (where) sql += ` WHERE ${where}`;
+  return sql;
+}
+function buildExists(table, where, negate) {
+  const inner = where ? `SELECT 1 FROM ${table} WHERE ${where}` : `SELECT 1 FROM ${table}`;
+  const fn = negate ? "NOT EXISTS" : "EXISTS";
+  return `SELECT ${fn}(${inner}) as result`;
+}
+function buildInsert(table, data, columns) {
+  const filtered = stripSystemColumns(data);
+  const keys = Object.keys(filtered);
+  const vals = keys.map((k) => serializeValue(filtered[k], k, columns));
+  return `INSERT INTO ${table} (${keys.join(", ")}) VALUES (${vals.join(", ")})`;
+}
+function buildUpdate(table, id, data, columns) {
+  const filtered = stripSystemColumns(data);
+  const assignments = Object.entries(filtered).map(([k, v]) => `${k} = ${serializeValue(v, k, columns)}`).join(", ");
+  return `UPDATE ${table} SET ${assignments} WHERE id = ${escapeValue(id)}`;
+}
+function buildDelete(table, where) {
+  let sql = `DELETE FROM ${table}`;
+  if (where) sql += ` WHERE ${where}`;
+  return sql;
+}
+var SYSTEM_COLUMNS = /* @__PURE__ */ new Set(["id", "createdAt", "updatedAt", "lastUpdatedBy"]);
+function stripSystemColumns(data) {
+  const result = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (!SYSTEM_COLUMNS.has(key)) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+// src/db/predicate.ts
+function compilePredicate(fn) {
+  try {
+    const source = fn.toString();
+    const paramName = extractParamName(source);
+    if (!paramName) return { type: "js", fn };
+    const body = extractBody(source);
+    if (!body) return { type: "js", fn };
+    const tokens = tokenize(body);
+    if (tokens.length === 0) return { type: "js", fn };
+    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 };
+    const where = compileNode(ast);
+    if (!where) return { type: "js", fn };
+    return { type: "sql", where };
+  } catch {
+    return { type: "js", fn };
+  }
+}
+function extractParamName(source) {
+  const match = source.match(
+    /^\s*(?:\(?\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*(?::[^)]*?)?\)?\s*=>)/
+  );
+  return match?.[1] ?? null;
+}
+function extractBody(source) {
+  const arrowIdx = source.indexOf("=>");
+  if (arrowIdx === -1) return null;
+  let body = source.slice(arrowIdx + 2).trim();
+  if (body.startsWith("{")) {
+    const match = body.match(/^\{\s*return\s+([\s\S]+?)\s*;?\s*\}$/);
+    if (!match) return null;
+    body = match[1];
+  }
+  return body.trim() || null;
+}
+function tokenize(expr) {
+  const tokens = [];
+  let i = 0;
+  while (i < expr.length) {
+    const ch = expr[i];
+    if (/\s/.test(ch)) {
+      i++;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      const quote = ch;
+      let str = "";
+      i++;
+      while (i < expr.length && expr[i] !== quote) {
+        if (expr[i] === "\\") {
+          i++;
+          if (i < expr.length) str += expr[i];
+        } else {
+          str += expr[i];
+        }
+        i++;
+      }
+      if (i >= expr.length) return [];
+      i++;
+      tokens.push({ type: "string", value: str });
+      continue;
+    }
+    if (ch === "`") return [];
+    if (/[0-9]/.test(ch) || ch === "-" && i + 1 < expr.length && /[0-9]/.test(expr[i + 1])) {
+      let num = ch;
+      i++;
+      while (i < expr.length && /[0-9.]/.test(expr[i])) {
+        num += expr[i];
+        i++;
+      }
+      tokens.push({ type: "number", value: num });
+      continue;
+    }
+    if (expr.slice(i, i + 3) === "===" || expr.slice(i, i + 3) === "!==") {
+      tokens.push({ type: "operator", value: expr.slice(i, i + 3) });
+      i += 3;
+      continue;
+    }
+    if (expr.slice(i, i + 2) === "==" || expr.slice(i, i + 2) === "!=" || expr.slice(i, i + 2) === "<=" || expr.slice(i, i + 2) === ">=" || expr.slice(i, i + 2) === "&&" || expr.slice(i, i + 2) === "||") {
+      tokens.push({ type: "operator", value: expr.slice(i, i + 2) });
+      i += 2;
+      continue;
+    }
+    if (ch === "!" || ch === "<" || ch === ">") {
+      tokens.push({ type: "operator", value: ch });
+      i++;
+      continue;
+    }
+    if (ch === ".") {
+      tokens.push({ type: "dot", value: "." });
+      i++;
+      continue;
+    }
+    if (ch === "(") {
+      tokens.push({ type: "lparen", value: "(" });
+      i++;
+      continue;
+    }
+    if (ch === ")") {
+      tokens.push({ type: "rparen", value: ")" });
+      i++;
+      continue;
+    }
+    if (ch === "[") {
+      tokens.push({ type: "lbracket", value: "[" });
+      i++;
+      continue;
+    }
+    if (ch === "]") {
+      tokens.push({ type: "rbracket", value: "]" });
+      i++;
+      continue;
+    }
+    if (ch === ",") {
+      tokens.push({ type: "comma", value: "," });
+      i++;
+      continue;
+    }
+    if (/[a-zA-Z_$]/.test(ch)) {
+      let ident = ch;
+      i++;
+      while (i < expr.length && /[a-zA-Z0-9_$]/.test(expr[i])) {
+        ident += expr[i];
+        i++;
+      }
+      tokens.push({ type: "identifier", value: ident });
+      continue;
+    }
+    return [];
+  }
+  return tokens;
+}
+var Parser = class {
+  constructor(tokens, paramName, originalFn) {
+    this.tokens = tokens;
+    this.paramName = paramName;
+    this.originalFn = originalFn;
+  }
+  pos = 0;
+  /** Peek at the current token without consuming it. */
+  peek() {
+    return this.tokens[this.pos];
+  }
+  /** Consume the current token and advance. */
+  advance() {
+    return this.tokens[this.pos++];
+  }
+  /** Check if the current token matches an expected type and value. */
+  match(type, value) {
+    const t = this.peek();
+    if (!t) return false;
+    if (t.type !== type) return false;
+    if (value !== void 0 && t.value !== value) return false;
+    return true;
+  }
+  /** Consume a token if it matches, otherwise return false. */
+  eat(type, value) {
+    if (this.match(type, value)) {
+      this.advance();
+      return true;
+    }
+    return false;
+  }
+  // --- Grammar rules ---
+  /** Entry point: parse a full expression. */
+  parseExpression() {
+    return this.parseOr();
+  }
+  /** or_expr → and_expr ( '||' and_expr )* */
+  parseOr() {
+    let left = this.parseAnd();
+    if (!left) return null;
+    while (this.match("operator", "||")) {
+      this.advance();
+      const right = this.parseAnd();
+      if (!right) return null;
+      left = { kind: "logical", operator: "OR", left, right };
+    }
+    return left;
+  }
+  /** and_expr → not_expr ( '&&' not_expr )* */
+  parseAnd() {
+    let left = this.parseNot();
+    if (!left) return null;
+    while (this.match("operator", "&&")) {
+      this.advance();
+      const right = this.parseNot();
+      if (!right) return null;
+      left = { kind: "logical", operator: "AND", left, right };
+    }
+    return left;
+  }
+  /** not_expr → '!' not_expr | primary */
+  parseNot() {
+    if (this.match("operator", "!")) {
+      this.advance();
+      if (this.match("lparen")) {
+        this.advance();
+        const inner2 = this.parseExpression();
+        if (!inner2) return null;
+        if (!this.eat("rparen")) return null;
+        return { kind: "not", operand: inner2 };
+      }
+      const inner = this.parsePrimary();
+      if (!inner) return null;
+      if (inner.kind === "booleanField") {
+        return { ...inner, negated: !inner.negated };
+      }
+      return { kind: "not", operand: inner };
+    }
+    return this.parsePrimary();
+  }
+  /**
+   * primary → field_comparison | null_check | includes_expr | paren_expr | boolean_field
+   *
+   * This is the workhorse — handles the different patterns that can appear
+   * as atomic expressions within a larger &&/|| combination.
+   */
+  parsePrimary() {
+    if (this.match("lparen")) {
+      this.advance();
+      const inner = this.parseExpression();
+      if (!inner) return null;
+      if (!this.eat("rparen")) return null;
+      return inner;
+    }
+    if (this.match("lbracket")) {
+      return this.parseArrayIncludes();
+    }
+    if (this.match("identifier", this.paramName)) {
+      return this.parseFieldExpression();
+    }
+    if (this.match("identifier")) {
+      return this.parseNonParamExpression();
+    }
+    return null;
+  }
+  /**
+   * Parse an expression that starts with the parameter name (e.g. `o.field`).
+   *
+   * Could be:
+   * - `o.field === value` (comparison)
+   * - `o.field != null` (null check)
+   * - `o.field.includes('text')` (LIKE)
+   * - `o.field` alone (boolean field check)
+   */
+  parseFieldExpression() {
+    this.advance();
+    const field = this.parseFieldPath();
+    if (!field) return null;
+    const next = this.peek();
+    if (next?.type === "dot" && this.lookAheadForIncludes()) {
+      return this.parseFieldIncludes(field);
+    }
+    if (next?.type === "operator" && isComparisonOp(next.value)) {
+      return this.parseComparison(field);
+    }
+    return { kind: "booleanField", field, negated: false };
+  }
+  /**
+   * Parse a dot-separated field path after the parameter name.
+   * `o.status` → `"status"`, `o.address.city` → `"json_extract(address, '$.city')"`.
+   */
+  parseFieldPath() {
+    if (!this.eat("dot")) return null;
+    if (!this.match("identifier")) return null;
+    const parts = [this.advance().value];
+    while (this.match("dot") && this.tokens[this.pos + 1]?.type === "identifier") {
+      this.advance();
+      parts.push(this.advance().value);
+    }
+    if (parts.length === 1) {
+      return parts[0];
+    }
+    const root = parts[0];
+    const jsonPath = "$." + parts.slice(1).join(".");
+    return `json_extract(${root}, '${jsonPath}')`;
+  }
+  /**
+   * Parse a comparison: `field OP value`.
+   * The field has already been parsed; we need the operator and right-hand value.
+   */
+  parseComparison(field) {
+    const opToken = this.advance();
+    const jsOp = opToken.value;
+    const value = this.parseValue();
+    if (value === PARSE_FAILED) return null;
+    if (value === null || value === void 0) {
+      if (jsOp === "===" || jsOp === "==") {
+        return { kind: "nullCheck", field, isNull: true };
+      }
+      if (jsOp === "!==" || jsOp === "!=") {
+        return { kind: "nullCheck", field, isNull: false };
+      }
+      return null;
+    }
+    const sqlOp = JS_TO_SQL_OP[jsOp];
+    if (!sqlOp) return null;
+    return { kind: "comparison", field, operator: sqlOp, value };
+  }
+  /**
+   * Parse `o.field.includes('text')` → LIKE expression.
+   * The field name has already been parsed.
+   */
+  parseFieldIncludes(field) {
+    this.advance();
+    this.advance();
+    if (!this.eat("lparen")) return null;
+    const value = this.parseValue();
+    if (value === PARSE_FAILED || typeof value !== "string") return null;
+    if (!this.eat("rparen")) return null;
+    const escaped = value.replace(/%/g, "\\%").replace(/_/g, "\\_");
+    return { kind: "like", field, pattern: `%${escaped}%` };
+  }
+  /**
+   * Parse `['a', 'b', 'c'].includes(o.field)` → IN expression.
+   * The opening bracket has been peeked but not consumed.
+   */
+  parseArrayIncludes() {
+    this.advance();
+    const values = [];
+    while (!this.match("rbracket")) {
+      if (values.length > 0) {
+        if (!this.eat("comma")) return null;
+      }
+      const val = this.parseValue();
+      if (val === PARSE_FAILED) return null;
+      values.push(val);
+    }
+    this.advance();
+    if (!this.eat("dot")) return null;
+    if (!this.match("identifier", "includes")) return null;
+    this.advance();
+    if (!this.eat("lparen")) return null;
+    if (!this.match("identifier", this.paramName)) return null;
+    this.advance();
+    const field = this.parseFieldPath();
+    if (!field) return null;
+    if (!this.eat("rparen")) return null;
+    return { kind: "in", field, values };
+  }
+  /**
+   * Parse an expression that starts with an identifier that is NOT the
+   * parameter name. This could be:
+   * - A keyword literal: `true`, `false`, `null`, `undefined`
+   * - A closure variable used in a comparison (handled by backtracking)
+   */
+  parseNonParamExpression() {
+    const ident = this.peek().value;
+    if (ident === "true" || ident === "false") return null;
+    return null;
+  }
+  /**
+   * Parse a literal value or closure variable reference.
+   *
+   * Returns the parsed value, or PARSE_FAILED if parsing fails.
+   * Returns `null` or `undefined` for those keyword literals.
+   */
+  parseValue() {
+    const t = this.peek();
+    if (!t) return PARSE_FAILED;
+    if (t.type === "string") {
+      this.advance();
+      return t.value;
+    }
+    if (t.type === "number") {
+      this.advance();
+      return Number(t.value);
+    }
+    if (t.type === "identifier") {
+      if (t.value === "true") {
+        this.advance();
+        return true;
+      }
+      if (t.value === "false") {
+        this.advance();
+        return false;
+      }
+      if (t.value === "null") {
+        this.advance();
+        return null;
+      }
+      if (t.value === "undefined") {
+        this.advance();
+        return void 0;
+      }
+      return this.resolveClosureVariable();
+    }
+    if (t.type === "operator" && t.value === "-") {
+      this.advance();
+      const next = this.peek();
+      if (next?.type === "number") {
+        this.advance();
+        return -Number(next.value);
+      }
+      return PARSE_FAILED;
+    }
+    return PARSE_FAILED;
+  }
+  /**
+   * Attempt to resolve a closure variable by invoking the original function
+   * with a recording Proxy and inspecting what values it compares against.
+   *
+   * This handles the common pattern:
+   * ```ts
+   * const userId = auth.userId;
+   * orders.filter(o => o.requestedBy === userId)
+   * ```
+   *
+   * The Proxy captures property accesses on the parameter and we can then
+   * extract the comparison value from the function's behavior. However,
+   * this approach has limitations — if the function throws, has side effects,
+   * or uses the variable in a non-comparison context, we fall back to JS.
+   */
+  resolveClosureVariable() {
+    const identToken = this.advance();
+    let closureExpr = identToken.value;
+    while (this.match("dot") && this.tokens[this.pos + 1]?.type === "identifier") {
+      this.advance();
+      closureExpr += "." + this.advance().value;
+    }
+    try {
+      const MARKER = /* @__PURE__ */ Symbol("field_access_marker");
+      const accessed = [];
+      const proxy = new Proxy(
+        {},
+        {
+          get(_, prop) {
+            accessed.push(prop);
+            return new Proxy(() => MARKER, {
+              get(_2, nestedProp) {
+                accessed.push(nestedProp);
+                return MARKER;
+              }
+            });
+          }
+        }
+      );
+      void proxy;
+      return PARSE_FAILED;
+    } catch {
+      return PARSE_FAILED;
+    }
+  }
+  /**
+   * Look ahead to check if the next tokens form `.includes(`.
+   * Used to disambiguate `o.field.includes(...)` from `o.field.nested`.
+   */
+  lookAheadForIncludes() {
+    return this.tokens[this.pos]?.type === "dot" && this.tokens[this.pos + 1]?.type === "identifier" && this.tokens[this.pos + 1]?.value === "includes" && this.tokens[this.pos + 2]?.type === "lparen";
+  }
+};
+function compileNode(node) {
+  switch (node.kind) {
+    case "comparison":
+      return `${node.field} ${node.operator} ${escapeValue(node.value)}`;
+    case "nullCheck":
+      return `${node.field} ${node.isNull ? "IS NULL" : "IS NOT NULL"}`;
+    case "in": {
+      if (node.values.length === 0) return "0";
+      const vals = node.values.map(escapeValue).join(", ");
+      return `${node.field} IN (${vals})`;
+    }
+    case "like":
+      return `${node.field} LIKE ${escapeValue(node.pattern)}`;
+    case "booleanField":
+      return node.negated ? `${node.field} = 0` : `${node.field} = 1`;
+    case "logical": {
+      const left = compileNode(node.left);
+      const right = compileNode(node.right);
+      if (!left || !right) return null;
+      return `(${left} ${node.operator} ${right})`;
+    }
+    case "not": {
+      const inner = compileNode(node.operand);
+      if (!inner) return null;
+      return `NOT (${inner})`;
+    }
+    default:
+      return null;
+  }
+}
+var JS_TO_SQL_OP = {
+  "===": "=",
+  "==": "=",
+  "!==": "!=",
+  "!=": "!=",
+  "<": "<",
+  ">": ">",
+  "<=": "<=",
+  ">=": ">="
+};
+var PARSE_FAILED = /* @__PURE__ */ Symbol("PARSE_FAILED");
+function isComparisonOp(value) {
+  return value in JS_TO_SQL_OP;
+}
+
+// src/db/query.ts
+var Query = class _Query {
+  /** @internal Accumulated predicate functions to filter by. */
+  _predicates;
+  /** @internal The field accessor for sorting, if set. */
+  _sortAccessor;
+  /** @internal Whether the sort order is reversed (DESC). */
+  _reversed;
+  /** @internal Maximum number of results (SQL LIMIT). */
+  _limit;
+  /** @internal Number of results to skip (SQL OFFSET). */
+  _offset;
+  /** @internal Binding to the database execution layer. */
+  _config;
+  constructor(config, options) {
+    this._config = config;
+    this._predicates = options?.predicates ?? [];
+    this._sortAccessor = options?.sortAccessor;
+    this._reversed = options?.reversed ?? false;
+    this._limit = options?.limit;
+    this._offset = options?.offset;
+  }
+  /**
+   * Create a clone of this query with some options overridden.
+   * Used internally by chain methods to maintain immutability.
+   */
+  _clone(overrides) {
+    return new _Query(this._config, {
+      predicates: overrides.predicates ?? this._predicates,
+      sortAccessor: overrides.sortAccessor ?? this._sortAccessor,
+      reversed: overrides.reversed ?? this._reversed,
+      limit: overrides.limit ?? this._limit,
+      offset: overrides.offset ?? this._offset
+    });
+  }
+  // -------------------------------------------------------------------------
+  // Chain methods — return new Query instances
+  // -------------------------------------------------------------------------
+  /**
+   * Add a filter predicate. Multiple filters are ANDed together.
+   *
+   * @example
+   * ```ts
+   * const active = Orders.filter(o => o.status === 'active');
+   * const expensive = active.filter(o => o.amount > 5000);
+   * // WHERE status = 'active' AND amount > 5000
+   * ```
+   */
+  filter(predicate) {
+    return this._clone({
+      predicates: [...this._predicates, predicate]
+    });
+  }
+  /**
+   * Sort results by a field (ascending by default).
+   * Use `.reverse()` after `.sortBy()` for descending order.
+   *
+   * @example
+   * ```ts
+   * const newest = Orders.sortBy(o => o.createdAt).reverse();
+   * ```
+   */
+  sortBy(accessor) {
+    return this._clone({ sortAccessor: accessor });
+  }
+  /**
+   * Reverse the current sort order. If no sort is set, this has no effect.
+   */
+  reverse() {
+    return this._clone({ reversed: !this._reversed });
+  }
+  /**
+   * Limit the number of results returned.
+   *
+   * @example
+   * ```ts
+   * const top10 = Orders.sortBy(o => o.amount).reverse().take(10);
+   * ```
+   */
+  take(n) {
+    return this._clone({ limit: n });
+  }
+  /**
+   * Skip the first n results. Use with `.take()` for pagination.
+   *
+   * @example
+   * ```ts
+   * const page2 = Orders.sortBy(o => o.createdAt).skip(50).take(50);
+   * ```
+   */
+  skip(n) {
+    return this._clone({ offset: n });
+  }
+  // -------------------------------------------------------------------------
+  // Terminal methods — execute the query and return results
+  // -------------------------------------------------------------------------
+  /**
+   * Return the first matching row, or null if no rows match.
+   * Applies the current sort order before taking the first result.
+   */
+  async first() {
+    const rows = await this._clone({ limit: 1 })._execute();
+    return rows[0] ?? null;
+  }
+  /**
+   * Return the last matching row (per current sort), or null.
+   * Flips the sort direction and takes 1 row.
+   */
+  async last() {
+    const rows = await this._clone({ limit: 1, reversed: !this._reversed })._execute();
+    return rows[0] ?? null;
+  }
+  /**
+   * Count matching rows. Returns a number, not the rows themselves.
+   * Executes as `SELECT COUNT(*)` when predicates compile to SQL.
+   */
+  async count() {
+    const compiled = this._compilePredicates();
+    if (compiled.allSql) {
+      const where = compiled.sqlWhere || void 0;
+      const sql = buildCount(this._config.tableName, where);
+      const result = await this._config.executeQuery(sql);
+      const row = result.rows[0];
+      return row?.count ?? 0;
+    }
+    const rows = await this._fetchAndFilterInJs(compiled);
+    return rows.length;
+  }
+  /**
+   * Check if any row matches the current filters. Short-circuits —
+   * doesn't load all rows when using SQL.
+   */
+  async some() {
+    const compiled = this._compilePredicates();
+    if (compiled.allSql) {
+      const where = compiled.sqlWhere || void 0;
+      const sql = buildExists(this._config.tableName, where);
+      const result = await this._config.executeQuery(sql);
+      const row = result.rows[0];
+      return row?.result === 1;
+    }
+    const rows = await this._fetchAndFilterInJs(compiled);
+    return rows.length > 0;
+  }
+  /**
+   * Check if all rows match the current filters. Short-circuits on false.
+   *
+   * Implemented as NOT EXISTS(... WHERE NOT predicate) — returns true
+   * if no rows fail the predicate.
+   */
+  async every() {
+    const compiled = this._compilePredicates();
+    if (compiled.allSql && compiled.sqlWhere) {
+      const sql = buildExists(this._config.tableName, `NOT (${compiled.sqlWhere})`, true);
+      const result = await this._config.executeQuery(sql);
+      const row = result.rows[0];
+      return row?.result === 1;
+    }
+    if (this._predicates.length === 0) return true;
+    const allRows = await this._fetchAllRows();
+    return allRows.every(
+      (row) => this._predicates.every((pred) => pred(row))
+    );
+  }
+  /**
+   * Return the row with the minimum value for the given field.
+   * Executes as `ORDER BY field ASC LIMIT 1` in SQL.
+   */
+  async min(accessor) {
+    return this.sortBy(accessor).first();
+  }
+  /**
+   * Return the row with the maximum value for the given field.
+   * Executes as `ORDER BY field DESC LIMIT 1` in SQL.
+   */
+  async max(accessor) {
+    return this.sortBy(accessor).reverse().first();
+  }
+  /**
+   * Group rows by a field value. Returns a Map.
+   * Always executes in JS (no SQL equivalent for grouping into a Map).
+   */
+  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]);
+      }
+    }
+    return map;
+  }
+  // -------------------------------------------------------------------------
+  // PromiseLike implementation — makes `await query` work
+  // -------------------------------------------------------------------------
+  /**
+   * PromiseLike.then() — executes the query and pipes the result.
+   * This is what makes `const rows = await query` work.
+   */
+  then(onfulfilled, onrejected) {
+    return this._execute().then(onfulfilled, onrejected);
+  }
+  // -------------------------------------------------------------------------
+  // Execution internals
+  // -------------------------------------------------------------------------
+  /**
+   * Execute the query and return typed result rows.
+   *
+   * This is the core execution method. It:
+   * 1. Tries to compile all predicates to SQL
+   * 2. If all compile → builds and executes a single SQL query
+   * 3. If any fail → fetches all rows and processes in JS
+   * 4. Deserializes rows (user prefix stripping, JSON parsing)
+   */
+  async _execute() {
+    const compiled = this._compilePredicates();
+    if (compiled.allSql) {
+      const sortField = this._sortAccessor ? extractFieldName(this._sortAccessor) : void 0;
+      const sql = buildSelect(this._config.tableName, {
+        where: compiled.sqlWhere || void 0,
+        orderBy: sortField ?? void 0,
+        desc: this._reversed,
+        limit: this._limit,
+        offset: this._offset
+      });
+      const result = await this._config.executeQuery(sql);
+      return result.rows.map(
+        (row) => deserializeRow(
+          row,
+          this._config.columns
+        )
+      );
+    }
+    let rows = await this._fetchAndFilterInJs(compiled);
+    if (this._sortAccessor) {
+      const accessor = this._sortAccessor;
+      rows.sort((a, b) => {
+        const aVal = accessor(a);
+        const bVal = accessor(b);
+        if (aVal < bVal) return this._reversed ? 1 : -1;
+        if (aVal > bVal) return this._reversed ? -1 : 1;
+        return 0;
+      });
+    }
+    if (this._offset != null || this._limit != null) {
+      const start = this._offset ?? 0;
+      const end = this._limit != null ? start + this._limit : void 0;
+      rows = rows.slice(start, end);
+    }
+    return rows;
+  }
+  /**
+   * Compile all accumulated predicates and determine the execution strategy.
+   *
+   * Returns an object with:
+   * - `allSql`: whether all predicates compiled to SQL
+   * - `sqlWhere`: combined WHERE clause (ANDed) if all compiled
+   * - `compiled`: individual compilation results
+   */
+  _compilePredicates() {
+    if (this._predicates.length === 0) {
+      return { allSql: true, sqlWhere: "", compiled: [] };
+    }
+    const compiled = this._predicates.map((pred) => compilePredicate(pred));
+    const allSql = compiled.every((c) => c.type === "sql");
+    let sqlWhere = "";
+    if (allSql) {
+      sqlWhere = compiled.map((c) => c.where).join(" AND ");
+    }
+    return { allSql, sqlWhere, compiled };
+  }
+  /**
+   * Fetch all rows from the table and apply JS predicates.
+   * This is the fallback path when SQL compilation fails.
+   *
+   * Logs a warning to stderr so developers know they're on the slow path.
+   */
+  async _fetchAndFilterInJs(compiled) {
+    const allRows = await this._fetchAllRows();
+    if (compiled.compiled.some((c) => c.type === "js")) {
+      console.warn(
+        `[mindstudio] Filter on ${this._config.tableName} could not be compiled to SQL \u2014 scanning ${allRows.length} rows in JS`
+      );
+    }
+    return allRows.filter(
+      (row) => this._predicates.every((pred) => pred(row))
+    );
+  }
+  /**
+   * Fetch all rows from the table (SELECT * with no WHERE).
+   * Used by the JS fallback path.
+   */
+  async _fetchAllRows() {
+    const sql = buildSelect(this._config.tableName);
+    const result = await this._config.executeQuery(sql);
+    return result.rows.map(
+      (row) => deserializeRow(row, this._config.columns)
+    );
+  }
+};
+function extractFieldName(accessor) {
+  const source = accessor.toString();
+  const match = source.match(
+    /^\s*\(?([a-zA-Z_$][a-zA-Z0-9_$]*)\)?\s*=>\s*\1\.([a-zA-Z_$][a-zA-Z0-9_$]*)\s*$/
+  );
+  return match?.[2] ?? null;
+}
+
+// src/db/table.ts
+var Table = class {
+  /** @internal Runtime config binding this table to the execution layer. */
+  _config;
+  constructor(config) {
+    this._config = config;
+  }
+  // -------------------------------------------------------------------------
+  // Reads — direct (return Promises)
+  // -------------------------------------------------------------------------
+  /**
+   * Get a single row by ID. Returns null if not found.
+   *
+   * @example
+   * ```ts
+   * const order = await Orders.get('abc-123');
+   * if (order) console.log(order.status);
+   * ```
+   */
+  async get(id) {
+    const sql = buildSelect(this._config.tableName, {
+      where: `id = ${escapeValue(id)}`,
+      limit: 1
+    });
+    const result = await this._config.executeQuery(sql);
+    if (result.rows.length === 0) return null;
+    return deserializeRow(
+      result.rows[0],
+      this._config.columns
+    );
+  }
+  /**
+   * Find the first row matching a predicate. Returns null if none match.
+   *
+   * @example
+   * ```ts
+   * const activeOrder = await Orders.findOne(o => o.status === 'active');
+   * ```
+   */
+  async findOne(predicate) {
+    return this.filter(predicate).first();
+  }
+  /**
+   * Count rows, optionally filtered by a predicate.
+   *
+   * @example
+   * ```ts
+   * const total = await Orders.count();
+   * const pending = await Orders.count(o => o.status === 'pending');
+   * ```
+   */
+  async count(predicate) {
+    if (predicate) {
+      return this.filter(predicate).count();
+    }
+    const sql = buildCount(this._config.tableName);
+    const result = await this._config.executeQuery(sql);
+    const row = result.rows[0];
+    return row?.count ?? 0;
+  }
+  /**
+   * Check if any row matches a predicate. Short-circuits.
+   *
+   * @example
+   * ```ts
+   * const hasActive = await Orders.some(o => o.status === 'active');
+   * ```
+   */
+  async some(predicate) {
+    return this.filter(predicate).some();
+  }
+  /**
+   * Check if all rows match a predicate.
+   *
+   * @example
+   * ```ts
+   * const allComplete = await Orders.every(o => o.status === 'completed');
+   * ```
+   */
+  async every(predicate) {
+    return this.filter(predicate).every();
+  }
+  /**
+   * Check if the table has zero rows.
+   *
+   * @example
+   * ```ts
+   * if (await Orders.isEmpty()) console.log('No orders yet');
+   * ```
+   */
+  async isEmpty() {
+    const sql = buildExists(this._config.tableName, void 0, true);
+    const result = await this._config.executeQuery(sql);
+    const row = result.rows[0];
+    return row?.result === 1;
+  }
+  /**
+   * Return the row with the minimum value for a field.
+   * Executes as `ORDER BY field ASC LIMIT 1`.
+   *
+   * @example
+   * ```ts
+   * const cheapest = await Orders.min(o => o.amount);
+   * ```
+   */
+  async min(accessor) {
+    return this.sortBy(accessor).first();
+  }
+  /**
+   * Return the row with the maximum value for a field.
+   * Executes as `ORDER BY field DESC LIMIT 1`.
+   *
+   * @example
+   * ```ts
+   * const mostExpensive = await Orders.max(o => o.amount);
+   * ```
+   */
+  async max(accessor) {
+    return this.sortBy(accessor).reverse().first();
+  }
+  /**
+   * Group all rows by a field value. Returns a Map.
+   *
+   * @example
+   * ```ts
+   * const byStatus = await Orders.groupBy(o => o.status);
+   * // Map { 'pending' => [...], 'approved' => [...] }
+   * ```
+   */
+  async groupBy(accessor) {
+    return new Query(this._config).groupBy(accessor);
+  }
+  // -------------------------------------------------------------------------
+  // Reads — chainable (return Query<T>)
+  // -------------------------------------------------------------------------
+  /**
+   * Filter rows by a predicate. Returns a chainable Query.
+   *
+   * The predicate is compiled to SQL when possible. If compilation fails,
+   * the query falls back to fetching all rows and filtering in JS.
+   *
+   * @example
+   * ```ts
+   * const active = await Orders.filter(o => o.status === 'active');
+   * const recentActive = await Orders
+   *   .filter(o => o.status === 'active')
+   *   .sortBy(o => o.createdAt)
+   *   .reverse()
+   *   .take(10);
+   * ```
+   */
+  filter(predicate) {
+    return new Query(this._config).filter(predicate);
+  }
+  /**
+   * Sort all rows by a field. Returns a chainable Query.
+   *
+   * @example
+   * ```ts
+   * const newest = await Orders.sortBy(o => o.createdAt).reverse().take(5);
+   * ```
+   */
+  sortBy(accessor) {
+    return new Query(this._config).sortBy(accessor);
+  }
+  async push(data) {
+    const isArray = Array.isArray(data);
+    const items = isArray ? data : [data];
+    const results = [];
+    for (const item of items) {
+      const insertSql = buildInsert(
+        this._config.tableName,
+        item,
+        this._config.columns
+      );
+      await this._config.executeQuery(insertSql);
+      const fetchSql = `SELECT * FROM ${this._config.tableName} WHERE rowid = last_insert_rowid()`;
+      const fetchResult = await this._config.executeQuery(fetchSql);
+      if (fetchResult.rows.length > 0) {
+        results.push(
+          deserializeRow(
+            fetchResult.rows[0],
+            this._config.columns
+          )
+        );
+      }
+    }
+    return isArray ? results : results[0];
+  }
+  /**
+   * Update a row by ID. Only the provided fields are changed.
+   * Returns the updated row.
+   *
+   * System columns cannot be updated — they're stripped automatically.
+   * `updatedAt` and `lastUpdatedBy` are set by the platform.
+   *
+   * @example
+   * ```ts
+   * const updated = await Orders.update(order.id, { status: 'approved' });
+   * console.log(updated.updatedAt); // freshly updated
+   * ```
+   */
+  async update(id, data) {
+    const updateSql = buildUpdate(
+      this._config.tableName,
+      id,
+      data,
+      this._config.columns
+    );
+    await this._config.executeQuery(updateSql);
+    const fetchSql = buildSelect(this._config.tableName, {
+      where: `id = ${escapeValue(id)}`,
+      limit: 1
+    });
+    const result = await this._config.executeQuery(fetchSql);
+    return deserializeRow(
+      result.rows[0],
+      this._config.columns
+    );
+  }
+  /**
+   * Remove a row by ID.
+   *
+   * @example
+   * ```ts
+   * await Orders.remove('abc-123');
+   * ```
+   */
+  async remove(id) {
+    const sql = buildDelete(
+      this._config.tableName,
+      `id = ${escapeValue(id)}`
+    );
+    await this._config.executeQuery(sql);
+  }
+  /**
+   * Remove all rows matching a predicate. Returns the count removed.
+   *
+   * The predicate is compiled to SQL when possible. If compilation fails,
+   * the function fetches all matching rows, collects their IDs, and
+   * deletes them individually.
+   *
+   * @example
+   * ```ts
+   * const removed = await Orders.removeAll(o => o.status === 'rejected');
+   * console.log(`Removed ${removed} orders`);
+   * ```
+   */
+  async removeAll(predicate) {
+    const compiled = compilePredicate(predicate);
+    if (compiled.type === "sql") {
+      const sql = buildDelete(this._config.tableName, compiled.where);
+      const result = await this._config.executeQuery(sql);
+      return result.changes;
+    }
+    console.warn(
+      `[mindstudio] removeAll predicate on ${this._config.tableName} could not be compiled to SQL \u2014 fetching all rows first`
+    );
+    const allSql = buildSelect(this._config.tableName);
+    const allResult = await this._config.executeQuery(allSql);
+    const allRows = allResult.rows.map(
+      (r) => deserializeRow(
+        r,
+        this._config.columns
+      )
+    );
+    const matching = allRows.filter((row) => predicate(row));
+    let count = 0;
+    for (const row of matching) {
+      const id = row.id;
+      if (id) {
+        const sql = buildDelete(this._config.tableName, `id = ${escapeValue(id)}`);
+        await this._config.executeQuery(sql);
+        count++;
+      }
+    }
+    return count;
+  }
+  /**
+   * Remove all rows from the table.
+   *
+   * @example
+   * ```ts
+   * await Orders.clear();
+   * ```
+   */
+  async clear() {
+    const sql = buildDelete(this._config.tableName);
+    await this._config.executeQuery(sql);
+  }
+};
+
+// src/db/index.ts
+function createDb(databases, executeQuery) {
+  return {
+    defineTable(name, options) {
+      const resolved = resolveTable(databases, name, options?.database);
+      const config = {
+        databaseId: resolved.databaseId,
+        tableName: name,
+        columns: resolved.columns,
+        executeQuery: (sql) => executeQuery(resolved.databaseId, sql)
+      };
+      return new Table(config);
+    },
+    // --- Time helpers ---
+    // Pure JS, no platform dependency. All timestamps are unix ms.
+    now: () => Date.now(),
+    days: (n) => n * 864e5,
+    hours: (n) => n * 36e5,
+    minutes: (n) => n * 6e4,
+    ago: (ms) => Date.now() - ms,
+    fromNow: (ms) => Date.now() + ms
+  };
+}
+function resolveTable(databases, tableName, databaseHint) {
+  if (databases.length === 0) {
+    throw new MindStudioError(
+      `No databases found in app context. Make sure the app has at least one database configured.`,
+      "no_databases",
+      400
+    );
+  }
+  if (databaseHint) {
+    const targetDb = databases.find(
+      (db2) => db2.id === databaseHint || db2.name === databaseHint
+    );
+    if (!targetDb) {
+      const available = databases.map((db2) => db2.name || db2.id).join(", ");
+      throw new MindStudioError(
+        `Database "${databaseHint}" not found. Available databases: ${available}`,
+        "database_not_found",
+        400
+      );
+    }
+    const table = targetDb.tables.find((t) => t.name === tableName);
+    if (!table) {
+      const available = targetDb.tables.map((t) => t.name).join(", ");
+      throw new MindStudioError(
+        `Table "${tableName}" not found in database "${databaseHint}". Available tables: ${available || "(none)"}`,
+        "table_not_found",
+        400
+      );
+    }
+    return { databaseId: targetDb.id, columns: table.schema };
+  }
+  for (const db2 of databases) {
+    const table = db2.tables.find((t) => t.name === tableName);
+    if (table) {
+      return {
+        databaseId: db2.id,
+        columns: table.schema
+      };
+    }
+  }
+  const availableTables = databases.flatMap((db2) => db2.tables.map((t) => t.name)).join(", ");
+  throw new MindStudioError(
+    `Table "${tableName}" not found in app databases. Available tables: ${availableTables || "(none)"}`,
+    "table_not_found",
+    400
+  );
+}
+
 // src/generated/steps.ts
 function applyStepMethods(AgentClass) {
   const proto = AgentClass.prototype;
@@ -170,6 +1498,9 @@ function applyStepMethods(AgentClass) {
   proto.captureThumbnail = function(step, options) {
     return this.executeStep("captureThumbnail", step, options);
   };
+  proto.checkAppRole = function(step, options) {
+    return this.executeStep("checkAppRole", step, options);
+  };
   proto.codaCreateUpdatePage = function(step, options) {
     return this.executeStep("codaCreateUpdatePage", step, options);
   };
@@ -419,6 +1750,9 @@ function applyStepMethods(AgentClass) {
   proto.postToZapier = function(step, options) {
     return this.executeStep("postToZapier", step, options);
   };
+  proto.queryAppDatabase = function(step, options) {
+    return this.executeStep("queryAppDatabase", step, options);
+  };
   proto.queryDataSource = function(step, options) {
     return this.executeStep("queryDataSource", step, options);
   };
@@ -620,17 +1954,46 @@ var MindStudioAgent = class {
   _reuseThreadId;
   /** @internal */
   _threadId;
+  // ---- App context (db + auth) ----
+  /**
+   * @internal App ID for context resolution. Resolved from:
+   * constructor appId → MINDSTUDIO_APP_ID env → sandbox globals →
+   * auto-detected from first executeStep response header.
+   */
+  _appId;
+  /**
+   * @internal Cached app context (auth + databases). Populated by
+   * ensureContext() and cached for the lifetime of the instance.
+   */
+  _context;
+  /**
+   * @internal Deduplication promise for ensureContext(). Ensures only one
+   * context fetch is in-flight at a time, even if multiple db/auth
+   * operations trigger it concurrently.
+   */
+  _contextPromise;
+  /** @internal Cached AuthContext instance, created during context hydration. */
+  _auth;
+  /** @internal Cached Db namespace instance, created during context hydration. */
+  _db;
+  /** @internal Auth type — 'internal' for CALLBACK_TOKEN (managed mode), 'apiKey' otherwise. */
+  _authType;
   constructor(options = {}) {
     const config = loadConfig();
     const { token, authType } = resolveToken(options.apiKey, config);
     const baseUrl = options.baseUrl ?? process.env.MINDSTUDIO_BASE_URL ?? process.env.REMOTE_HOSTNAME ?? config.baseUrl ?? DEFAULT_BASE_URL;
     this._reuseThreadId = options.reuseThreadId ?? /^(true|1)$/i.test(process.env.MINDSTUDIO_REUSE_THREAD_ID ?? "");
+    this._appId = options.appId ?? process.env.MINDSTUDIO_APP_ID ?? void 0;
+    this._authType = authType;
     this._httpConfig = {
       baseUrl,
       token,
       rateLimiter: new RateLimiter(authType),
       maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES
     };
+    if (authType === "internal") {
+      this._trySandboxHydration();
+    }
   }
   /**
    * Execute any step by its type name. This is the low-level method that all
@@ -669,6 +2032,10 @@ var MindStudioAgent = class {
     if (this._reuseThreadId && returnedThreadId) {
       this._threadId = returnedThreadId;
     }
+    const returnedAppId = headers.get("x-mindstudio-app-id");
+    if (!this._appId && returnedAppId) {
+      this._appId = returnedAppId;
+    }
     const remaining = headers.get("x-ratelimit-remaining");
     const billingCost = headers.get("x-mindstudio-billing-cost");
     const billingEvents = headers.get("x-mindstudio-billing-events");
@@ -935,6 +2302,278 @@ var MindStudioAgent = class {
     return data;
   }
   // -------------------------------------------------------------------------
+  // db + auth namespaces
+  // -------------------------------------------------------------------------
+  /**
+   * The `auth` namespace — synchronous role-based access control.
+   *
+   * Provides the current user's identity and roles. All methods are
+   * synchronous since the role map is preloaded during context hydration.
+   *
+   * **Important**: Context must be hydrated before accessing `auth`.
+   * - Inside the MindStudio sandbox: automatic (populated from globals)
+   * - Outside the sandbox: call `await agent.ensureContext()` first,
+   *   or access `auth` after any `db` operation (which auto-hydrates)
+   *
+   * @throws {MindStudioError} if context has not been hydrated yet
+   *
+   * @example
+   * ```ts
+   * await agent.ensureContext();
+   * agent.auth.requireRole(Roles.admin);
+   * const admins = agent.auth.getUsersByRole(Roles.admin);
+   * ```
+   */
+  get auth() {
+    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.",
+        "context_not_loaded",
+        400
+      );
+    }
+    return this._auth;
+  }
+  /**
+   * The `db` namespace — chainable collection API over managed databases.
+   *
+   * Use `db.defineTable<T>(name)` to get a typed Table<T>, then call
+   * collection methods (filter, sortBy, push, update, etc.) on it.
+   *
+   * Context is auto-hydrated on first query execution — you can safely
+   * call `defineTable()` at module scope without triggering any HTTP.
+   *
+   * @example
+   * ```ts
+   * const Orders = agent.db.defineTable<Order>('orders');
+   * const active = await Orders.filter(o => o.status === 'active').take(10);
+   * ```
+   */
+  get db() {
+    if (this._db) return this._db;
+    return this._createLazyDb();
+  }
+  /**
+   * Hydrate the app context (auth + database metadata). This must be
+   * called before using `auth` synchronously. For `db`, hydration happens
+   * automatically on first query.
+   *
+   * Context is fetched once and cached for the instance's lifetime.
+   * Calling `ensureContext()` multiple times is safe (no-op after first).
+   *
+   * Context sources (checked in order):
+   * 1. Sandbox globals (`globalThis.ai.auth`, `globalThis.ai.databases`)
+   * 2. HTTP: `GET /developer/v2/helpers/app-context?appId={appId}`
+   *
+   * @throws {MindStudioError} if no `appId` is available
+   *
+   * @example
+   * ```ts
+   * await agent.ensureContext();
+   * // auth is now available synchronously
+   * agent.auth.requireRole(Roles.admin);
+   * ```
+   */
+  async ensureContext() {
+    if (this._context) return;
+    if (!this._contextPromise) {
+      this._contextPromise = this._hydrateContext();
+    }
+    await this._contextPromise;
+  }
+  /**
+   * @internal Fetch and cache app context, then create auth + db instances.
+   *
+   * In managed mode (CALLBACK_TOKEN), the platform resolves the app from
+   * the token — no appId needed. With an API key, appId is required.
+   */
+  async _hydrateContext() {
+    if (!this._appId && this._authType !== "internal") {
+      throw new MindStudioError(
+        "No app ID available for context resolution. Pass `appId` to the constructor, set the MINDSTUDIO_APP_ID environment variable, or make a step execution call first (which auto-detects the app ID).",
+        "missing_app_id",
+        400
+      );
+    }
+    const context = await this.getAppContext(this._appId);
+    this._applyContext(context);
+  }
+  /**
+   * @internal Apply a resolved context object — creates AuthContext and Db.
+   * Used by both the HTTP path and sandbox hydration.
+   */
+  _applyContext(context) {
+    this._context = context;
+    this._auth = new AuthContext(context.auth);
+    this._db = createDb(
+      context.databases,
+      this._executeDbQuery.bind(this)
+    );
+  }
+  /**
+   * @internal Try to hydrate context synchronously from sandbox globals.
+   * Called in the constructor when CALLBACK_TOKEN auth is detected.
+   *
+   * The MindStudio sandbox pre-populates `globalThis.ai` with:
+   * - `ai.auth`: { userId, roleAssignments[] }
+   * - `ai.databases`: [{ id, name, tables[] }]
+   */
+  _trySandboxHydration() {
+    const ai = globalThis.ai;
+    if (ai?.auth && ai?.databases) {
+      this._applyContext({
+        auth: ai.auth,
+        databases: ai.databases
+      });
+    }
+  }
+  /**
+   * @internal Execute a SQL query against a managed database.
+   * Used as the `executeQuery` callback for Table instances.
+   *
+   * Calls the `queryAppDatabase` step with `parameterize: false`
+   * (the SDK builds fully-formed SQL with escaped inline values).
+   */
+  async _executeDbQuery(databaseId, sql) {
+    const result = await this.executeStep("queryAppDatabase", {
+      databaseId,
+      sql,
+      parameterize: false
+    });
+    return { rows: result.rows ?? [], changes: result.changes ?? 0 };
+  }
+  /**
+   * @internal Create a lazy Db proxy that auto-hydrates context.
+   *
+   * defineTable() returns Table instances immediately (no async needed).
+   * But the Table's executeQuery callback is wrapped to call ensureContext()
+   * before the first query, so context is fetched lazily.
+   */
+  _createLazyDb() {
+    const agent = this;
+    return {
+      defineTable(name, options) {
+        const databaseHint = options?.database;
+        return new Table({
+          databaseId: "",
+          tableName: name,
+          columns: [],
+          executeQuery: async (sql) => {
+            await agent.ensureContext();
+            const databases = agent._context.databases;
+            let targetDb;
+            if (databaseHint) {
+              targetDb = databases.find(
+                (d) => d.id === databaseHint || d.name === databaseHint
+              );
+            } else {
+              targetDb = databases.find(
+                (d) => d.tables.some((t) => t.name === name)
+              );
+            }
+            const databaseId = targetDb?.id ?? databases[0]?.id ?? "";
+            return agent._executeDbQuery(databaseId, sql);
+          }
+        });
+      },
+      // Time helpers work without context
+      now: () => Date.now(),
+      days: (n) => n * 864e5,
+      hours: (n) => n * 36e5,
+      minutes: (n) => n * 6e4,
+      ago: (ms) => Date.now() - ms,
+      fromNow: (ms) => Date.now() + ms
+    };
+  }
+  // -------------------------------------------------------------------------
+  // Helper methods — user resolution
+  // -------------------------------------------------------------------------
+  /**
+   * Resolve a single user ID to display info (name, email, profile picture).
+   *
+   * Use this when you have a `User`-typed field value and need the person's
+   * display name, email, or avatar. Returns null if the user ID is not found.
+   *
+   * Also available as a top-level import:
+   * ```ts
+   * import { resolveUser } from '@mindstudio-ai/agent';
+   * ```
+   *
+   * @param userId - The user ID to resolve (a `User` branded string or plain UUID)
+   * @returns Resolved user info, or null if not found
+   *
+   * @example
+   * ```ts
+   * const user = await agent.resolveUser(order.requestedBy);
+   * if (user) {
+   *   console.log(user.name);              // "Jane Smith"
+   *   console.log(user.email);             // "jane@example.com"
+   *   console.log(user.profilePictureUrl); // "https://..." or null
+   * }
+   * ```
+   */
+  async resolveUser(userId) {
+    const { users } = await this.resolveUsers([userId]);
+    return users[0] ?? null;
+  }
+  /**
+   * Resolve multiple user IDs to display info in a single request.
+   * Maximum 100 user IDs per request.
+   *
+   * Use this for batch resolution when you have multiple user references
+   * to display (e.g. all approvers on a purchase order, all team members).
+   *
+   * @param userIds - Array of user IDs to resolve (max 100)
+   * @returns Object with `users` array of resolved user info
+   *
+   * @example
+   * ```ts
+   * // Resolve all approvers at once
+   * const approverIds = approvals.map(a => a.assignedTo);
+   * const { users } = await agent.resolveUsers(approverIds);
+   *
+   * for (const u of users) {
+   *   console.log(`${u.name} (${u.email})`);
+   * }
+   * ```
+   */
+  async resolveUsers(userIds) {
+    const { data } = await request(
+      this._httpConfig,
+      "POST",
+      "/helpers/resolve-users",
+      { userIds }
+    );
+    return data;
+  }
+  // -------------------------------------------------------------------------
+  // App context
+  // -------------------------------------------------------------------------
+  /**
+   * Get auth and database context for an app.
+   *
+   * Returns role assignments and managed database schemas. Useful for
+   * hydrating `auth` and `db` namespaces when running outside the sandbox.
+   *
+   * When called with a CALLBACK_TOKEN (managed mode), `appId` is optional —
+   * the platform resolves the app from the token. With an API key, `appId`
+   * is required.
+   *
+   * ```ts
+   * const ctx = await agent.getAppContext('your-app-id');
+   * console.log(ctx.auth.roleAssignments, ctx.databases);
+   * ```
+   */
+  async getAppContext(appId) {
+    const query = appId ? `?appId=${encodeURIComponent(appId)}` : "";
+    const { data } = await request(
+      this._httpConfig,
+      "GET",
+      `/helpers/app-context${query}`
+    );
+    return data;
+  }
+  // -------------------------------------------------------------------------
   // Account methods
   // -------------------------------------------------------------------------
   /** Update the display name of the authenticated user/agent. */
@@ -1015,6 +2654,7 @@ var monacoSnippets = {
   "analyzeImage": { fields: [["prompt", "string"], ["imageUrl", "string"]], outputKeys: ["analysis"] },
   "analyzeVideo": { fields: [["prompt", "string"], ["videoUrl", "string"]], outputKeys: ["analysis"] },
   "captureThumbnail": { fields: [["videoUrl", "string"], ["at", "string"]], outputKeys: ["thumbnailUrl"] },
+  "checkAppRole": { fields: [["roleName", "string"]], outputKeys: ["hasRole", "userRoles"] },
   "codaCreateUpdatePage": { fields: [["pageData", "object"]], outputKeys: ["pageId"] },
   "codaCreateUpdateRow": { fields: [["docId", "string"], ["tableId", "string"], ["rowData", "object"]], outputKeys: ["rowId"] },
   "codaFindRow": { fields: [["docId", "string"], ["tableId", "string"], ["rowData", "object"]], outputKeys: ["row"] },
@@ -1100,6 +2740,7 @@ var monacoSnippets = {
   "postToSlackChannel": { fields: [["channelId", "string"], ["messageType", ["string", "blocks"]], ["message", "string"]], outputKeys: [] },
   "postToX": { fields: [["text", "string"]], outputKeys: [] },
   "postToZapier": { fields: [["webhookUrl", "string"], ["input", "object"]], outputKeys: ["data"] },
+  "queryAppDatabase": { fields: [["databaseId", "string"], ["sql", "string"]], outputKeys: ["rows", "changes"] },
   "queryDataSource": { fields: [["dataSourceId", "string"], ["query", "string"], ["maxResults", "number"]], outputKeys: ["text", "chunks", "query", "citations", "latencyMs"] },
   "queryExternalDatabase": { fields: [["query", "string"], ["outputFormat", ["json", "csv"]]], outputKeys: ["data"] },
   "redactPII": { fields: [["input", "string"], ["language", "string"], ["entities", "array"]], outputKeys: ["text"] },
@@ -1189,7 +2830,7 @@ var stepMetadata = {
     stepType: "addSubtitlesToVideo",
     description: "Automatically add subtitles to a video",
     usageNotes: "- Can control style of text and animation",
-    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video" }, "language": { "type": "string", "description": "ISO language code for subtitle transcription" }, "fontName": { "type": "string", "description": "Google Font name for subtitle text" }, "fontSize": { "type": "number", "description": "Font size in pixels. Default: 100." }, "fontWeight": { "enum": ["normal", "bold", "black"], "type": "string", "description": "Font weight for subtitle text" }, "fontColor": { "enum": ["white", "black", "red", "green", "blue", "yellow", "orange", "purple", "pink", "brown", "gray", "cyan", "magenta"], "type": "string", "description": "Color of the subtitle text" }, "highlightColor": { "enum": ["white", "black", "red", "green", "blue", "yellow", "orange", "purple", "pink", "brown", "gray", "cyan", "magenta"], "type": "string", "description": "Color used to highlight the currently spoken word" }, "strokeWidth": { "type": "number", "description": "Width of the text stroke outline in pixels" }, "strokeColor": { "enum": ["black", "white", "red", "green", "blue", "yellow", "orange", "purple", "pink", "brown", "gray", "cyan", "magenta"], "type": "string", "description": "Color of the text stroke outline" }, "backgroundColor": { "enum": ["black", "white", "red", "green", "blue", "yellow", "orange", "purple", "pink", "brown", "gray", "cyan", "magenta", "none"], "type": "string", "description": "Background color behind subtitle text. Use 'none' for transparent." }, "backgroundOpacity": { "type": "number", "description": "Opacity of the subtitle background. 0.0 = fully transparent, 1.0 = fully opaque." }, "position": { "enum": ["top", "center", "bottom"], "type": "string", "description": "Vertical position of subtitle text on screen" }, "yOffset": { "type": "number", "description": "Vertical offset in pixels from the position. Positive moves down, negative moves up. Default: 75." }, "wordsPerSubtitle": { "type": "number", "description": "Maximum number of words per subtitle segment. Use 1 for single-word display, 2-3 for short phrases, or 8-12 for full sentences. Default: 3." }, "enableAnimation": { "type": "boolean", "description": "When true, enables bounce-style entrance animation for subtitles. Default: true." }, "skipAssetCreation": { "type": "boolean", "description": "When true, the result will not appear in the user's asset history. Useful for intermediate compositing steps." } }, "required": ["videoUrl", "language", "fontName", "fontSize", "fontWeight", "fontColor", "highlightColor", "strokeWidth", "strokeColor", "backgroundColor", "backgroundOpacity", "position", "yOffset", "wordsPerSubtitle", "enableAnimation"] },
+    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video" }, "language": { "type": "string", "description": "ISO language code for subtitle transcription" }, "fontName": { "type": "string", "description": "Google Font name for subtitle text" }, "fontSize": { "type": "number", "description": "Font size in pixels. Default: 100." }, "fontWeight": { "enum": ["normal", "bold", "black"], "type": "string", "description": "Font weight for subtitle text" }, "fontColor": { "enum": ["white", "black", "red", "green", "blue", "yellow", "orange", "purple", "pink", "brown", "gray", "cyan", "magenta"], "type": "string", "description": "Color of the subtitle text" }, "highlightColor": { "enum": ["white", "black", "red", "green", "blue", "yellow", "orange", "purple", "pink", "brown", "gray", "cyan", "magenta"], "type": "string", "description": "Color used to highlight the currently spoken word" }, "strokeWidth": { "type": "number", "description": "Width of the text stroke outline in pixels" }, "strokeColor": { "enum": ["black", "white", "red", "green", "blue", "yellow", "orange", "purple", "pink", "brown", "gray", "cyan", "magenta"], "type": "string", "description": "Color of the text stroke outline" }, "backgroundColor": { "enum": ["black", "white", "red", "green", "blue", "yellow", "orange", "purple", "pink", "brown", "gray", "cyan", "magenta", "none"], "type": "string", "description": "Background color behind subtitle text. Use 'none' for transparent." }, "backgroundOpacity": { "type": "number", "description": "Opacity of the subtitle background. 0.0 = fully transparent, 1.0 = fully opaque." }, "position": { "enum": ["top", "center", "bottom"], "type": "string", "description": "Vertical position of subtitle text on screen" }, "yOffset": { "type": "number", "description": "Vertical offset in pixels from the position. Positive moves down, negative moves up. Default: 75." }, "wordsPerSubtitle": { "type": "number", "description": "Maximum number of words per subtitle segment. Use 1 for single-word display, 2-3 for short phrases, or 8-12 for full sentences. Default: 3." }, "enableAnimation": { "type": "boolean", "description": "When true, enables bounce-style entrance animation for subtitles. Default: true." }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["videoUrl", "language", "fontName", "fontSize", "fontWeight", "fontColor", "highlightColor", "strokeWidth", "strokeColor", "backgroundColor", "backgroundOpacity", "position", "yOffset", "wordsPerSubtitle", "enableAnimation"] },
     outputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the video with subtitles added" } }, "required": ["videoUrl"] }
   },
   "airtableCreateUpdateRecord": {
@@ -1241,6 +2882,13 @@ var stepMetadata = {
     inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video to capture a frame from" }, "at": { "anyOf": [{ "type": "number" }, { "type": "string" }] } }, "required": ["videoUrl", "at"] },
     outputSchema: { "type": "object", "properties": { "thumbnailUrl": { "type": "string", "description": "URL of the captured thumbnail image" } }, "required": ["thumbnailUrl"] }
   },
+  "checkAppRole": {
+    stepType: "checkAppRole",
+    description: "Check whether the current user has a specific app role and branch accordingly.",
+    usageNotes: '- Checks if the current user has been assigned a specific role in this app.\n- If the user has the role, transitions to the "has role" path.\n- If the user does not have the role, transitions to the "no role" path, or errors if no path is configured.\n- Role names are defined by the app creator and assigned to users via the app roles system.\n- The roleName field supports {{variables}} for dynamic role checks.',
+    inputSchema: { "type": "object", "properties": { "roleName": { "type": "string", "description": "The role name to check (supports {{variables}})" }, "hasRoleStepId": { "type": "string", "description": "Step to transition to if the user has the role (same workflow)" }, "hasRoleWorkflowId": { "type": "string", "description": "Workflow to jump to if the user has the role (cross workflow)" }, "noRoleStepId": { "type": "string", "description": "Step to transition to if the user does not have the role (same workflow)" }, "noRoleWorkflowId": { "type": "string", "description": "Workflow to jump to if the user does not have the role (cross workflow)" } }, "required": ["roleName"], "description": "Configuration for the check app role step" },
+    outputSchema: { "type": "object", "properties": { "hasRole": { "type": "boolean", "description": "Whether the current user has the checked role" }, "userRoles": { "type": "array", "items": { "type": "string" }, "description": "All roles assigned to the current user for this app" } }, "required": ["hasRole", "userRoles"] }
+  },
   "codaCreateUpdatePage": {
     stepType: "codaCreateUpdatePage",
     description: "Create a new page or update an existing page in a Coda document.",
@@ -1492,7 +3140,7 @@ var stepMetadata = {
     stepType: "generatePdf",
     description: "Generate an HTML asset and export it as a webpage, PDF, or image",
     usageNotes: '- Agents can generate HTML documents and export as webpage, PDFs, images, or videos. They do this by using the "generatePdf" block, which defines an HTML page with variables, and then the generation process renders the page to create the output and save its URL at the specified variable.\n- The template for the HTML page is generated by a separate process, and it can only use variables that have already been defined in the workflow at the time of its execution. It has full access to handlebars to render the HTML template, including a handlebars helper to render a markdown variable string as HTML (which can be useful for creating templates that render long strings). The template can also create its own simple JavaScript to do things like format dates and strings.\n- If PDF or composited image generation are part of the workflow, assistant adds the block and leaves the "source" empty. In a separate step, assistant generates a detailed request for the developer who will write the HTML.\n- Can also auto-generate HTML from a prompt (like a generate text block to generate HTML). In these cases, create a prompt with variables in the dynamicPrompt variable describing, in detail, the document to generate\n- Can either display output directly to user (foreground mode) or save the URL of the asset to a variable (background mode)',
-    inputSchema: { "type": "object", "properties": { "source": { "type": "string", "description": "The HTML or Markdown source template for the asset" }, "sourceType": { "enum": ["html", "markdown", "spa", "raw", "dynamic", "customInterface"], "type": "string", "description": "Source type: html, markdown (auto-formatted), spa (single page app), raw (pre-generated HTML in a variable), dynamic (AI-generated from prompt), or customInterface" }, "outputFormat": { "enum": ["pdf", "png", "html", "mp4", "openGraph"], "type": "string", "description": "The output format for the generated asset" }, "pageSize": { "enum": ["full", "letter", "A4", "custom"], "type": "string", "description": "Page size for PDF, PNG, or MP4 output" }, "testData": { "type": "object", "description": "Test data used for previewing the template with sample variable values" }, "options": { "type": "object", "properties": { "pageWidthPx": { "type": "number", "description": "Custom page width in pixels (for custom pageSize)" }, "pageHeightPx": { "type": "number", "description": "Custom page height in pixels (for custom pageSize)" }, "pageOrientation": { "enum": ["portrait", "landscape"], "type": "string", "description": "Page orientation for the rendered output" }, "rehostMedia": { "type": "boolean", "description": "Whether to re-host third-party images on the MindStudio CDN" }, "videoDurationSeconds": { "type": "number", "description": "Duration in seconds for MP4 video output" } }, "description": "Additional rendering options" }, "spaSource": { "type": "object", "properties": { "source": { "type": "string", "description": "Source code of the SPA (legacy, use files instead)" }, "lastCompiledSource": { "type": "string", "description": "Last compiled source (cached)" }, "files": { "type": "object", "description": "Multi-file SPA source" }, "paths": { "type": "array", "items": { "type": "string" }, "description": "Available route paths in the SPA" }, "root": { "type": "string", "description": "Root URL of the SPA bundle" }, "zipUrl": { "type": "string", "description": "URL of the zipped SPA bundle" } }, "required": ["paths", "root", "zipUrl"], "description": "Single page app source configuration (advanced)" }, "rawSource": { "type": "string", "description": "Raw HTML source stored in a variable, using handlebars syntax (e.g. {{myHtmlVariable}})" }, "dynamicPrompt": { "type": "string", "description": 'Prompt to generate the HTML dynamically when sourceType is "dynamic"' }, "dynamicSourceModelOverride": { "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", "description": "Additional model-specific configuration" } }, "required": ["model", "temperature", "maxResponseTokens"], "description": "Model override for dynamic HTML generation. Leave undefined to use the default model" }, "transitionControl": { "enum": ["default", "native"], "type": "string", "description": "Controls how the step transitions after displaying in foreground mode" }, "shareControl": { "enum": ["default", "hidden"], "type": "string", "description": "Controls visibility of the share button on displayed assets" }, "shareImageUrl": { "type": "string", "description": "URL of a custom Open Graph share image" }, "skipAssetCreation": { "type": "boolean", "description": "If true, the asset will not appear in the user's asset history" } }, "required": ["source", "sourceType", "outputFormat", "pageSize", "testData"] },
+    inputSchema: { "type": "object", "properties": { "source": { "type": "string", "description": "The HTML or Markdown source template for the asset" }, "sourceType": { "enum": ["html", "markdown", "spa", "raw", "dynamic", "customInterface"], "type": "string", "description": "Source type: html, markdown (auto-formatted), spa (single page app), raw (pre-generated HTML in a variable), dynamic (AI-generated from prompt), or customInterface" }, "outputFormat": { "enum": ["pdf", "png", "html", "mp4", "openGraph"], "type": "string", "description": "The output format for the generated asset" }, "pageSize": { "enum": ["full", "letter", "A4", "custom"], "type": "string", "description": "Page size for PDF, PNG, or MP4 output" }, "testData": { "type": "object", "description": "Test data used for previewing the template with sample variable values" }, "options": { "type": "object", "properties": { "pageWidthPx": { "type": "number", "description": "Custom page width in pixels (for custom pageSize)" }, "pageHeightPx": { "type": "number", "description": "Custom page height in pixels (for custom pageSize)" }, "pageOrientation": { "enum": ["portrait", "landscape"], "type": "string", "description": "Page orientation for the rendered output" }, "rehostMedia": { "type": "boolean", "description": "Whether to re-host third-party images on the MindStudio CDN" }, "videoDurationSeconds": { "type": "number", "description": "Duration in seconds for MP4 video output" } }, "description": "Additional rendering options" }, "spaSource": { "type": "object", "properties": { "source": { "type": "string", "description": "Source code of the SPA (legacy, use files instead)" }, "lastCompiledSource": { "type": "string", "description": "Last compiled source (cached)" }, "files": { "type": "object", "description": "Multi-file SPA source" }, "paths": { "type": "array", "items": { "type": "string" }, "description": "Available route paths in the SPA" }, "root": { "type": "string", "description": "Root URL of the SPA bundle" }, "zipUrl": { "type": "string", "description": "URL of the zipped SPA bundle" } }, "required": ["paths", "root", "zipUrl"], "description": "Single page app source configuration (advanced)" }, "rawSource": { "type": "string", "description": "Raw HTML source stored in a variable, using handlebars syntax (e.g. {{myHtmlVariable}})" }, "dynamicPrompt": { "type": "string", "description": 'Prompt to generate the HTML dynamically when sourceType is "dynamic"' }, "dynamicSourceModelOverride": { "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", "description": "Additional model-specific configuration" } }, "required": ["model", "temperature", "maxResponseTokens"], "description": "Model override for dynamic HTML generation. Leave undefined to use the default model" }, "transitionControl": { "enum": ["default", "native"], "type": "string", "description": "Controls how the step transitions after displaying in foreground mode" }, "shareControl": { "enum": ["default", "hidden"], "type": "string", "description": "Controls visibility of the share button on displayed assets" }, "shareImageUrl": { "type": "string", "description": "URL of a custom Open Graph share image" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["source", "sourceType", "outputFormat", "pageSize", "testData"] },
     outputSchema: { "type": "object", "properties": { "url": { "type": "string", "description": "CDN URL of the generated asset (PDF, PNG, HTML, or MP4 depending on outputFormat)" } }, "required": ["url"] }
   },
   "generateChart": {
@@ -1506,28 +3154,28 @@ var stepMetadata = {
     stepType: "generateImage",
     description: "Generate an image from a text prompt using an AI model.",
     usageNotes: "- Prompts should be descriptive but concise (roughly 3\u20136 sentences).\n- Images are automatically hosted on a CDN.\n- In foreground mode, the image is displayed to the user. In background mode, the URL is saved to a variable.\n- When generateVariants is true with numVariants > 1, multiple images are generated in parallel.\n- In direct execution, foreground mode behaves as background, and userSelect variant behavior behaves as saveAll.",
-    inputSchema: { "type": "object", "properties": { "prompt": { "type": "string", "description": "Text prompt describing the image to generate" }, "skipAssetCreation": { "type": "boolean", "description": "If true, the image will not appear in the user's asset history" }, "imageModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": "Image generation model identifier" }, "config": { "type": "object", "description": "Additional model-specific configuration" } }, "required": ["model"], "description": "Optional model configuration override. Uses the workflow's default image model if not specified" }, "generateVariants": { "type": "boolean", "description": "Whether to generate multiple image variants in parallel" }, "numVariants": { "type": "number", "description": "Number of variants to generate (max 10)" }, "addWatermark": { "type": "boolean", "description": "Whether to add a MindStudio watermark to the generated image" } }, "required": ["prompt"] },
+    inputSchema: { "type": "object", "properties": { "prompt": { "type": "string", "description": "Text prompt describing the image to generate" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" }, "imageModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": "Image generation model identifier" }, "config": { "type": "object", "description": "Additional model-specific configuration" } }, "required": ["model"], "description": "Optional model configuration override. Uses the workflow's default image model if not specified" }, "generateVariants": { "type": "boolean", "description": "Whether to generate multiple image variants in parallel" }, "numVariants": { "type": "number", "description": "Number of variants to generate (max 10)" }, "addWatermark": { "type": "boolean", "description": "Whether to add a MindStudio watermark to the generated image" } }, "required": ["prompt"] },
     outputSchema: { "type": "object", "properties": { "imageUrl": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] } }, "required": ["imageUrl"] }
   },
   "generateLipsync": {
     stepType: "generateLipsync",
     description: "Generate a lip sync video from provided audio and image.",
     usageNotes: "- In foreground mode, the video is displayed to the user. In background mode, the URL is saved to a variable.",
-    inputSchema: { "type": "object", "properties": { "skipAssetCreation": { "type": "boolean", "description": "If true, the generated video will not appear in the user's asset history" }, "addWatermark": { "type": "boolean", "description": "Whether to add a MindStudio watermark to the generated video" }, "lipsyncModelOverride": { "type": "object", "properties": { "model": { "type": "string" }, "config": { "type": "object" } }, "required": ["model"], "description": "Optional model configuration override. Uses the workflow's default lipsync model if not specified" } } },
+    inputSchema: { "type": "object", "properties": { "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" }, "addWatermark": { "type": "boolean", "description": "Whether to add a MindStudio watermark to the generated video" }, "lipsyncModelOverride": { "type": "object", "properties": { "model": { "type": "string" }, "config": { "type": "object" } }, "required": ["model"], "description": "Optional model configuration override. Uses the workflow's default lipsync model if not specified" } } },
     outputSchema: { "description": "This step does not produce output data." }
   },
   "generateMusic": {
     stepType: "generateMusic",
     description: "Generate an audio file from provided instructions (text) using a music model.",
     usageNotes: "- The text field contains the instructions (prompt) for the music generation.\n- In foreground mode, the audio is displayed to the user. In background mode, the URL is saved to a variable.",
-    inputSchema: { "type": "object", "properties": { "text": { "type": "string", "description": "The instructions (prompt) for the music generation" }, "skipAssetCreation": { "type": "boolean", "description": "If true, the generated audio will not appear in the user's asset history" }, "musicModelOverride": { "type": "object", "properties": { "model": { "type": "string" }, "config": { "type": "object" } }, "required": ["model"], "description": "Optional model configuration override. Uses the workflow's default music model if not specified" } }, "required": ["text"] },
+    inputSchema: { "type": "object", "properties": { "text": { "type": "string", "description": "The instructions (prompt) for the music generation" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" }, "musicModelOverride": { "type": "object", "properties": { "model": { "type": "string" }, "config": { "type": "object" } }, "required": ["model"], "description": "Optional model configuration override. Uses the workflow's default music model if not specified" } }, "required": ["text"] },
     outputSchema: { "description": "This step does not produce output data." }
   },
   "generatePdf": {
     stepType: "generatePdf",
     description: "Generate an HTML asset and export it as a webpage, PDF, or image",
     usageNotes: '- Agents can generate HTML documents and export as webpage, PDFs, images, or videos. They do this by using the "generatePdf" block, which defines an HTML page with variables, and then the generation process renders the page to create the output and save its URL at the specified variable.\n- The template for the HTML page is generated by a separate process, and it can only use variables that have already been defined in the workflow at the time of its execution. It has full access to handlebars to render the HTML template, including a handlebars helper to render a markdown variable string as HTML (which can be useful for creating templates that render long strings). The template can also create its own simple JavaScript to do things like format dates and strings.\n- If PDF or composited image generation are part of the workflow, assistant adds the block and leaves the "source" empty. In a separate step, assistant generates a detailed request for the developer who will write the HTML.\n- Can also auto-generate HTML from a prompt (like a generate text block to generate HTML). In these cases, create a prompt with variables in the dynamicPrompt variable describing, in detail, the document to generate\n- Can either display output directly to user (foreground mode) or save the URL of the asset to a variable (background mode)',
-    inputSchema: { "type": "object", "properties": { "source": { "type": "string", "description": "The HTML or Markdown source template for the asset" }, "sourceType": { "enum": ["html", "markdown", "spa", "raw", "dynamic", "customInterface"], "type": "string", "description": "Source type: html, markdown (auto-formatted), spa (single page app), raw (pre-generated HTML in a variable), dynamic (AI-generated from prompt), or customInterface" }, "outputFormat": { "enum": ["pdf", "png", "html", "mp4", "openGraph"], "type": "string", "description": "The output format for the generated asset" }, "pageSize": { "enum": ["full", "letter", "A4", "custom"], "type": "string", "description": "Page size for PDF, PNG, or MP4 output" }, "testData": { "type": "object", "description": "Test data used for previewing the template with sample variable values" }, "options": { "type": "object", "properties": { "pageWidthPx": { "type": "number", "description": "Custom page width in pixels (for custom pageSize)" }, "pageHeightPx": { "type": "number", "description": "Custom page height in pixels (for custom pageSize)" }, "pageOrientation": { "enum": ["portrait", "landscape"], "type": "string", "description": "Page orientation for the rendered output" }, "rehostMedia": { "type": "boolean", "description": "Whether to re-host third-party images on the MindStudio CDN" }, "videoDurationSeconds": { "type": "number", "description": "Duration in seconds for MP4 video output" } }, "description": "Additional rendering options" }, "spaSource": { "type": "object", "properties": { "source": { "type": "string", "description": "Source code of the SPA (legacy, use files instead)" }, "lastCompiledSource": { "type": "string", "description": "Last compiled source (cached)" }, "files": { "type": "object", "description": "Multi-file SPA source" }, "paths": { "type": "array", "items": { "type": "string" }, "description": "Available route paths in the SPA" }, "root": { "type": "string", "description": "Root URL of the SPA bundle" }, "zipUrl": { "type": "string", "description": "URL of the zipped SPA bundle" } }, "required": ["paths", "root", "zipUrl"], "description": "Single page app source configuration (advanced)" }, "rawSource": { "type": "string", "description": "Raw HTML source stored in a variable, using handlebars syntax (e.g. {{myHtmlVariable}})" }, "dynamicPrompt": { "type": "string", "description": 'Prompt to generate the HTML dynamically when sourceType is "dynamic"' }, "dynamicSourceModelOverride": { "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", "description": "Additional model-specific configuration" } }, "required": ["model", "temperature", "maxResponseTokens"], "description": "Model override for dynamic HTML generation. Leave undefined to use the default model" }, "transitionControl": { "enum": ["default", "native"], "type": "string", "description": "Controls how the step transitions after displaying in foreground mode" }, "shareControl": { "enum": ["default", "hidden"], "type": "string", "description": "Controls visibility of the share button on displayed assets" }, "shareImageUrl": { "type": "string", "description": "URL of a custom Open Graph share image" }, "skipAssetCreation": { "type": "boolean", "description": "If true, the asset will not appear in the user's asset history" } }, "required": ["source", "sourceType", "outputFormat", "pageSize", "testData"] },
+    inputSchema: { "type": "object", "properties": { "source": { "type": "string", "description": "The HTML or Markdown source template for the asset" }, "sourceType": { "enum": ["html", "markdown", "spa", "raw", "dynamic", "customInterface"], "type": "string", "description": "Source type: html, markdown (auto-formatted), spa (single page app), raw (pre-generated HTML in a variable), dynamic (AI-generated from prompt), or customInterface" }, "outputFormat": { "enum": ["pdf", "png", "html", "mp4", "openGraph"], "type": "string", "description": "The output format for the generated asset" }, "pageSize": { "enum": ["full", "letter", "A4", "custom"], "type": "string", "description": "Page size for PDF, PNG, or MP4 output" }, "testData": { "type": "object", "description": "Test data used for previewing the template with sample variable values" }, "options": { "type": "object", "properties": { "pageWidthPx": { "type": "number", "description": "Custom page width in pixels (for custom pageSize)" }, "pageHeightPx": { "type": "number", "description": "Custom page height in pixels (for custom pageSize)" }, "pageOrientation": { "enum": ["portrait", "landscape"], "type": "string", "description": "Page orientation for the rendered output" }, "rehostMedia": { "type": "boolean", "description": "Whether to re-host third-party images on the MindStudio CDN" }, "videoDurationSeconds": { "type": "number", "description": "Duration in seconds for MP4 video output" } }, "description": "Additional rendering options" }, "spaSource": { "type": "object", "properties": { "source": { "type": "string", "description": "Source code of the SPA (legacy, use files instead)" }, "lastCompiledSource": { "type": "string", "description": "Last compiled source (cached)" }, "files": { "type": "object", "description": "Multi-file SPA source" }, "paths": { "type": "array", "items": { "type": "string" }, "description": "Available route paths in the SPA" }, "root": { "type": "string", "description": "Root URL of the SPA bundle" }, "zipUrl": { "type": "string", "description": "URL of the zipped SPA bundle" } }, "required": ["paths", "root", "zipUrl"], "description": "Single page app source configuration (advanced)" }, "rawSource": { "type": "string", "description": "Raw HTML source stored in a variable, using handlebars syntax (e.g. {{myHtmlVariable}})" }, "dynamicPrompt": { "type": "string", "description": 'Prompt to generate the HTML dynamically when sourceType is "dynamic"' }, "dynamicSourceModelOverride": { "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", "description": "Additional model-specific configuration" } }, "required": ["model", "temperature", "maxResponseTokens"], "description": "Model override for dynamic HTML generation. Leave undefined to use the default model" }, "transitionControl": { "enum": ["default", "native"], "type": "string", "description": "Controls how the step transitions after displaying in foreground mode" }, "shareControl": { "enum": ["default", "hidden"], "type": "string", "description": "Controls visibility of the share button on displayed assets" }, "shareImageUrl": { "type": "string", "description": "URL of a custom Open Graph share image" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["source", "sourceType", "outputFormat", "pageSize", "testData"] },
     outputSchema: { "type": "object", "properties": { "url": { "type": "string", "description": "CDN URL of the generated asset (PDF, PNG, HTML, or MP4 depending on outputFormat)" } }, "required": ["url"] }
   },
   "generateStaticVideoFromImage": {
@@ -1551,7 +3199,7 @@ var stepMetadata = {
     stepType: "generateVideo",
     description: "Generate a video from a text prompt using an AI model.",
     usageNotes: "- Prompts should be descriptive but concise (roughly 3\u20136 sentences).\n- Videos are automatically hosted on a CDN.\n- In foreground mode, the video is displayed to the user. In background mode, the URL is saved to a variable.\n- When generateVariants is true with numVariants > 1, multiple videos are generated in parallel.\n- In direct execution, foreground mode behaves as background, and userSelect variant behavior behaves as saveAll.",
-    inputSchema: { "type": "object", "properties": { "prompt": { "type": "string", "description": "Text prompt describing the video to generate" }, "skipAssetCreation": { "type": "boolean", "description": "If true, the video will not appear in the user's asset history" }, "videoModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": "Video generation model identifier" }, "config": { "type": "object", "description": "Additional model-specific configuration" } }, "required": ["model"], "description": "Optional model configuration override. Uses the workflow's default video model if not specified" }, "generateVariants": { "type": "boolean", "description": "Whether to generate multiple video variants in parallel" }, "numVariants": { "type": "number", "description": "Number of variants to generate (max 10)" }, "addWatermark": { "type": "boolean", "description": "Whether to add a MindStudio watermark to the generated video" } }, "required": ["prompt"] },
+    inputSchema: { "type": "object", "properties": { "prompt": { "type": "string", "description": "Text prompt describing the video to generate" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" }, "videoModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": "Video generation model identifier" }, "config": { "type": "object", "description": "Additional model-specific configuration" } }, "required": ["model"], "description": "Optional model configuration override. Uses the workflow's default video model if not specified" }, "generateVariants": { "type": "boolean", "description": "Whether to generate multiple video variants in parallel" }, "numVariants": { "type": "number", "description": "Number of variants to generate (max 10)" }, "addWatermark": { "type": "boolean", "description": "Whether to add a MindStudio watermark to the generated video" } }, "required": ["prompt"] },
     outputSchema: { "type": "object", "properties": { "videoUrl": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] } }, "required": ["videoUrl"] }
   },
   "getGmailAttachments": {
@@ -1691,14 +3339,14 @@ var stepMetadata = {
     stepType: "imageRemoveWatermark",
     description: "Remove watermarks from an image using AI.",
     usageNotes: "- Output is re-hosted on the CDN as a PNG.",
-    inputSchema: { "type": "object", "properties": { "imageUrl": { "type": "string", "description": "URL of the image to remove the watermark from" }, "engine": { "type": "string", "description": "Watermark removal engine to use" }, "skipAssetCreation": { "type": "boolean", "description": "When true, the result will not appear in the user's asset history" } }, "required": ["imageUrl", "engine"] },
+    inputSchema: { "type": "object", "properties": { "imageUrl": { "type": "string", "description": "URL of the image to remove the watermark from" }, "engine": { "type": "string", "description": "Watermark removal engine to use" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["imageUrl", "engine"] },
     outputSchema: { "type": "object", "properties": { "imageUrl": { "type": "string", "description": "CDN URL of the processed image with watermark removed (PNG)" } }, "required": ["imageUrl"] }
   },
   "insertVideoClips": {
     stepType: "insertVideoClips",
     description: "Insert b-roll clips into a base video at a timecode, optionally with an xfade transition.",
     usageNotes: "",
-    inputSchema: { "type": "object", "properties": { "baseVideoUrl": { "type": "string", "description": "URL of the base video to insert clips into" }, "overlayVideos": { "type": "array", "items": { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the overlay video clip" }, "startTimeSec": { "type": "number", "description": "Timecode in seconds at which to insert this clip" } }, "required": ["videoUrl", "startTimeSec"] }, "description": "Array of overlay clips to insert at specified timecodes" }, "transition": { "type": "string", "description": "Optional xfade transition effect name between clips" }, "transitionDuration": { "type": "number", "description": "Duration of the transition in seconds" }, "useOverlayAudio": { "type": "boolean", "description": "When true, uses audio from the overlay clips instead of the base video audio during inserts" }, "skipAssetCreation": { "type": "boolean", "description": "When true, the result will not appear in the user's asset history. Useful for intermediate compositing steps." } }, "required": ["baseVideoUrl", "overlayVideos"] },
+    inputSchema: { "type": "object", "properties": { "baseVideoUrl": { "type": "string", "description": "URL of the base video to insert clips into" }, "overlayVideos": { "type": "array", "items": { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the overlay video clip" }, "startTimeSec": { "type": "number", "description": "Timecode in seconds at which to insert this clip" } }, "required": ["videoUrl", "startTimeSec"] }, "description": "Array of overlay clips to insert at specified timecodes" }, "transition": { "type": "string", "description": "Optional xfade transition effect name between clips" }, "transitionDuration": { "type": "number", "description": "Duration of the transition in seconds" }, "useOverlayAudio": { "type": "boolean", "description": "When true, uses audio from the overlay clips instead of the base video audio during inserts" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["baseVideoUrl", "overlayVideos"] },
     outputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the video with clips inserted" } }, "required": ["videoUrl"] }
   },
   "listDataSources": {
@@ -1765,28 +3413,28 @@ var stepMetadata = {
     stepType: "mergeAudio",
     description: "Merge one or more clips into a single audio file.",
     usageNotes: "",
-    inputSchema: { "type": "object", "properties": { "mp3Urls": { "type": "array", "items": { "type": "string" }, "description": "URLs of the MP3 audio clips to merge in order" }, "fileMetadata": { "type": "object", "description": "FFmpeg MP3 metadata key-value pairs to embed in the output file" }, "albumArtUrl": { "type": "string", "description": "URL of an image to embed as album art in the output file" }, "skipAssetCreation": { "type": "boolean", "description": "When true, the result will not appear in the user's asset history. Useful for intermediate compositing steps." } }, "required": ["mp3Urls"] },
+    inputSchema: { "type": "object", "properties": { "mp3Urls": { "type": "array", "items": { "type": "string" }, "description": "URLs of the MP3 audio clips to merge in order" }, "fileMetadata": { "type": "object", "description": "FFmpeg MP3 metadata key-value pairs to embed in the output file" }, "albumArtUrl": { "type": "string", "description": "URL of an image to embed as album art in the output file" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["mp3Urls"] },
     outputSchema: { "type": "object", "properties": { "audioUrl": { "type": "string", "description": "URL of the merged audio file" } }, "required": ["audioUrl"] }
   },
   "mergeVideos": {
     stepType: "mergeVideos",
     description: "Merge one or more clips into a single video.",
     usageNotes: "",
-    inputSchema: { "type": "object", "properties": { "videoUrls": { "type": "array", "items": { "type": "string" }, "description": "URLs of the video clips to merge in order" }, "transition": { "type": "string", "description": "Optional xfade transition effect name" }, "transitionDuration": { "type": "number", "description": "Duration of the transition in seconds" }, "skipAssetCreation": { "type": "boolean", "description": "When true, the result will not appear in the user's asset history. Useful for intermediate compositing steps." } }, "required": ["videoUrls"] },
+    inputSchema: { "type": "object", "properties": { "videoUrls": { "type": "array", "items": { "type": "string" }, "description": "URLs of the video clips to merge in order" }, "transition": { "type": "string", "description": "Optional xfade transition effect name" }, "transitionDuration": { "type": "number", "description": "Duration of the transition in seconds" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["videoUrls"] },
     outputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the merged video" } }, "required": ["videoUrl"] }
   },
   "mixAudioIntoVideo": {
     stepType: "mixAudioIntoVideo",
     description: "Mix an audio track into a video",
     usageNotes: "",
-    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video" }, "audioUrl": { "type": "string", "description": "URL of the audio track to mix into the video" }, "options": { "type": "object", "properties": { "keepVideoAudio": { "type": "boolean", "description": "When true, preserves the original video audio alongside the new track. Defaults to false." }, "audioGainDb": { "type": "number", "description": "Volume adjustment for the new audio track in decibels. Defaults to 0." }, "videoGainDb": { "type": "number", "description": "Volume adjustment for the existing video audio in decibels. Defaults to 0." }, "loopAudio": { "type": "boolean", "description": "When true, loops the audio track to match the video duration. Defaults to false." } }, "description": "Audio mixing options" }, "skipAssetCreation": { "type": "boolean", "description": "When true, the result will not appear in the user's asset history. Useful for intermediate compositing steps." } }, "required": ["videoUrl", "audioUrl", "options"] },
+    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video" }, "audioUrl": { "type": "string", "description": "URL of the audio track to mix into the video" }, "options": { "type": "object", "properties": { "keepVideoAudio": { "type": "boolean", "description": "When true, preserves the original video audio alongside the new track. Defaults to false." }, "audioGainDb": { "type": "number", "description": "Volume adjustment for the new audio track in decibels. Defaults to 0." }, "videoGainDb": { "type": "number", "description": "Volume adjustment for the existing video audio in decibels. Defaults to 0." }, "loopAudio": { "type": "boolean", "description": "When true, loops the audio track to match the video duration. Defaults to false." } }, "description": "Audio mixing options" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["videoUrl", "audioUrl", "options"] },
     outputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the video with the mixed audio track" } }, "required": ["videoUrl"] }
   },
   "muteVideo": {
     stepType: "muteVideo",
     description: "Mute a video file",
     usageNotes: "",
-    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video to mute" }, "skipAssetCreation": { "type": "boolean", "description": "When true, the result will not appear in the user's asset history. Useful for intermediate compositing steps." } }, "required": ["videoUrl"] },
+    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video to mute" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["videoUrl"] },
     outputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the muted video" } }, "required": ["videoUrl"] }
   },
   "n8nRunNode": {
@@ -1820,8 +3468,8 @@ var stepMetadata = {
   "postToLinkedIn": {
     stepType: "postToLinkedIn",
     description: "Create a post on LinkedIn from the connected account.",
-    usageNotes: "- Requires a LinkedIn OAuth connection (connectionId).\n- Supports text posts, image posts, and video posts.\n- Visibility controls who can see the post.",
-    inputSchema: { "type": "object", "properties": { "message": { "type": "string", "description": "The text content of the LinkedIn post" }, "visibility": { "enum": ["PUBLIC", "CONNECTIONS"], "type": "string", "description": 'Who can see the post: "PUBLIC" or "CONNECTIONS"' }, "videoUrl": { "type": "string", "description": "URL of a video to attach to the post" }, "descriptionText": { "type": "string", "description": "Description text for link/media attachments" }, "titleText": { "type": "string", "description": "Title text for link/media attachments" }, "imageUrl": { "type": "string", "description": "URL of an image to attach to the post" }, "connectionId": { "type": "string", "description": "LinkedIn OAuth connection ID" } }, "required": ["message", "visibility"] },
+    usageNotes: "- Requires a LinkedIn OAuth connection (connectionId).\n- Supports text posts, image posts, video posts, document posts, and article posts.\n- Attach one media type per post: image, video, document, or article.\n- Documents support PDF, PPT, PPTX, DOC, DOCX (max 100MB, 300 pages). Displays as a slideshow carousel.\n- Articles create a link preview with optional custom title, description, and thumbnail.\n- Visibility controls who can see the post.",
+    inputSchema: { "type": "object", "properties": { "message": { "type": "string", "description": "The text content of the LinkedIn post" }, "visibility": { "enum": ["PUBLIC", "CONNECTIONS"], "type": "string", "description": 'Who can see the post: "PUBLIC" or "CONNECTIONS"' }, "imageUrl": { "type": "string", "description": "URL of an image to attach to the post" }, "videoUrl": { "type": "string", "description": "URL of a video to attach to the post" }, "documentUrl": { "type": "string", "description": "URL of a document (PDF, PPT, DOC) to attach to the post" }, "articleUrl": { "type": "string", "description": "URL to share as an article link preview" }, "titleText": { "type": "string", "description": "Title text for media or article attachments" }, "descriptionText": { "type": "string", "description": "Description text for article attachments" }, "connectionId": { "type": "string", "description": "LinkedIn OAuth connection ID" } }, "required": ["message", "visibility"] },
     outputSchema: { "description": "This step does not produce output data." }
   },
   "postToSlackChannel": {
@@ -1845,6 +3493,13 @@ var stepMetadata = {
     inputSchema: { "type": "object", "properties": { "webhookUrl": { "type": "string", "description": "Zapier webhook URL to send data to" }, "input": { "type": "object", "description": "Key-value pairs to send as the JSON POST body" } }, "required": ["webhookUrl", "input"] },
     outputSchema: { "type": "object", "properties": { "data": { "description": "Parsed webhook response from Zapier (JSON object, array, or string)" } }, "required": ["data"] }
   },
+  "queryAppDatabase": {
+    stepType: "queryAppDatabase",
+    description: "Execute a SQL query against the app managed database.",
+    usageNotes: '- Executes raw SQL against a SQLite database managed by the app.\n- For SELECT queries, returns rows as JSON.\n- For INSERT/UPDATE/DELETE, returns the number of affected rows.\n- Use {{variables}} directly in your SQL. By default they are automatically extracted\n  and passed as safe parameterized values (preventing SQL injection).\n  Example: INSERT INTO contacts (name, comment) VALUES ({{name}}, {{comment}})\n- Full MindStudio handlebars syntax is supported, including helpers like {{json myVar}},\n  {{get myVar "$.path"}}, {{global.orgName}}, etc.\n- Set parameterize to false for raw/dynamic SQL where variables are interpolated directly\n  into the query string. Use this when another step generates full or partial SQL, e.g.\n  a bulk INSERT with a precomputed VALUES list. The user is responsible for sanitization\n  when parameterize is false.',
+    inputSchema: { "type": "object", "properties": { "databaseId": { "type": "string", "description": "Name or ID of the app data database to query" }, "sql": { "type": "string", "description": "SQL query to execute. Use {{variables}} directly in the SQL \u2014 they are handled according to the `parameterize` setting.\n\nWhen parameterize is true (default):   {{variables}} are extracted from the SQL, replaced with ? placeholders,   resolved via the full MindStudio handlebars pipeline, and passed as safe   parameterized values to SQLite. This prevents SQL injection.   Example: INSERT INTO contacts (name, email) VALUES ({{name}}, {{email}})\n\nWhen parameterize is false:   The entire SQL string is resolved via compileString (standard handlebars   interpolation) and executed as-is. Use this for dynamic/generated SQL   where another step builds the query. The user is responsible for safety.   Example: {{generatedInsertQuery}}\n\nAsk the user for the database schema if they have not already provided it." }, "parameterize": { "type": "boolean", "description": "Whether to treat {{variables}} as parameterized query values (default: true).\n\n- true:  {{vars}} are extracted, replaced with ?, and passed as bind params.          Safe from SQL injection. Use for standard CRUD operations.\n- false: {{vars}} are interpolated directly into the SQL string via handlebars.          Use when another step generates full or partial SQL (e.g. bulk inserts          with precomputed VALUES). The user is responsible for sanitization." } }, "required": ["databaseId", "sql"] },
+    outputSchema: { "type": "object", "properties": { "rows": { "type": "array", "items": {}, "description": "Result rows for SELECT queries (empty array for write queries)" }, "changes": { "type": "number", "description": "Number of rows affected by INSERT, UPDATE, or DELETE queries (0 for SELECT)" } }, "required": ["rows", "changes"] }
+  },
   "queryDataSource": {
     stepType: "queryDataSource",
     description: "Search a vector data source (RAG) and return relevant document chunks.",
@@ -1884,7 +3539,7 @@ var stepMetadata = {
     stepType: "resizeVideo",
     description: "Resize a video file",
     usageNotes: "",
-    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video to resize" }, "mode": { "enum": ["fit", "exact"], "type": "string", "description": "Resize mode: 'fit' scales within max dimensions, 'exact' forces exact dimensions" }, "maxWidth": { "type": "number", "description": "Maximum width in pixels (used with 'fit' mode)" }, "maxHeight": { "type": "number", "description": "Maximum height in pixels (used with 'fit' mode)" }, "width": { "type": "number", "description": "Exact width in pixels (used with 'exact' mode)" }, "height": { "type": "number", "description": "Exact height in pixels (used with 'exact' mode)" }, "strategy": { "enum": ["pad", "crop"], "type": "string", "description": "Strategy for handling aspect ratio mismatch in 'exact' mode" }, "skipAssetCreation": { "type": "boolean", "description": "When true, the result will not appear in the user's asset history. Useful for intermediate compositing steps." } }, "required": ["videoUrl", "mode"] },
+    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video to resize" }, "mode": { "enum": ["fit", "exact"], "type": "string", "description": "Resize mode: 'fit' scales within max dimensions, 'exact' forces exact dimensions" }, "maxWidth": { "type": "number", "description": "Maximum width in pixels (used with 'fit' mode)" }, "maxHeight": { "type": "number", "description": "Maximum height in pixels (used with 'fit' mode)" }, "width": { "type": "number", "description": "Exact width in pixels (used with 'exact' mode)" }, "height": { "type": "number", "description": "Exact height in pixels (used with 'exact' mode)" }, "strategy": { "enum": ["pad", "crop"], "type": "string", "description": "Strategy for handling aspect ratio mismatch in 'exact' mode" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["videoUrl", "mode"] },
     outputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the resized video" } }, "required": ["videoUrl"] }
   },
   "runFromConnectorRegistry": {
@@ -2180,7 +3835,7 @@ var stepMetadata = {
     stepType: "textToSpeech",
     description: "Generate an audio file from provided text using a speech model.",
     usageNotes: "- The text field contains the exact words to be spoken (not instructions).\n- In foreground mode, the audio is displayed to the user. In background mode, the URL is saved to a variable.",
-    inputSchema: { "type": "object", "properties": { "text": { "type": "string", "description": "The text to convert to speech" }, "skipAssetCreation": { "type": "boolean" }, "speechModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": "Speech synthesis model identifier" }, "config": { "type": "object", "description": "Additional model-specific configuration" } }, "required": ["model"], "description": "Optional model configuration override. Uses the workflow's default speech model if not specified" } }, "required": ["text"] },
+    inputSchema: { "type": "object", "properties": { "text": { "type": "string", "description": "The text to convert to speech" }, "intermediateAsset": { "type": "boolean" }, "speechModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": "Speech synthesis model identifier" }, "config": { "type": "object", "description": "Additional model-specific configuration" } }, "required": ["model"], "description": "Optional model configuration override. Uses the workflow's default speech model if not specified" } }, "required": ["text"] },
     outputSchema: { "type": "object", "properties": { "audioUrl": { "type": "string", "description": "URL of the generated audio file" } }, "required": ["audioUrl"] }
   },
   "transcribeAudio": {
@@ -2194,7 +3849,7 @@ var stepMetadata = {
     stepType: "trimMedia",
     description: "Trim an audio or video clip",
     usageNotes: "",
-    inputSchema: { "type": "object", "properties": { "inputUrl": { "type": "string", "description": "URL of the source audio or video file to trim" }, "start": { "type": ["number", "string"] }, "duration": { "type": ["string", "number"] }, "skipAssetCreation": { "type": "boolean", "description": "When true, the result will not appear in the user's asset history. Useful for intermediate compositing steps." } }, "required": ["inputUrl"] },
+    inputSchema: { "type": "object", "properties": { "inputUrl": { "type": "string", "description": "URL of the source audio or video file to trim" }, "start": { "type": ["number", "string"] }, "duration": { "type": ["string", "number"] }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["inputUrl"] },
     outputSchema: { "type": "object", "properties": { "mediaUrl": { "type": "string", "description": "URL of the trimmed media file" } }, "required": ["mediaUrl"] }
   },
   "updateGmailLabels": {
@@ -2243,7 +3898,7 @@ var stepMetadata = {
     stepType: "upscaleVideo",
     description: "Upscale a video file",
     usageNotes: "",
-    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video to upscale" }, "targetResolution": { "enum": ["720p", "1080p", "2K", "4K"], "type": "string", "description": "Target output resolution for the upscaled video" }, "engine": { "enum": ["standard", "pro", "ultimate", "flashvsr", "seedance", "seedvr2", "runwayml/upscale-v1"], "type": "string", "description": "Upscaling engine to use. Higher tiers produce better quality at higher cost." }, "skipAssetCreation": { "type": "boolean", "description": "When true, the result will not appear in the user's asset history. Useful for intermediate compositing steps." } }, "required": ["videoUrl", "targetResolution", "engine"] },
+    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video to upscale" }, "targetResolution": { "enum": ["720p", "1080p", "2K", "4K"], "type": "string", "description": "Target output resolution for the upscaled video" }, "engine": { "enum": ["standard", "pro", "ultimate", "flashvsr", "seedance", "seedvr2", "runwayml/upscale-v1"], "type": "string", "description": "Upscaling engine to use. Higher tiers produce better quality at higher cost." }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["videoUrl", "targetResolution", "engine"] },
     outputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the upscaled video" } }, "required": ["videoUrl"] }
   },
   "userMessage": {
@@ -2260,46 +3915,86 @@ var stepMetadata = {
     stepType: "videoFaceSwap",
     description: "Swap faces in a video file",
     usageNotes: "",
-    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video containing faces to swap" }, "faceImageUrl": { "type": "string", "description": "URL of the image containing the replacement face" }, "targetIndex": { "type": "number", "description": "Zero-based index of the face to replace in the video" }, "engine": { "type": "string", "description": "Face swap engine to use" }, "skipAssetCreation": { "type": "boolean", "description": "When true, the result will not appear in the user's asset history. Useful for intermediate compositing steps." } }, "required": ["videoUrl", "faceImageUrl", "targetIndex", "engine"] },
+    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video containing faces to swap" }, "faceImageUrl": { "type": "string", "description": "URL of the image containing the replacement face" }, "targetIndex": { "type": "number", "description": "Zero-based index of the face to replace in the video" }, "engine": { "type": "string", "description": "Face swap engine to use" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["videoUrl", "faceImageUrl", "targetIndex", "engine"] },
     outputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the face-swapped video" } }, "required": ["videoUrl"] }
   },
   "videoRemoveBackground": {
     stepType: "videoRemoveBackground",
     description: "Remove or replace background from a video",
     usageNotes: "",
-    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video" }, "newBackground": { "enum": ["transparent", "image"], "type": "string", "description": "Whether to make the background transparent or replace it with an image" }, "newBackgroundImageUrl": { "type": "string", "description": "URL of a replacement background image. Required when newBackground is 'image'." }, "engine": { "type": "string", "description": "Background removal engine to use" }, "skipAssetCreation": { "type": "boolean", "description": "When true, the result will not appear in the user's asset history. Useful for intermediate compositing steps." } }, "required": ["videoUrl", "newBackground", "engine"] },
+    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video" }, "newBackground": { "enum": ["transparent", "image"], "type": "string", "description": "Whether to make the background transparent or replace it with an image" }, "newBackgroundImageUrl": { "type": "string", "description": "URL of a replacement background image. Required when newBackground is 'image'." }, "engine": { "type": "string", "description": "Background removal engine to use" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["videoUrl", "newBackground", "engine"] },
     outputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the video with background removed or replaced" } }, "required": ["videoUrl"] }
   },
   "videoRemoveWatermark": {
     stepType: "videoRemoveWatermark",
     description: "Remove a watermark from a video",
     usageNotes: "",
-    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video containing a watermark" }, "engine": { "type": "string", "description": "Watermark removal engine to use" }, "skipAssetCreation": { "type": "boolean", "description": "When true, the result will not appear in the user's asset history. Useful for intermediate compositing steps." } }, "required": ["videoUrl", "engine"] },
+    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video containing a watermark" }, "engine": { "type": "string", "description": "Watermark removal engine to use" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["videoUrl", "engine"] },
     outputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the video with watermark removed" } }, "required": ["videoUrl"] }
   },
   "watermarkImage": {
     stepType: "watermarkImage",
     description: "Overlay a watermark image onto another image.",
     usageNotes: "- The watermark is placed at the specified corner with configurable padding and width.",
-    inputSchema: { "type": "object", "properties": { "imageUrl": { "type": "string", "description": "URL of the base image" }, "watermarkImageUrl": { "type": "string", "description": "URL of the watermark image to overlay" }, "corner": { "enum": ["top-left", "top-right", "bottom-left", "bottom-right"], "type": "string", "description": "Corner position for the watermark placement" }, "paddingPx": { "type": "number", "description": "Padding from the corner in pixels" }, "widthPx": { "type": "number", "description": "Width of the watermark overlay in pixels" }, "skipAssetCreation": { "type": "boolean", "description": "When true, the result will not appear in the user's asset history" } }, "required": ["imageUrl", "watermarkImageUrl", "corner", "paddingPx", "widthPx"] },
+    inputSchema: { "type": "object", "properties": { "imageUrl": { "type": "string", "description": "URL of the base image" }, "watermarkImageUrl": { "type": "string", "description": "URL of the watermark image to overlay" }, "corner": { "enum": ["top-left", "top-right", "bottom-left", "bottom-right"], "type": "string", "description": "Corner position for the watermark placement" }, "paddingPx": { "type": "number", "description": "Padding from the corner in pixels" }, "widthPx": { "type": "number", "description": "Width of the watermark overlay in pixels" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["imageUrl", "watermarkImageUrl", "corner", "paddingPx", "widthPx"] },
     outputSchema: { "type": "object", "properties": { "imageUrl": { "type": "string", "description": "CDN URL of the watermarked image" } }, "required": ["imageUrl"] }
   },
   "watermarkVideo": {
     stepType: "watermarkVideo",
     description: "Add an image watermark to a video",
     usageNotes: "",
-    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video" }, "imageUrl": { "type": "string", "description": "URL of the watermark image to overlay" }, "corner": { "enum": ["top-left", "top-right", "bottom-left", "bottom-right"], "type": "string", "description": "Corner position for the watermark placement" }, "paddingPx": { "type": "number", "description": "Padding from the corner in pixels" }, "widthPx": { "type": "number", "description": "Width of the watermark overlay in pixels" }, "skipAssetCreation": { "type": "boolean", "description": "When true, the result will not appear in the user's asset history. Useful for intermediate compositing steps." } }, "required": ["videoUrl", "imageUrl", "corner", "paddingPx", "widthPx"] },
+    inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the source video" }, "imageUrl": { "type": "string", "description": "URL of the watermark image to overlay" }, "corner": { "enum": ["top-left", "top-right", "bottom-left", "bottom-right"], "type": "string", "description": "Corner position for the watermark placement" }, "paddingPx": { "type": "number", "description": "Padding from the corner in pixels" }, "widthPx": { "type": "number", "description": "Width of the watermark overlay in pixels" }, "intermediateAsset": { "type": "boolean", "description": "When true, the asset is created but hidden from the user's gallery (tagged as intermediate)" } }, "required": ["videoUrl", "imageUrl", "corner", "paddingPx", "widthPx"] },
     outputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "URL of the watermarked video" } }, "required": ["videoUrl"] }
   }
 };
 
 // src/index.ts
 var MindStudioAgent2 = MindStudioAgent;
+var _default;
+var mindstudio = new Proxy(
+  {},
+  {
+    get(_, prop, receiver) {
+      _default ??= new MindStudioAgent2();
+      const value = Reflect.get(_default, prop, _default);
+      return typeof value === "function" ? value.bind(_default) : value;
+    }
+  }
+);
+var index_default = mindstudio;
+var auth = new Proxy(
+  {},
+  {
+    get(_, prop) {
+      const target = mindstudio.auth;
+      const value = Reflect.get(target, prop, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  }
+);
+var db = new Proxy(
+  {},
+  {
+    get(_, prop) {
+      const target = mindstudio.db;
+      const value = Reflect.get(target, prop, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  }
+);
+var resolveUser = (userId) => mindstudio.resolveUser(userId);
 export {
+  AuthContext,
   MindStudioAgent2 as MindStudioAgent,
   MindStudioError,
+  Roles,
+  auth,
   blockTypeAliases,
+  db,
+  index_default as default,
+  mindstudio,
   monacoSnippets,
+  resolveUser,
   stepMetadata
 };
 //# sourceMappingURL=index.js.map