@mindstudio-ai/agent 0.1.9 → 0.1.11

package/dist/index.d.ts

@@ -156,9 +156,7 @@ interface UserInfoResult {
  * }
  * ```
  */
-type User = string & {
-    readonly __brand: 'User';
-};
+type User = string;
 /**
  * Resolved display info for a platform user. Returned by `resolveUser()`
  * and `resolveUsers()`.
@@ -597,16 +595,26 @@ interface TableConfig {
      */
     columns: AppDatabaseColumnSchema[];
     /**
-     * Execute a SQL query against the managed database. This is bound to
-     * `agent.executeStep('queryAppDatabase', ...)` at creation time.
+     * Execute one or more SQL queries against the managed database in a
+     * single round trip. All queries run on the same SQLite connection,
+     * enabling RETURNING clauses and multi-statement batches.
+     *
+     * Bound to the `POST /_internal/v2/db/query` endpoint at creation time.
      *
-     * @param sql - The SQL query string (fully formed, no placeholders)
-     * @returns The query result: rows for SELECT, changes count for writes
+     * @param queries - Array of SQL queries with optional bind params
+     * @returns Array of results in the same order as the input queries
      */
-    executeQuery: (sql: string) => Promise<{
-        rows: unknown[];
-        changes: number;
-    }>;
+    executeBatch: (queries: SqlQuery[]) => Promise<SqlResult[]>;
+}
+/** A single SQL query with optional positional bind params. */
+interface SqlQuery {
+    sql: string;
+    params?: unknown[];
+}
+/** Result of a single SQL query execution. */
+interface SqlResult {
+    rows: unknown[];
+    changes: number;
 }
 
 /**
@@ -642,53 +650,14 @@ interface TableConfig {
  *
  * Both paths produce identical results. The SQL path is a transparent
  * performance optimization.
- *
- * ## Data flow
- *
- * ```
- * .filter(pred1).filter(pred2).sortBy(fn).reverse().take(10)
- *     ↓
- * Query { predicates: [pred1, pred2], sortAccessor: fn, reversed: true, limit: 10 }
- *     ↓ (on await)
- * compilePredicate(pred1) → SQL?   compilePredicate(pred2) → SQL?
- *     ↓
- * All SQL? → buildSelect('table', { where: 'p1 AND p2', orderBy, desc, limit })
- *            → executeQuery(sql) → deserialize rows → return T[]
- *
- * Any JS?  → buildSelect('table', {}) → executeQuery → deserialize all rows
- *            → Array.filter(pred1).filter(pred2).sort(...).slice(0, 10) → return T[]
- * ```
  */
 
-/**
- * A lazy, chainable database query. Implements PromiseLike<T[]> so it
- * can be awaited directly to get the result rows.
- *
- * @example
- * ```ts
- * // Chain operations (nothing executes yet)
- * const query = Orders
- *   .filter(o => o.status === 'active')
- *   .sortBy(o => o.createdAt)
- *   .reverse()
- *   .take(10);
- *
- * // Execute the query by awaiting it
- * const rows = await query;
- * ```
- */
 declare class Query<T> implements PromiseLike<T[]> {
-    /** @internal Accumulated predicate functions to filter by. */
     private readonly _predicates;
-    /** @internal The field accessor for sorting, if set. */
     private readonly _sortAccessor;
-    /** @internal Whether the sort order is reversed (DESC). */
     private readonly _reversed;
-    /** @internal Maximum number of results (SQL LIMIT). */
     private readonly _limit;
-    /** @internal Number of results to skip (SQL OFFSET). */
     private readonly _offset;
-    /** @internal Binding to the database execution layer. */
     private readonly _config;
     constructor(config: TableConfig, options?: {
         predicates?: Predicate<T>[];
@@ -697,356 +666,115 @@ declare class Query<T> implements PromiseLike<T[]> {
         limit?: number;
         offset?: number;
     });
-    /**
-     * Create a clone of this query with some options overridden.
-     * Used internally by chain methods to maintain immutability.
-     */
     private _clone;
-    /**
-     * 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: Predicate<T>): Query<T>;
-    /**
-     * 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: Accessor<T>): Query<T>;
-    /**
-     * Reverse the current sort order. If no sort is set, this has no effect.
-     */
     reverse(): Query<T>;
-    /**
-     * Limit the number of results returned.
-     *
-     * @example
-     * ```ts
-     * const top10 = Orders.sortBy(o => o.amount).reverse().take(10);
-     * ```
-     */
     take(n: number): Query<T>;
-    /**
-     * 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: number): Query<T>;
-    /**
-     * Return the first matching row, or null if no rows match.
-     * Applies the current sort order before taking the first result.
-     */
     first(): Promise<T | null>;
-    /**
-     * Return the last matching row (per current sort), or null.
-     * Flips the sort direction and takes 1 row.
-     */
     last(): Promise<T | null>;
-    /**
-     * Count matching rows. Returns a number, not the rows themselves.
-     * Executes as `SELECT COUNT(*)` when predicates compile to SQL.
-     */
     count(): Promise<number>;
-    /**
-     * Check if any row matches the current filters. Short-circuits —
-     * doesn't load all rows when using SQL.
-     */
     some(): Promise<boolean>;
-    /**
-     * 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.
-     */
     every(): Promise<boolean>;
-    /**
-     * Return the row with the minimum value for the given field.
-     * Executes as `ORDER BY field ASC LIMIT 1` in SQL.
-     */
     min(accessor: Accessor<T, number>): Promise<T | null>;
-    /**
-     * Return the row with the maximum value for the given field.
-     * Executes as `ORDER BY field DESC LIMIT 1` in SQL.
-     */
     max(accessor: Accessor<T, number>): Promise<T | null>;
-    /**
-     * Group rows by a field value. Returns a Map.
-     * Always executes in JS (no SQL equivalent for grouping into a Map).
-     */
     groupBy<K extends string | number>(accessor: Accessor<T, K>): Promise<Map<K, T[]>>;
     /**
-     * PromiseLike.then() — executes the query and pipes the result.
-     * This is what makes `const rows = await query` work.
-     */
-    then<TResult1 = T[], TResult2 = never>(onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
-    /**
-     * Execute the query and return typed result rows.
+     * @internal Compile this query into a SqlQuery for batch execution.
      *
-     * 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)
+     * 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.
      */
-    private _execute;
+    _compile(): CompiledQuery<T>;
     /**
-     * Compile all accumulated predicates and determine the execution strategy.
+     * @internal Process raw SQL results into typed rows. Used by db.batch()
+     * after executing the compiled query.
      *
-     * Returns an object with:
-     * - `allSql`: whether all predicates compiled to SQL
-     * - `sqlWhere`: combined WHERE clause (ANDed) if all compiled
-     * - `compiled`: individual compilation results
+     * For SQL-compiled queries: just deserialize the rows.
+     * For JS-fallback queries: filter, sort, and slice in JS.
      */
+    static _processResults<T>(result: SqlResult, compiled: CompiledQuery<T>): T[];
+    then<TResult1 = T[], TResult2 = never>(onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private _execute;
     private _compilePredicates;
-    /**
-     * 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.
-     */
     private _fetchAndFilterInJs;
-    /**
-     * Fetch all rows from the table (SELECT * with no WHERE).
-     * Used by the JS fallback path.
-     */
     private _fetchAllRows;
 }
+/**
+ * Result of Query._compile(). Contains either a compiled SQL query
+ * (fast path) or a fallback SELECT * with JS processing metadata.
+ */
+interface CompiledQuery<T> {
+    /** Compiled SQL query, or null if JS fallback needed. */
+    query: SqlQuery | null;
+    /** SELECT * fallback query, or null if SQL compiled. */
+    fallbackQuery: SqlQuery | null;
+    /** Table config for deserialization. */
+    config: TableConfig;
+    /** JS predicates (only for fallback). */
+    predicates?: Predicate<T>[];
+    /** Sort accessor (only for fallback). */
+    sortAccessor?: Accessor<T>;
+    /** Sort direction (only for fallback). */
+    reversed?: boolean;
+    /** Limit (only for fallback). */
+    limit?: number;
+    /** Offset (only for fallback). */
+    offset?: number;
+}
 
 /**
  * Table<T> — a typed persistent collection backed by SQLite.
  *
- * Created via `db.defineTable<T>(name)`. The returned object is the full
- * API for interacting with that table. Every method either returns a
+ * Created via `db.defineTable<T>(name)`. Every method either returns a
  * chainable Query<T> (for lazy reads) or a Promise (for terminal reads
  * and writes).
  *
- * ## Read vs Write operations
- *
- * **Reads** come in two flavors:
- * - **Direct reads**: `get(id)`, `findOne()`, `count()`, `some()`, `every()`,
- *   `isEmpty()`, `min()`, `max()`, `groupBy()` — return Promises directly.
- * - **Chainable reads**: `filter()`, `sortBy()` — return a Query<T> that
- *   accumulates operations lazily. The query executes when awaited.
- *
- * **Writes** are always immediate (return Promises):
- * - `push()` — INSERT + SELECT to return the created row with system fields
- * - `update()` — UPDATE + SELECT to return the updated row
- * - `remove()` — DELETE by ID
- * - `removeAll()` — DELETE with compiled WHERE clause
- * - `clear()` — DELETE all rows
- *
- * ## System columns
+ * ## Write operations use RETURNING
  *
- * Every row has platform-managed columns: `id`, `createdAt`, `updatedAt`,
- * `lastUpdatedBy`. These are:
- * - Included in read results (populated by the platform)
- * - Excluded from `push()` and `update()` inputs (TypeScript enforces this
- *   via PushInput<T> and UpdateInput<T>; runtime also strips them)
- *
- * ## User type handling
- *
- * Columns with schema type `'user'` store values with a `@@user@@` prefix
- * in SQLite. This is handled transparently:
- * - On read: prefix is stripped, application code gets clean UUID strings
- * - On write: prefix is added before sending to the database
+ * INSERT and UPDATE use `RETURNING *` to get the created/updated row
+ * back in a single round trip — no separate SELECT needed. This is
+ * executed via the batch endpoint which runs all queries on a single
+ * SQLite connection.
  */
 
 declare class Table<T> {
-    /** @internal Runtime config binding this table to the execution layer. */
+    /** @internal */
     private readonly _config;
     constructor(config: TableConfig);
-    /**
-     * 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);
-     * ```
-     */
     get(id: string): Promise<T | null>;
