@mindstudio-ai/agent 0.1.102 → 0.1.104

package/dist/index.js

@@ -462,6 +462,59 @@ function buildSelect(table, options = {}) {
   if (options.offset != null) sql += ` OFFSET ${options.offset}`;
   return { sql, params: params.length > 0 ? params : void 0 };
 }
+var SQL_IDENTIFIER_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+function assertSqlIdentifier(name, context) {
+  if (!SQL_IDENTIFIER_RE.test(name)) {
+    throw new MindStudioError(
+      `Invalid ${context}: "${name}" \u2014 must be a plain identifier (letters, digits, _ and $, not starting with a digit).`,
+      "invalid_identifier",
+      400
+    );
+  }
+}
+function aggregateExpr(fn, column) {
+  switch (fn) {
+    case "count":
+      return "COUNT(*)";
+    case "sum":
+      return `TOTAL(${column})`;
+    case "avg":
+      return `AVG(${column})`;
+    case "min":
+      return `MIN(${column})`;
+    case "max":
+      return `MAX(${column})`;
+    case "countDistinct":
+      return `COUNT(DISTINCT ${column})`;
+  }
+}
+function buildScalarAggregate(table, fn, column, where, whereParams) {
+  if (column != null) assertSqlIdentifier(column, "aggregate column");
+  let sql = `SELECT ${aggregateExpr(fn, column ?? void 0)} AS value FROM ${table}`;
+  if (where) sql += ` WHERE ${where}`;
+  return { sql, params: whereParams?.length ? whereParams : void 0 };
+}
+function buildGroupedAggregate(table, options) {
+  for (const col of options.by) assertSqlIdentifier(col, "group-by column");
+  for (const term of options.select) {
+    assertSqlIdentifier(term.alias, "aggregate alias");
+    if (term.column != null) assertSqlIdentifier(term.column, "aggregate column");
+  }
+  if (options.orderBy != null) assertSqlIdentifier(options.orderBy, "aggregate order key");
+  const selectList = [
+    ...options.by,
+    ...options.select.map((t) => `${aggregateExpr(t.fn, t.column)} AS ${t.alias}`)
+  ].join(", ");
+  let sql = `SELECT ${selectList} FROM ${table}`;
+  if (options.where) sql += ` WHERE ${options.where}`;
+  if (options.by.length > 0) sql += ` GROUP BY ${options.by.join(", ")}`;
+  if (options.orderBy) sql += ` ORDER BY ${options.orderBy}${options.desc ? " DESC" : " ASC"}`;
+  if (options.limit != null) sql += ` LIMIT ${options.limit}`;
+  return {
+    sql,
+    params: options.whereParams?.length ? options.whereParams : void 0
+  };
+}
 function buildExists(table, where, whereParams, negate) {
   const inner = where ? `SELECT 1 FROM ${table} WHERE ${where}` : `SELECT 1 FROM ${table}`;
   const fn = negate ? "NOT EXISTS" : "EXISTS";
@@ -1119,6 +1172,187 @@ function isComparisonOp(value) {
   return value in JS_TO_SQL_OP;
 }
 
+// src/db/aggregate.ts
+var IDENTIFIER_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+var AGGREGATE_FNS = [
+  "count",
+  "sum",
+  "avg",
+  "min",
+  "max",
+  "countDistinct"
+];
+function normalizeAggregateSpec(spec) {
+  const by = [...spec.by ?? []];
+  for (const col of by) {
+    if (typeof col !== "string" || !IDENTIFIER_RE.test(col)) {
+      throw new MindStudioError(
+        `aggregate(): invalid group-by column "${col}" \u2014 column names are plain identifiers.`,
+        "invalid_column",
+        400
+      );
+    }
+  }
+  const aliases = Object.keys(spec.select ?? {});
+  if (aliases.length === 0) {
+    throw new MindStudioError(
+      "aggregate(): select must contain at least one aggregate, e.g. { n: { count: true } }.",
+      "invalid_aggregate_spec",
+      400
+    );
+  }
+  const select = aliases.map((alias) => {
+    if (!IDENTIFIER_RE.test(alias)) {
+      throw new MindStudioError(
+        `aggregate(): invalid alias "${alias}" \u2014 result property names are plain identifiers.`,
+        "invalid_aggregate_alias",
+        400
+      );
+    }
+    if (by.includes(alias)) {
+      throw new MindStudioError(
+        `aggregate(): alias "${alias}" collides with a group-by column of the same name.`,
+        "invalid_aggregate_alias",
+        400
+      );
+    }
+    const term = spec.select[alias];
+    const fns = AGGREGATE_FNS.filter((fn2) => term && fn2 in term);
+    if (fns.length !== 1) {
+      throw new MindStudioError(
+        `aggregate(): term "${alias}" must have exactly one aggregate key (count, sum, avg, min, max, countDistinct).`,
+        "invalid_aggregate_spec",
+        400
+      );
+    }
+    const fn = fns[0];
+    if (fn === "count") {
+      if (term[fn] !== true) {
+        throw new MindStudioError(
+          `aggregate(): term "${alias}" \u2014 count takes \`true\`, e.g. { count: true }.`,
+          "invalid_aggregate_spec",
+          400
+        );
+      }
+      return { alias, fn };
+    }
+    const column = term[fn];
+    if (typeof column !== "string" || !IDENTIFIER_RE.test(column)) {
+      throw new MindStudioError(
+        `aggregate(): term "${alias}" \u2014 invalid column "${String(column)}".`,
+        "invalid_column",
+        400
+      );
+    }
+    return { alias, fn, column };
+  });
+  if (spec.orderBy != null) {
+    if (!aliases.includes(spec.orderBy) && !by.includes(spec.orderBy)) {
+      throw new MindStudioError(
+        `aggregate(): orderBy "${spec.orderBy}" is neither a select alias nor a group-by column.`,
+        "invalid_aggregate_order",
+        400
+      );
+    }
+  }
+  return {
+    by,
+    select,
+    orderBy: spec.orderBy,
+    desc: spec.desc,
+    limit: spec.limit
+  };
+}
+function aggregateValues(fn, values) {
+  const present = values.filter((v) => v != null);
+  switch (fn) {
+    case "count":
+      return values.length;
+    case "sum":
+      return present.reduce((s, v) => s + v, 0);
+    case "avg":
+      return present.length === 0 ? null : present.reduce((s, v) => s + v, 0) / present.length;
+    case "countDistinct":
+      return new Set(present).size;
+    case "min":
+      return present.length === 0 ? null : present.reduce((m, v) => v < m ? v : m);
+    case "max":
+      return present.length === 0 ? null : present.reduce((m, v) => v > m ? v : m);
+  }
+}
+function compareForOrder(a, b) {
+  if (a == null && b == null) return 0;
+  if (a == null) return -1;
+  if (b == null) return 1;
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+function computeAggregateInJs(rows, spec) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const key = JSON.stringify(spec.by.map((col) => row[col]));
+    const group = groups.get(key);
+    if (group) group.push(row);
+    else groups.set(key, [row]);
+  }
+  if (spec.by.length === 0 && groups.size === 0) {
+    groups.set("[]", []);
+  }
+  let out = Array.from(groups.values()).map((groupRows) => {
+    const result = {};
+    for (const col of spec.by) {
+      result[col] = groupRows[0]?.[col];
+    }
+    for (const term of spec.select) {
+      result[term.alias] = aggregateValues(
+        term.fn,
+        term.column != null ? groupRows.map((r) => r[term.column]) : groupRows
+      );
+    }
+    return result;
+  });
+  if (spec.orderBy) {
+    const key = spec.orderBy;
+    out.sort((a, b) => compareForOrder(a[key], b[key]));
+    if (spec.desc) out.reverse();
+  }
+  if (spec.limit != null) {
+    out = out.slice(0, spec.limit);
+  }
+  return spec.by.length === 0 ? out[0] : out;
+}
+function deserializeAggregateRows(rows, spec, columns) {
+  const schemaFor = /* @__PURE__ */ new Map();
+  for (const col of spec.by) {
+    schemaFor.set(
+      col,
+      columns.filter((c) => c.name === col)
+    );
+  }
+  for (const term of spec.select) {
+    if ((term.fn === "min" || term.fn === "max") && term.column != null) {
+      schemaFor.set(
+        term.alias,
+        columns.filter((c) => c.name === term.column).map((c) => ({ ...c, name: term.alias }))
+      );
+    }
+  }
+  return rows.map((raw) => {
+    const row = raw;
+    const result = {};
+    for (const [key, value] of Object.entries(row)) {
+      const schema = schemaFor.get(key);
+      if (schema) {
+        result[key] = deserializeRow({ [key]: value }, schema)[key];
+      } else {
+        result[key] = value;
+      }
+    }
+    return result;
+  });
+}
+
 // src/db/query.ts
 var Query = class _Query {
   _predicates;
@@ -1130,6 +1364,8 @@ var Query = class _Query {
   /** @internal Pre-compiled WHERE clause (bypasses predicate compiler). Used by Table.get(). */
   _rawWhere;
   _rawWhereParams;
+  /** @internal See AggregateState — set by aggregate terminals. */
+  _aggregate;
   /** @internal Post-process transform applied after row deserialization. */
   _postProcess;
   constructor(config, options) {
@@ -1142,6 +1378,7 @@ var Query = class _Query {
     this._postProcess = options?.postProcess;
     this._rawWhere = options?.rawWhere;
     this._rawWhereParams = options?.rawWhereParams;
+    this._aggregate = options?.aggregate;
   }
   _clone(overrides) {
     return new _Query(this._config, {
@@ -1152,7 +1389,8 @@ var Query = class _Query {
       offset: overrides.offset ?? this._offset,
       postProcess: overrides.postProcess,
       rawWhere: this._rawWhere,
-      rawWhereParams: this._rawWhereParams
+      rawWhereParams: this._rawWhereParams,
+      aggregate: overrides.aggregate ?? this._aggregate
     });
   }
   filter(predicate, bindings) {
@@ -1190,9 +1428,60 @@ var Query = class _Query {
   }
   count() {
     return this._clone({
+      aggregate: { kind: "scalar", fn: "count" },
       postProcess: (rows) => rows.length
     });
   }
+  /**
+   * Sum of a numeric field across matching rows. Compiles to a SQL
+   * aggregate (TOTAL) when possible — no rows are fetched. Returns 0 for
+   * an empty set; NULL values are skipped (SQL semantics).
+   */
+  sum(accessor) {
+    return this._clone({
+      aggregate: { kind: "scalar", fn: "sum", accessor },
+      postProcess: (rows) => rows.reduce((total, row) => {
+        const value = accessor(row);
+        return value == null ? total : total + value;
+      }, 0)
+    });
+  }
+  /**
+   * Average of a numeric field across matching rows. Compiles to SQL AVG
+   * when possible. Returns null for an empty set (or when every value is
+   * null) — SQL AVG semantics.
+   */
+  avg(accessor) {
+    return this._clone({
+      aggregate: { kind: "scalar", fn: "avg", accessor },
+      postProcess: (rows) => {
+        const values = rows.map((row) => accessor(row)).filter((v) => v != null);
+        return values.length === 0 ? null : values.reduce((s, v) => s + v, 0) / values.length;
+      }
+    });
+  }
+  /**
+   * Number of distinct non-null values of a field across matching rows.
+   * Compiles to SQL COUNT(DISTINCT col) when possible.
+   */
+  countDistinct(accessor) {
+    return this._clone({
+      aggregate: { kind: "scalar", fn: "countDistinct", accessor },
+      postProcess: (rows) => new Set(rows.map((row) => accessor(row)).filter((v) => v != null)).size
+    });
+  }
+  aggregate(spec) {
+    const normalized = normalizeAggregateSpec(
+      spec
+    );
+    return this._clone({
+      aggregate: { kind: "grouped", spec: normalized },
+      postProcess: (rows) => computeAggregateInJs(
+        rows,
+        normalized
+      )
+    });
+  }
   some() {
     return this._clone({
       limit: 1,
@@ -1263,6 +1552,10 @@ var Query = class _Query {
     const compiled = this._compilePredicates();
     const sortField = this._sortAccessor ? extractFieldName(this._sortAccessor) : void 0;
     if (compiled.allSql) {
+      const agg = this._compileAggregateSql(compiled.sqlWhere);
+      if (agg) {
+        return { type: "query", query: agg.query, fallbackQuery: null, config: this._config, processRaw: agg.processRaw };
+      }
       const query = buildSelect(this._config.tableName, {
         where: compiled.sqlWhere || void 0,
         orderBy: sortField ?? void 0,
@@ -1294,6 +1587,9 @@ var Query = class _Query {
    * For JS-fallback queries: filter, sort, and slice in JS.
    */
   static _processResults(result, compiled) {
+    if (compiled.processRaw) {
+      return compiled.processRaw(result);
+    }
     const rows = result.rows.map(
       (row) => deserializeRow(
         row,
@@ -1326,10 +1622,81 @@ var Query = class _Query {
   // PromiseLike
   // -------------------------------------------------------------------------
   then(onfulfilled, onrejected) {
-    const promise = this._execute().then(
-      (rows) => this._postProcess ? this._postProcess(rows) : rows
-    );
-    return promise.then(onfulfilled, onrejected);
+    return this._run().then(onfulfilled, onrejected);
+  }
+  async _run() {
+    if (this._aggregate && !this._rawWhere) {
+      const compiled = this._compilePredicates();
+      if (compiled.allSql) {
+        const agg = this._compileAggregateSql(compiled.sqlWhere);
+        if (agg) {
+          const results = await this._config.executeBatch([agg.query]);
+          return agg.processRaw(results[0]);
+        }
+      }
+    }
+    const rows = await this._execute();
+    return this._postProcess ? this._postProcess(rows) : rows;
+  }
+  /**
+   * @internal Compile the pending aggregate into a single SQL statement +
+   * result processor. Returns null (→ fetch path, postProcess computes the
+   * aggregate) when there is no aggregate, when a pre-compiled WHERE is in
+   * play (Table.get()), when limit/offset are set (aggregate-the-page
+   * semantics — COUNT(*)/TOTAL can't express "over the limited page"), or
+   * when a scalar accessor doesn't extract to a column (computed accessors
+   * stay correct via JS, with a warning to prompt optimization).
+   */
+  _compileAggregateSql(sqlWhere) {
+    const agg = this._aggregate;
+    if (!agg || this._rawWhere || this._limit != null || this._offset != null) {
+      return null;
+    }
+    const where = sqlWhere || void 0;
+    if (agg.kind === "scalar") {
+      let column = null;
+      if (agg.accessor) {
+        column = extractFieldName(agg.accessor);
+        if (column == null) {
+          console.warn(
+            `[mindstudio] ${agg.fn}() accessor on '${this._config.tableName}' could not be compiled to SQL \u2014 fetching matching rows and computing in JS`
+          );
+          return null;
+        }
+      }
+      const query2 = buildScalarAggregate(
+        this._config.tableName,
+        agg.fn,
+        column,
+        where
+      );
+      const processRaw2 = (result) => {
+        const value = result.rows[0]?.value;
+        if (agg.fn === "avg") {
+          return value == null ? null : Number(value);
+        }
+        return Number(value ?? 0);
+      };
+      return { query: query2, processRaw: processRaw2 };
+    }
+    const spec = agg.spec;
+    const query = buildGroupedAggregate(this._config.tableName, {
+      by: spec.by,
+      select: spec.select,
+      where,
+      orderBy: spec.orderBy,
+      desc: spec.desc,
+      limit: spec.limit
+    });
+    const processRaw = (result) => {
+      const rows = deserializeAggregateRows(
+        result.rows,
+        spec,
+        this._config.columns
+      );
+      return spec.by.length === 0 ? rows[0] : rows;
+    };
+    return { query, processRaw };
   }
   catch(onrejected) {
     return this.then(void 0, onrejected);
@@ -1560,7 +1927,34 @@ var Table = class {
   max(accessor) {
     return this.sortBy(accessor).reverse().first();
   }
-  /** Group rows by a field. Returns a Map. */
+  /**
+   * Sum of a numeric field across all rows (0 for an empty table).
+   * Runs as a SQL aggregate — no rows are fetched. Chain from filter()
+   * to sum a subset: `Orders.filter(...).sum(o => o.amount)`.
+   */
+  sum(accessor) {
+    return this.toArray().sum(accessor);
+  }
+  /**
+   * Average of a numeric field across all rows (null for an empty table).
+   * Runs as a SQL aggregate — no rows are fetched.
+   */
+  avg(accessor) {
+    return this.toArray().avg(accessor);
+  }
+  /**
+   * Number of distinct non-null values of a field across all rows.
+   * Runs as a SQL aggregate — no rows are fetched.
+   */
+  countDistinct(accessor) {
+    return this.toArray().countDistinct(accessor);
+  }
+  aggregate(spec) {
+    return this.toArray().aggregate(spec);
+  }
+  /** Group rows by a field. Returns a Map of FULL rows per group — it
+   * fetches everything. For grouped counts/sums/averages over tables that
+   * can grow large, use `aggregate()` instead (SQL GROUP BY, no row fetch). */
   groupBy(accessor) {
     return new Query(this._config).groupBy(accessor);
   }
@@ -1796,6 +2190,57 @@ var Table = class {
   }
 };
 
+// src/db/raw.ts
+var RawQuery = class _RawQuery {
+  _databaseId;
+  _executeBatch;
+  _query;
+  constructor(databaseId, executeBatch, query) {
+    this._databaseId = databaseId;
+    this._executeBatch = executeBatch;
+    this._query = query;
+  }
+  // -------------------------------------------------------------------------
+  // PromiseLike — executes on await
+  // -------------------------------------------------------------------------
+  then(onfulfilled, onrejected) {
+    return this._execute().then(onfulfilled, onrejected);
+  }
+  catch(onrejected) {
+    return this._execute().catch(onrejected);
+  }
+  // -------------------------------------------------------------------------
+  // Batch support
+  // -------------------------------------------------------------------------
+  /** @internal Compile for db.batch(). */
+  _compile() {
+    return {
+      type: "raw",
+      query: this._query,
+      config: { databaseId: this._databaseId },
+      processResult: (result) => _RawQuery._process(result)
+    };
+  }
+  /** @internal Process a raw SQL result. Used by db.batch(). */
+  static _processResults(result, compiled) {
+    return compiled.processResult(result);
+  }
+  // -------------------------------------------------------------------------
+  // Execution
+  // -------------------------------------------------------------------------
+  /** Schema-less deserialization: strips @@user@@ prefixes and best-effort
+   * parses JSON-looking strings; makes no other representation promises. */
+  static _process(result) {
+    return result.rows.map(
+      (row) => deserializeRow(row, [])
+    );
+  }
+  async _execute() {
+    const results = await this._executeBatch([this._query]);
+    return _RawQuery._process(results[0]);
+  }
+};
+
 // src/db/index.ts
 function createDb(databases, executeBatch, authConfig, syncRoles) {
   return {
@@ -1823,6 +2268,16 @@ function createDb(databases, executeBatch, authConfig, syncRoles) {
     fromNow: (ms) => Date.now() + ms,
     // --- User references ---
     userRef: (id) => id.startsWith(USER_PREFIX) ? id.slice(USER_PREFIX.length) : id,
+    // --- Raw SQL (read-only) ---
+    sql(query, params, options) {
+      validateRawSql(query);
+      const database = resolveDatabase(databases, options?.database);
+      return new RawQuery(
+        database.id,
+        (queries) => executeBatch(database.id, queries),
+        { sql: query, params: params?.map(serializeParam) }
+      );
+    },
     // --- Batch execution ---
     batch: ((...operations) => {
       return (async () => {
@@ -1833,8 +2288,11 @@ function createDb(databases, executeBatch, authConfig, syncRoles) {
           if (op instanceof Mutation) {
             return op._compile();
           }
+          if (op instanceof RawQuery) {
+            return op._compile();
+          }
           throw new MindStudioError(
-            "db.batch() only accepts Query and Mutation objects (from .filter(), .update(), .push(), etc.)",
+            "db.batch() only accepts Query, Mutation, and RawQuery objects (from .filter(), .update(), .push(), db.sql(), etc.)",
             "invalid_batch_operation",
             400
           );
@@ -1847,6 +2305,8 @@ function createDb(databases, executeBatch, authConfig, syncRoles) {
           if (c.type === "query") {
             const sqlQuery = c.query ?? c.fallbackQuery;
             groups.get(dbId).push({ opIndex: i, sqlQueries: [sqlQuery] });
+          } else if (c.type === "raw") {
+            groups.get(dbId).push({ opIndex: i, sqlQueries: [c.query] });
           } else {
             groups.get(dbId).push({ opIndex: i, sqlQueries: c.queries });
           }
@@ -1879,6 +2339,8 @@ function createDb(databases, executeBatch, authConfig, syncRoles) {
               );
             }
             return Query._processResults(results[0], c);
+          } else if (c.type === "raw") {
+            return RawQuery._processResults(results[0], c);
           } else {
             return Mutation._processResults(results, c);
           }
@@ -1887,7 +2349,23 @@ function createDb(databases, executeBatch, authConfig, syncRoles) {
     })
   };
 }
-function resolveTable(databases, tableName, databaseHint) {
+function validateRawSql(query) {
+  if (typeof query !== "string" || !query.trim()) {
+    throw new MindStudioError(
+      "db.sql() requires a non-empty SQL string.",
+      "invalid_sql",
+      400
+    );
+  }
+  if (!/^\s*(select|with)\b/i.test(query)) {
+    throw new MindStudioError(
+      "db.sql() is read-only \u2014 the statement must start with SELECT or WITH. Use Table methods (push/update/upsert/remove) for writes.",
+      "sql_read_only",
+      400
+    );
+  }
+}
+function resolveDatabase(databases, hint) {
   if (databases.length === 0) {
     throw new MindStudioError(
       `No databases found in app context. Make sure the app has at least one database configured.`,
@@ -1895,18 +2373,40 @@ function resolveTable(databases, tableName, databaseHint) {
       400
     );
   }
-  if (databaseHint) {
+  if (hint) {
     const targetDb = databases.find(
-      (db2) => db2.id === databaseHint || db2.name === databaseHint
+      (db2) => db2.id === hint || db2.name === hint
     );
     if (!targetDb) {
       const available = databases.map((db2) => db2.name || db2.id).join(", ");
       throw new MindStudioError(
-        `Database "${databaseHint}" not found. Available databases: ${available}`,
+        `Database "${hint}" not found. Available databases: ${available}`,
         "database_not_found",
         400
       );
     }
+    return targetDb;
+  }
+  if (databases.length > 1) {
+    const available = databases.map((db2) => db2.name || db2.id).join(", ");
+    throw new MindStudioError(
+      `This app has multiple databases \u2014 pass { database } to pick one. Available databases: ${available}`,
+      "ambiguous_database",
+      400
+    );
+  }
+  return databases[0];
+}
+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 = resolveDatabase(databases, databaseHint);
     const table = targetDb.tables.find((t) => t.name === tableName);
     if (!table) {
       const available = targetDb.tables.map((t) => t.name).join(", ");
@@ -3056,13 +3556,6 @@ var stepMetadata = {
     inputSchema: { "type": "object", "properties": { "webhookUrl": { "type": "string", "description": "Zapier webhook URL to send data to" }, "input": { "type": "object", "properties": {}, "required": [], "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: "Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Search a vector data source (RAG) and return relevant document chunks.",
@@ -3175,9 +3668,13 @@ var stepMetadata = {
   "searchGoogle": {
     stepType: "searchGoogle",
     description: "Search the web using Google and return structured results.",
-    usageNotes: "- Defaults to us/english, but can optionally specify country and/or language.\n- Defaults to any time, but can optionally specify last hour, last day, week, month, or year.\n- Defaults to top 30 results, but can specify 1 to 100 results to return.",
-    inputSchema: { "type": "object", "properties": { "query": { "type": "string", "description": "The search query to send to Google" }, "exportType": { "enum": ["text", "json"], "type": "string", "description": 'Format for the variable value: "text" or "json"' }, "countryCode": { "type": "string", "description": "Google gl country code (defaults to US)" }, "languageCode": { "type": "string", "description": 'Google hl language code (defaults to "en")' }, "dateRange": { "enum": ["hour", "day", "week", "month", "year", "any"], "type": "string", "description": 'Time range filter: "hour", "day", "week", "month", "year", or "any"' }, "numResults": { "type": "number", "description": "Number of results to return (1-100, default: 30)" } }, "required": ["query", "exportType"] },
-    outputSchema: { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the search result" }, "description": { "type": "string", "description": "Snippet/description of the search result" }, "url": { "type": "string", "description": "URL of the search result page" } }, "required": ["title", "description", "url"] }, "description": "List of search result entries" } }, "required": ["results"] }
+    usageNotes: `- Defaults to us/english, but can optionally specify country and/or language.
+- Defaults to any time, but can optionally specify last hour, last day, week, month, or year.
+- Defaults to top 30 results, but can specify 1 to 100 results to return.
+- Set fetchTopN to also read the page content of the first N results in the same step, instead of following up with a separate Scrape URL step per result. Costs meaningfully more (each page is a full scrape), so ask for the fewest you need.
+- Also returns Google's "people also ask" and related searches when available, which are useful for choosing a follow-up query.`,
+    inputSchema: { "type": "object", "properties": { "query": { "type": "string", "description": "The search query to send to Google" }, "exportType": { "enum": ["text", "json"], "type": "string", "description": 'Format for the variable value: "text" or "json"' }, "countryCode": { "type": "string", "description": "Google gl country code (defaults to US)" }, "languageCode": { "type": "string", "description": 'Google hl language code (defaults to "en")' }, "dateRange": { "enum": ["hour", "day", "week", "month", "year", "any"], "type": "string", "description": 'Time range filter: "hour", "day", "week", "month", "year", or "any"' }, "numResults": { "type": "number", "description": "Number of results to return (1-100, default: 30)" }, "fetchTopN": { "type": "number", "description": "Read the page content of the first N results in this same step (0-10, default 0 = off), rather than following up with a Scrape URL step per result. Each page is a full scrape, so this costs substantially more than the search alone." } }, "required": ["query", "exportType"] },
+    outputSchema: { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the search result" }, "description": { "type": "string", "description": "Snippet/description of the search result" }, "url": { "type": "string", "description": "URL of the search result page" }, "content": { "type": "string", "description": "Page content, only present when fetchTopN covered this result" } }, "required": ["title", "description", "url"] }, "description": "List of search result entries" }, "peopleAlsoAsk": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "snippet": { "type": "string" }, "link": { "type": "string" } } }, "description": `Google's "People also ask" entries, when Google returned any` }, "relatedSearches": { "type": "array", "items": { "type": "string" }, "description": "Google's related-search suggestions, when Google returned any" } }, "required": ["results"] }
   },
   "searchGoogleCalendarEvents": {
     stepType: "searchGoogleCalendarEvents",
@@ -4729,9 +5226,6 @@ 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);
   };
@@ -6295,6 +6789,24 @@ var MindStudioAgent = class {
       ago: (ms) => Date.now() - ms,
       fromNow: (ms) => Date.now() + ms,
       userRef: (id) => id.startsWith("@@user@@") ? id.slice("@@user@@".length) : id,
+      // Raw SQL — validate synchronously; database resolution needs context,
+      // so it happens inside the executeBatch closure at execution time
+      // (the same deferral lazy defineTable uses).
+      sql: ((query, params, options) => {
+        validateRawSql(query);
+        return new RawQuery(
+          "",
+          async (queries) => {
+            await agent.ensureContext();
+            const database = resolveDatabase(
+              agent._getContext().databases,
+              options?.database
+            );
+            return agent._executeDbBatch(database.id, queries);
+          },
+          { sql: query, params: params?.map(serializeParam) }
+        );
+      }),
       // Batch needs context — hydrate first, then delegate to real db
       batch: ((...queries) => {
         return (async () => {
@@ -6850,7 +7362,6 @@ 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"] },