@mindstudio-ai/agent 0.1.9 → 0.1.11

package/dist/index.js

@@ -211,6 +211,19 @@ var Roles = new Proxy(
 );
 
 // src/db/sql.ts
+function serializeParam(val) {
+  if (val === null || val === void 0) return null;
+  if (typeof val === "boolean") return val ? 1 : 0;
+  if (typeof val === "number" || typeof val === "string") return val;
+  return JSON.stringify(val);
+}
+function serializeColumnParam(val, columnName, columns) {
+  const col = columns.find((c) => c.name === columnName);
+  if (col?.type === "user" && typeof val === "string") {
+    return `@@user@@${val}`;
+  }
+  return serializeParam(val);
+}
 function escapeValue(val) {
   if (val === null || val === void 0) return "NULL";
   if (typeof val === "boolean") return val ? "1" : "0";
@@ -219,13 +232,6 @@ function escapeValue(val) {
   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 = {};
@@ -247,37 +253,54 @@ function deserializeRow(row, columns) {
 }
 function buildSelect(table, options = {}) {
   let sql = `SELECT * FROM ${table}`;
-  if (options.where) sql += ` WHERE ${options.where}`;
+  const params = [];
+  if (options.where) {
+    sql += ` WHERE ${options.where}`;
+    if (options.whereParams) params.push(...options.whereParams);
+  }
   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;
+  return { sql, params: params.length > 0 ? params : void 0 };
 }
-function buildCount(table, where) {
+function buildCount(table, where, whereParams) {
   let sql = `SELECT COUNT(*) as count FROM ${table}`;
   if (where) sql += ` WHERE ${where}`;
-  return sql;
+  return { sql, params: whereParams?.length ? whereParams : void 0 };
 }
-function buildExists(table, where, negate) {
+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";
-  return `SELECT ${fn}(${inner}) as result`;
+  return { sql: `SELECT ${fn}(${inner}) as result`, params: whereParams?.length ? whereParams : void 0 };
 }
 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(", ")})`;
+  const placeholders = keys.map(() => "?").join(", ");
+  const params = keys.map((k) => serializeColumnParam(filtered[k], k, columns));
+  return {
+    sql: `INSERT INTO ${table} (${keys.join(", ")}) VALUES (${placeholders}) RETURNING *`,
+    params
+  };
 }
 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)}`;
+  const keys = Object.keys(filtered);
+  const assignments = keys.map((k) => `${k} = ?`).join(", ");
+  const params = [
+    ...keys.map((k) => serializeColumnParam(filtered[k], k, columns)),
+    id
+    // for WHERE id = ?
+  ];
+  return {
+    sql: `UPDATE ${table} SET ${assignments} WHERE id = ? RETURNING *`,
+    params
+  };
 }