-    /**
-     * Find the first row matching a predicate. Returns null if none match.
-     *
-     * @example
-     * ```ts
-     * const activeOrder = await Orders.findOne(o => o.status === 'active');
-     * ```
-     */
     findOne(predicate: Predicate<T>): Promise<T | null>;
-    /**
-     * Count rows, optionally filtered by a predicate.
-     *
-     * @example
-     * ```ts
-     * const total = await Orders.count();
-     * const pending = await Orders.count(o => o.status === 'pending');
-     * ```
-     */
     count(predicate?: Predicate<T>): Promise<number>;
-    /**
-     * Check if any row matches a predicate. Short-circuits.
-     *
-     * @example
-     * ```ts
-     * const hasActive = await Orders.some(o => o.status === 'active');
-     * ```
-     */
     some(predicate: Predicate<T>): Promise<boolean>;
-    /**
-     * Check if all rows match a predicate.
-     *
-     * @example
-     * ```ts
-     * const allComplete = await Orders.every(o => o.status === 'completed');
-     * ```
-     */
     every(predicate: Predicate<T>): Promise<boolean>;
-    /**
-     * Check if the table has zero rows.
-     *
-     * @example
-     * ```ts
-     * if (await Orders.isEmpty()) console.log('No orders yet');
-     * ```
-     */
     isEmpty(): Promise<boolean>;