-function buildDelete(table, where) {
+function buildDelete(table, where, whereParams) {
   let sql = `DELETE FROM ${table}`;
   if (where) sql += ` WHERE ${where}`;
-  return sql;
+  return { sql, params: whereParams?.length ? whereParams : void 0 };
 }
 var SYSTEM_COLUMNS = /* @__PURE__ */ new Set(["id", "createdAt", "updatedAt", "lastUpdatedBy"]);
 function stripSystemColumns(data) {
@@ -693,8 +716,7 @@ var Parser = class {
     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.
+   * Attempt to resolve a closure variable's value.
    *
    * This handles the common pattern:
    * ```ts
@@ -702,40 +724,28 @@ var Parser = class {
    * 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.
+   * Closure variable resolution is fundamentally limited in JavaScript —
+   * we can't access another function's closure scope from outside without
+   * `eval`. The `===` operator can't be overridden via Proxy or
+   * Symbol.toPrimitive, so we can't intercept comparisons.
+   *
+   * For now, this falls back to JS execution. The predicate still works
+   * correctly — it just scans all rows instead of generating SQL.
+   * This is the most common reason for JS fallback in practice, since
+   * almost every real-world filter references a variable like `userId`.
+   *
+   * A future improvement could accept an explicit `vars` argument:
+   * ```ts
+   * orders.filter(o => o.requestedBy === $userId, { $userId: auth.userId })
+   * ```
    */
   resolveClosureVariable() {
-    const identToken = this.advance();
-    let closureExpr = identToken.value;
+    this.advance();
     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;
+      this.advance();
     }
+    return PARSE_FAILED;
   }
   /**
    * Look ahead to check if the next tokens form `.includes(`.
@@ -792,17 +802,11 @@ function isComparisonOp(value) {
 
 // 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;
@@ -812,10 +816,6 @@ var Query = class _Query {
     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,
@@ -826,126 +826,73 @@ var Query = class _Query {
     });
   }
   // -------------------------------------------------------------------------
-  // Chain methods — return new Query instances
+  // Chain methods
   // -------------------------------------------------------------------------
-  /**
-   * 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]
-    });
+    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
+  // Terminal methods
   // -------------------------------------------------------------------------
-  /**
-   * 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];
+      const query = buildCount(
+        this._config.tableName,
+        compiled.sqlWhere || void 0
+      );
+      const results = await this._config.executeBatch([query]);
+      const row = results[0]?.rows[0];
       return row?.count ?? 0;
     }
     const rows = await this._fetchAndFilterInJs(compiled);
     return rows.length;
   }
-  /**
-   * 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];
+      const query = buildExists(
+        this._config.tableName,
+        compiled.sqlWhere || void 0
+      );
+      const results = await this._config.executeBatch([query]);
+      const row = results[0]?.rows[0];
       return row?.result === 1;
     }
     const rows = await this._fetchAndFilterInJs(compiled);
     return rows.length > 0;
   }
-  /**
-   * 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];
+      const query = buildExists(
+        this._config.tableName,
+        `NOT (${compiled.sqlWhere})`,
+        void 0,
+        true
+      );
+      const results = await this._config.executeBatch([query]);
+      const row = results[0]?.rows[0];
       return row?.result === 1;
     }
     if (this._predicates.length === 0) return true;
@@ -954,24 +901,12 @@ var Query = class _Query {
       (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();
@@ -987,40 +922,97 @@ var Query = class _Query {
     return map;
   }
   // -------------------------------------------------------------------------
-  // PromiseLike implementation — makes `await query` work
+  // Batch compilation — used by db.batch() to extract SQL without executing
   // -------------------------------------------------------------------------
   /**
-   * PromiseLike.then() — executes the query and pipes the result.
-   * This is what makes `const rows = await query` work.
+   * @internal Compile this query into a SqlQuery for batch execution.
+   *
+   * Returns the compiled SQL query (if all predicates compile to SQL),
+   * or null (if JS fallback is needed). In the fallback case, a bare
+   * `SELECT *` is returned as `fallbackQuery` so the batch can fetch
+   * all rows and this query can filter them in JS post-fetch.
+   */
+  _compile() {
+    const compiled = this._compilePredicates();
+    const sortField = this._sortAccessor ? extractFieldName(this._sortAccessor) : void 0;
+    if (compiled.allSql) {
+      const query = buildSelect(this._config.tableName, {
+        where: compiled.sqlWhere || void 0,
+        orderBy: sortField ?? void 0,
+        desc: this._reversed,
+        limit: this._limit,
+        offset: this._offset
+      });
+      return { query, fallbackQuery: null, config: this._config };
+    }
+    const fallbackQuery = buildSelect(this._config.tableName);
+    return {
+      query: null,
+      fallbackQuery,
+      config: this._config,
+      predicates: this._predicates,
+      sortAccessor: this._sortAccessor,
+      reversed: this._reversed,
+      limit: this._limit,
+      offset: this._offset
+    };
+  }
+  /**
+   * @internal Process raw SQL results into typed rows. Used by db.batch()
+   * after executing the compiled query.
+   *
+   * For SQL-compiled queries: just deserialize the rows.
+   * For JS-fallback queries: filter, sort, and slice in JS.
    */
+  static _processResults(result, compiled) {
+    const rows = result.rows.map(
+      (row) => deserializeRow(
+        row,
+        compiled.config.columns
+      )
+    );
+    if (compiled.query) return rows;
+    let filtered = compiled.predicates ? rows.filter((row) => compiled.predicates.every((pred) => pred(row))) : rows;
+    if (compiled.sortAccessor) {
+      const accessor = compiled.sortAccessor;
+      const reversed = compiled.reversed ?? false;
+      filtered.sort((a, b) => {
+        const aVal = accessor(a);
+        const bVal = accessor(b);
+        if (aVal < bVal) return reversed ? 1 : -1;
+        if (aVal > bVal) return reversed ? -1 : 1;
+        return 0;
+      });
+    }
+    if (compiled.offset != null || compiled.limit != null) {
+      const start = compiled.offset ?? 0;
+      const end = compiled.limit != null ? start + compiled.limit : void 0;
+      filtered = filtered.slice(start, end);
+    }
+    return filtered;
+  }
+  // -------------------------------------------------------------------------
+  // PromiseLike
+  // -------------------------------------------------------------------------
   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, {
+      const query = 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(
+      const results = await this._config.executeBatch([query]);
+      return results[0].rows.map(
         (row) => deserializeRow(
           row,
           this._config.columns
@@ -1045,14 +1037,6 @@ var Query = class _Query {
     }
     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: [] };
@@ -1065,12 +1049,6 @@ var Query = class _Query {
     }
     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")) {
@@ -1082,14 +1060,10 @@ var Query = class _Query {
       (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(
+    const query = buildSelect(this._config.tableName);
+    const results = await this._config.executeBatch([query]);
+    return results[0].rows.map(
       (row) => deserializeRow(row, this._config.columns)
     );
   }
@@ -1104,298 +1078,147 @@ function extractFieldName(accessor) {
 
 // src/db/table.ts
 var Table = class {
-  /** @internal Runtime config binding this table to the execution layer. */
+  /** @internal */
   _config;
   constructor(config) {
     this._config = config;
   }
   // -------------------------------------------------------------------------
-  // Reads — direct (return Promises)
+  // Reads — direct
   // -------------------------------------------------------------------------
-  /**
-   * 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)}`,
+    const query = buildSelect(this._config.tableName, {
+      where: `id = ?`,
+      whereParams: [id],
       limit: 1
     });
-    const result = await this._config.executeQuery(sql);
-    if (result.rows.length === 0) return null;
+    const results = await this._config.executeBatch([query]);
+    if (results[0].rows.length === 0) return null;
     return deserializeRow(
-      result.rows[0],
+      results[0].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];
+    if (predicate) return this.filter(predicate).count();
+    const query = buildCount(this._config.tableName);
+    const results = await this._config.executeBatch([query]);
+    const row = results[0]?.rows[0];
     return row?.count ?? 0;
   }
-  /**
-   * 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];
+    const query = buildExists(this._config.tableName, void 0, void 0, true);
+    const results = await this._config.executeBatch([query]);
+    const row = results[0]?.rows[0];
     return row?.result === 1;
   }
-  /**
-   * 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>)
+  // Reads — chainable
   // -------------------------------------------------------------------------
-  /**
-   * 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(
+    const queries = items.map(
+      (item) => 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
-          )
+      )
+    );
+    const results = await this._config.executeBatch(queries);
+    const rows = results.map((r) => {
+      if (r.rows.length > 0) {
+        return deserializeRow(
+          r.rows[0],
+          this._config.columns
         );
       }
-    }
-    return isArray ? results : results[0];
+      return void 0;
+    });
+    return isArray ? rows : rows[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
-   * ```
+   * Returns the updated row via `UPDATE ... RETURNING *`.
    */
   async update(id, data) {
-    const updateSql = buildUpdate(
+    const query = 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);
+    const results = await this._config.executeBatch([query]);
     return deserializeRow(
-      result.rows[0],
+      results[0].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);
+    const query = buildDelete(this._config.tableName, `id = ?`, [id]);
+    await this._config.executeBatch([query]);
   }
   /**
    * 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;
+      const query = buildDelete(this._config.tableName, compiled.where);
+      const results = await this._config.executeBatch([query]);
+      return results[0].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(
+    const allQuery = buildSelect(this._config.tableName);
+    const allResults = await this._config.executeBatch([allQuery]);
+    const allRows = allResults[0].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++;
-      }
+    if (matching.length === 0) return 0;
+    const deleteQueries = matching.filter((row) => row.id).map((row) => buildDelete(this._config.tableName, `id = ?`, [row.id]));
+    if (deleteQueries.length > 0) {
+      await this._config.executeBatch(deleteQueries);
     }
-    return count;
+    return matching.length;
   }
-  /**
-   * Remove all rows from the table.
-   *
-   * @example
-   * ```ts
-   * await Orders.clear();
-   * ```
-   */
   async clear() {
-    const sql = buildDelete(this._config.tableName);
-    await this._config.executeQuery(sql);
+    const query = buildDelete(this._config.tableName);
+    await this._config.executeBatch([query]);
   }
 };
 
 // src/db/index.ts
-function createDb(databases, executeQuery) {
+function createDb(databases, executeBatch) {
   return {
     defineTable(name, options) {
       const resolved = resolveTable(databases, name, options?.database);
@@ -1403,7 +1226,7 @@ function createDb(databases, executeQuery) {
         databaseId: resolved.databaseId,
         tableName: name,
         columns: resolved.columns,
-        executeQuery: (sql) => executeQuery(resolved.databaseId, sql)
+        executeBatch: (queries) => executeBatch(resolved.databaseId, queries)
       };
       return new Table(config);
     },
@@ -1414,7 +1237,49 @@ function createDb(databases, executeQuery) {
     hours: (n) => n * 36e5,
     minutes: (n) => n * 6e4,
     ago: (ms) => Date.now() - ms,
-    fromNow: (ms) => Date.now() + ms
+    fromNow: (ms) => Date.now() + ms,
+    // --- Batch execution ---
+    batch: ((...queries) => {
+      return (async () => {
+        const compiled = queries.map((q) => {
+          if (!(q instanceof Query)) {
+            throw new MindStudioError(
+              "db.batch() only accepts Query objects (from .filter(), .sortBy(), etc.)",
+              "invalid_batch_query",
+              400
+            );
+          }
+          return q._compile();
+        });
+        const groups = /* @__PURE__ */ new Map();
+        for (let i = 0; i < compiled.length; i++) {
+          const c = compiled[i];
+          const dbId = c.config.databaseId;
+          const sqlQuery = c.query ?? c.fallbackQuery;
+          if (!groups.has(dbId)) groups.set(dbId, []);
+          groups.get(dbId).push({ index: i, sqlQuery });
+        }
+        const allResults = new Array(compiled.length);
+        await Promise.all(
+          Array.from(groups.entries()).map(async ([dbId, entries]) => {
+            const sqlQueries = entries.map((e) => e.sqlQuery);
+            const results = await executeBatch(dbId, sqlQueries);
+            for (let i = 0; i < entries.length; i++) {
+              allResults[entries[i].index] = results[i];
+            }
+          })
+        );
+        return compiled.map((c, i) => {
+          const result = allResults[i];
+          if (!c.query && c.predicates?.length) {
+            console.warn(
+              `[mindstudio] db.batch(): filter on ${c.config.tableName} could not be compiled to SQL \u2014 processing in JS`
+            );
+          }
+          return Query._processResults(result, c);
+        });
+      })();
+    })
   };
 }
 function resolveTable(databases, tableName, databaseHint) {
@@ -2325,6 +2190,9 @@ var MindStudioAgent = class {
    * ```
    */
   get auth() {
+    if (!this._auth) {
+      this._trySandboxHydration();
+    }
     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.",
@@ -2350,6 +2218,9 @@ var MindStudioAgent = class {
    * ```
    */
   get db() {
+    if (!this._db) {
+      this._trySandboxHydration();
+    }
     if (this._db) return this._db;
     return this._createLazyDb();
   }
@@ -2407,7 +2278,7 @@ var MindStudioAgent = class {
     this._auth = new AuthContext(context.auth);
     this._db = createDb(
       context.databases,
-      this._executeDbQuery.bind(this)
+      this._executeDbBatch.bind(this)
     );
   }
   /**
@@ -2428,25 +2299,40 @@ var MindStudioAgent = class {
     }
   }
   /**
-   * @internal Execute a SQL query against a managed database.
-   * Used as the `executeQuery` callback for Table instances.
+   * @internal Execute a batch of SQL queries against a managed database.
+   * Used as the `executeBatch` callback for Table/Query instances.
    *
-   * Calls the `queryAppDatabase` step with `parameterize: false`
-   * (the SDK builds fully-formed SQL with escaped inline values).
+   * Calls `POST /_internal/v2/db/query` directly with the hook token
+   * (raw, no Bearer prefix). All queries run on a single SQLite connection,
+   * enabling RETURNING clauses and multi-statement batches.
    */
-  async _executeDbQuery(databaseId, sql) {
-    const result = await this.executeStep("queryAppDatabase", {
-      databaseId,
-      sql,
-      parameterize: false
+  async _executeDbBatch(databaseId, queries) {
+    const url = `${this._httpConfig.baseUrl}/_internal/v2/db/query`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: this._httpConfig.token
+      },
+      body: JSON.stringify({ databaseId, queries })
     });
-    return { rows: result.rows ?? [], changes: result.changes ?? 0 };
+    if (!res.ok) {
+      let message = `Database query failed: ${res.status} ${res.statusText}`;
+      try {
+        const body = await res.json();
+        if (body.error) message = body.error;
+      } catch {
+      }
+      throw new MindStudioError(message, "db_query_error", res.status);
+    }
+    const data = await res.json();
+    return data.results;
   }
   /**
    * @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()
+   * But the Table's executeBatch callback is wrapped to call ensureContext()
    * before the first query, so context is fetched lazily.
    */
   _createLazyDb() {
@@ -2458,7 +2344,7 @@ var MindStudioAgent = class {
           databaseId: "",
           tableName: name,
           columns: [],
-          executeQuery: async (sql) => {
+          executeBatch: async (queries) => {
             await agent.ensureContext();
             const databases = agent._context.databases;
             let targetDb;
@@ -2472,7 +2358,7 @@ var MindStudioAgent = class {
               );
             }
             const databaseId = targetDb?.id ?? databases[0]?.id ?? "";
-            return agent._executeDbQuery(databaseId, sql);
+            return agent._executeDbBatch(databaseId, queries);
           }
         });
       },
@@ -2482,7 +2368,14 @@ var MindStudioAgent = class {
       hours: (n) => n * 36e5,
       minutes: (n) => n * 6e4,
       ago: (ms) => Date.now() - ms,
-      fromNow: (ms) => Date.now() + ms
+      fromNow: (ms) => Date.now() + ms,
+      // Batch needs context — hydrate first, then delegate to real db
+      batch: ((...queries) => {
+        return (async () => {
+          await agent.ensureContext();
+          return agent._db.batch(...queries);
+        })();
+      })
     };
   }
   // -------------------------------------------------------------------------