-    /**
-     * 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);
-     * ```
-     */
     min(accessor: Accessor<T, number>): Promise<T | null>;
-    /**
-     * 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);
-     * ```
-     */
     max(accessor: Accessor<T, number>): Promise<T | null>;
-    /**
-     * Group all rows by a field value. Returns a Map.
-     *
-     * @example
-     * ```ts
-     * const byStatus = await Orders.groupBy(o => o.status);
-     * // Map { 'pending' => [...], 'approved' => [...] }
-     * ```
-     */
     groupBy<K extends string | number>(accessor: Accessor<T, K>): Promise<Map<K, 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: Predicate<T>): Query<T>;
-    /**
-     * 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: Accessor<T>): Query<T>;
     /**
      * Insert one or more rows. Returns the created row(s) with system fields
      * populated (id, createdAt, updatedAt, lastUpdatedBy).
      *
-     * System columns are stripped from the input automatically — you don't
-     * need to (and can't) set id, createdAt, etc.
-     *
-     * @example
-     * ```ts
-     * // Single row
-     * const order = await Orders.push({ item: 'Laptop', amount: 999, status: 'pending' });
-     * console.log(order.id, order.createdAt); // system fields populated
-     *
-     * // Multiple rows
-     * const orders = await Orders.push([
-     *   { item: 'Monitor', amount: 300, status: 'pending' },
-     *   { item: 'Keyboard', amount: 50, status: 'pending' },
-     * ]);
-     * ```
+     * Uses `INSERT ... RETURNING *` so the created row comes back in a
+     * single round trip — no separate SELECT needed.
      */
     push(data: PushInput<T>): Promise<T>;
     push(data: PushInput<T>[]): Promise<T[]>;
     /**
      * 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 *`.
      */
     update(id: string, data: UpdateInput<T>): Promise<T>;
-    /**
-     * Remove a row by ID.
-     *
-     * @example
-     * ```ts
-     * await Orders.remove('abc-123');
-     * ```
-     */
     remove(id: string): Promise<void>;
     /**
      * 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`);
-     * ```
      */
     removeAll(predicate: Predicate<T>): Promise<number>;
-    /**
-     * Remove all rows from the table.
-     *
-     * @example
-     * ```ts
-     * await Orders.clear();
-     * ```
-     */
     clear(): Promise<void>;
 }
 
@@ -1157,6 +885,28 @@ interface Db {
     ago(ms: number): number;
     /** Returns a unix timestamp for (now + duration). Use with days/hours/minutes. */
     fromNow(ms: number): number;
+    /**
+     * Execute multiple queries in a single round trip. All queries run on
+     * the same database connection, eliminating per-query HTTP overhead.
+     *
+     * Accepts Query objects (lazy, not yet executed). Compiles them to SQL,
+     * sends all in one batch request, and returns typed results.
+     *
+     * @example
+     * ```ts
+     * const [orders, approvals, vendors] = await db.batch(
+     *   Orders.filter(o => o.status === 'active').take(10),
+     *   Approvals.filter(a => a.status === 'pending').take(25),
+     *   Vendors.sortBy(v => v.createdAt).reverse().take(5),
+     * );
+     * ```
+     */
+    batch<A>(q1: PromiseLike<A>): Promise<[A]>;
+    batch<A, B>(q1: PromiseLike<A>, q2: PromiseLike<B>): Promise<[A, B]>;
+    batch<A, B, C>(q1: PromiseLike<A>, q2: PromiseLike<B>, q3: PromiseLike<C>): Promise<[A, B, C]>;
+    batch<A, B, C, D>(q1: PromiseLike<A>, q2: PromiseLike<B>, q3: PromiseLike<C>, q4: PromiseLike<D>): Promise<[A, B, C, D]>;
+    batch<A, B, C, D, E>(q1: PromiseLike<A>, q2: PromiseLike<B>, q3: PromiseLike<C>, q4: PromiseLike<D>, q5: PromiseLike<E>): Promise<[A, B, C, D, E]>;
+    batch(...queries: PromiseLike<unknown>[]): Promise<unknown[]>;
 }
 
 /**
@@ -1408,18 +1158,19 @@ declare class MindStudioAgent$1 {
      */
     private _trySandboxHydration;
     /**
-     * @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.
      */
-    private _executeDbQuery;
+    private _executeDbBatch;
     /**
      * @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.
      */
     private _createLazyDb;