@granular-software/sdk 0.4.19 → 0.4.21

package/README.md

@@ -353,6 +353,14 @@ After applying the manifest and publishing tools, the sandbox gets **auto-genera
 
 ```typescript
 // What the sandbox sees (auto-generated):
+export interface SandboxPageResult<T> {
+  items: T[];
+  page: number;
+  perPage: number;
+  totalCount: number;
+  hasMore: boolean;
+}
+
 export declare class Author {
   readonly id: string;
   readonly name: string;
@@ -363,8 +371,17 @@ export declare class Author {
   /** Get a cached Author by graph path, hydrating from the graph when needed */
   static get(query: { path: string; refresh?: boolean }): Promise<Author | null>;
 
-  /** List known Author instances */
-  static list(query?: { limit?: number; saveAs?: string; refresh?: boolean }): Promise<Author[]>;
+  /** Count Author instances without loading them into the heap */
+  static count(): Promise<number>;
+
+  /** Return one page of Author instances together with pagination metadata */
+  static page(query?: { page?: number; perPage?: number; limit?: number; saveAs?: string; refresh?: boolean }): Promise<SandboxPageResult<Author>>;
+
+  /** List one page of Author instances */
+  static list(query?: { page?: number; perPage?: number; limit?: number; saveAs?: string; refresh?: boolean }): Promise<Author[]>;
+
+  /** Stream Author instances page by page */
+  static iterate(query?: { page?: number; perPage?: number; limit?: number; maxItems?: number; refresh?: boolean }): AsyncIterable<Author>;
 
   /** Get biography of an author */
   get_bio(input?: { detailed?: boolean }): Promise<{ bio: string; source?: string }>;
@@ -384,7 +401,13 @@ export declare class Book {
 
   static get(query: { path: string; refresh?: boolean }): Promise<Book | null>;
 
-  static list(query?: { limit?: number; saveAs?: string; refresh?: boolean }): Promise<Book[]>;
+  static count(): Promise<number>;
+
+  static page(query?: { page?: number; perPage?: number; limit?: number; saveAs?: string; refresh?: boolean }): Promise<SandboxPageResult<Book>>;
+
+  static list(query?: { page?: number; perPage?: number; limit?: number; saveAs?: string; refresh?: boolean }): Promise<Book[]>;
+
+  static iterate(query?: { page?: number; perPage?: number; limit?: number; maxItems?: number; refresh?: boolean }): AsyncIterable<Book>;
 
   /** Navigate to author (many_to_one) */
   get_author(): Promise<Author | null>;
@@ -399,11 +422,18 @@ The LLM or user writes code against these typed classes:
 ```typescript
 import { Author, Book, global_search } from './sandbox-tools';
 
-const authors = await Author.list();
+const totalAuthors = await Author.count();
+const firstPage = await Author.page({ page: 1, perPage: 25 });
+const authors = firstPage.items;
 const tolkien = authors.find((author) => author.name === 'J.R.R. Tolkien');
 if (!tolkien) throw new Error('Author not found');
+console.log(totalAuthors, firstPage.hasMore);
 console.log(tolkien.name);              // "J.R.R. Tolkien"
 
+for await (const author of Author.iterate({ perPage: 100, maxItems: 200 })) {
+  console.log(author.id);
+}
+
 const bio = await tolkien.get_bio({ detailed: true });
 console.log(bio.bio);                   // typed as string
 
@@ -456,6 +486,16 @@ Defines domain ontology: classes (with typed properties), and relationships (wit
 ### `environment.recordObject(options)`
 Creates or updates a class instance with fields and relationships. Returns `{ path, id, created }`.
 
+### `environment.recordObjects(records, options?)`
+Batch upsert for many instances. The SDK sends **chunks** (default **100** rows per HTTP `POST` to `/records/batch`) with **retries** on transient failures, so large arrays do not time out as a single oversized request.
+
+Optional **`options`**:
+- **`batchSize`** — max rows per request (default 100).
+- **`concurrency`** — how many chunk requests may run in parallel (default 1, max 16); can reduce wall time when the server can overlap work.
+- **`onChunkComplete`** — async-friendly hook after each chunk for progress UIs; the returned array is always ordered like `records`.
+
+**Sync batch vs queued import:** use **`recordObjects`** when you need **synchronous** commits and/or per-chunk feedback. Use **`enqueueRecordImport`** + **`getRecordImport` / `getRecordImportSummary`** for **background** ingestion with aggregate counters when admission latency matters more than immediate row-by-row completion.
+
 ### `environment.getRelationships(modelPath)`
 Returns relationship definitions for a given class.
 

package/dist/agent-evals.d.mts

@@ -1,4 +1,4 @@
-import { P as Prompt, c as Environment, b as SessionHeapSnapshot, aZ as ManifestContent, ax as RecordObjectOptions, T as ToolWithHandler, G as Granular, C as ConnectOptions, y as CreateEnvironmentData, i as GranularOptions } from './client-BQw_gUK3.mjs';
+import { P as Prompt, d as Environment, c as SessionHeapSnapshot, a$ as ManifestContent, ax as RecordObjectOptions, T as ToolWithHandler, G as Granular, C as ConnectOptions, y as CreateEnvironmentData, i as GranularOptions } from './client-DLGC0mJk.mjs';
 import { GeneratedJobCodeIssue, HarnessControllerBudgets } from './agent-harness.mjs';
 import '@automerge/automerge';
 import '@automerge/automerge/slim';

package/dist/agent-evals.d.ts

@@ -1,4 +1,4 @@
-import { P as Prompt, c as Environment, b as SessionHeapSnapshot, aZ as ManifestContent, ax as RecordObjectOptions, T as ToolWithHandler, G as Granular, C as ConnectOptions, y as CreateEnvironmentData, i as GranularOptions } from './client-BQw_gUK3.js';
+import { P as Prompt, d as Environment, c as SessionHeapSnapshot, a$ as ManifestContent, ax as RecordObjectOptions, T as ToolWithHandler, G as Granular, C as ConnectOptions, y as CreateEnvironmentData, i as GranularOptions } from './client-DLGC0mJk.js';
 import { GeneratedJobCodeIssue, HarnessControllerBudgets } from './agent-harness.js';
 import '@automerge/automerge';
 import '@automerge/automerge/slim';

package/dist/agent-evals.js

@@ -4687,10 +4687,15 @@ var Session = class {
    * ```typescript
    * import { Author, Book, global_search } from './sandbox-tools';
    *
-   * const authors = await Author.list({ limit: 10, saveAs: 'recent_authors' });
+   * const totalAuthors = await Author.count();
+   * const firstAuthorsPage = await Author.page({ page: 1, perPage: 10, saveAs: 'recent_authors' });
+   * const authors = firstAuthorsPage.items;
    * const tolkien = await Author.get({ path: 'author_tolkien' });
    * const bio = await tolkien.get_bio({ detailed: true });
    * const books = await tolkien.get_books();
+   * for await (const author of Author.iterate({ perPage: 100, maxItems: 500 })) {
+   *   console.log(author.id);
+   * }
    * ```
    *
    * Effect calls (instance methods, static methods, global functions) trigger
@@ -11248,14 +11253,49 @@ var STANDARD_MODULES_OPERATIONS = [
   { create: "class", extends: "entity", has: {} },
   { create: "user", extends: "entity", has: { email: { value: void 0 }, firstName: { value: void 0 }, lastName: { value: void 0 } } },
   { create: "company", extends: "entity", has: { name: { value: void 0 }, website: { value: void 0 } } },
-  { create: "string", has: { value: { value: void 0 } } },
-  { create: "number", has: { value: { value: 0 } } },
-  { create: "boolean", has: { value: { value: false } } },
+  { create: "string", has: {} },
+  { create: "number", has: {} },
+  { create: "boolean", has: {} },
   { create: "tool_parameter", has: { name: { value: void 0 }, type: { value: "string" }, description: { value: void 0 }, required: { value: false } } }
 ];
 var BUILTIN_MODULES = {
   "standard_modules": STANDARD_MODULES_OPERATIONS
 };
+var DEFAULT_DIRECT_RECORD_OBJECTS_REQUEST_BATCH_SIZE = 100;
+var MAX_RECORD_OBJECTS_CONCURRENCY = 16;
+var DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_COUNT = 3;
+var DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_DELAY_MS = 1e3;
+var LOCAL_CONTROL_REQUEST_RETRY_COUNT = 4;
+var LOCAL_CONTROL_REQUEST_RETRY_DELAY_MS = 500;
+function planRecordObjectsChunks(records, batchSize) {
+  const total = records.length;
+  const size = Math.max(1, Math.min(batchSize, total));
+  const chunkCount = Math.ceil(total / size);
+  const plans = [];
+  for (let offset = 0, chunkIndex = 0; offset < total; offset += size, chunkIndex += 1) {
+    const slice = records.slice(offset, offset + size);
+    plans.push({ chunkIndex, chunkCount, offset, slice });
+  }
+  return plans;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isLocalControlUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname === "127.0.0.1" || parsed.hostname === "localhost" || parsed.hostname === "::1";
+  } catch {
+    return false;
+  }
+}
+function isRetryableLocalWorkerRestart(status, body, url) {
+  return isLocalControlUrl(url) && (status === 503 && body.includes("Your worker restarted mid-request") || status === 500 && body.includes("Network connection lost"));
+}
+function isRetryableRecordObjectsError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return /worker restarted mid-request|econnreset|network|socket connection was closed unexpectedly|timed out/i.test(message);
+}
 function computeEffectKey2(effect) {
   const attachedClass = effect.className?.trim();
   if (!attachedClass) {
@@ -12213,24 +12253,101 @@ var Environment = class extends Session {
   /**
    * Batch version of `recordObject()`.
    *
-   * Sends several upserts through the control-plane batch endpoint so the
-   * server can collapse the graph mutations into far fewer round trips.
+   * Sends rows through the control-plane **`/records/batch`** endpoint in **chunks** (default
+   * **100** records per HTTP request) so individual requests stay bounded and gateway timeouts are
+   * unlikely. Each chunk is retried on transient network / worker errors.
+   *
+   * Use the optional second argument to:
+   * - **`batchSize`** — rows per POST (smaller = more progress events; larger = fewer round trips).
+   * - **`concurrency`** — run up to N chunk POSTs in parallel (capped at 16) when you want lower wall time.
+   * - **`onChunkComplete`** — hook for UIs after each chunk succeeds (row order in the returned array
+   *   always matches `records`; chunk **completion** order may differ when `concurrency > 1`).
+   *
+   * For **asynchronous** ingestion with worker-side batching and aggregate counters (`queued`,
+   * `completed`, …), use **`enqueueRecordImport`** and poll **`getRecordImport`** /
+   * **`getRecordImportSummary`** — best for very large fire-and-forget loads when immediate
+   * synchronous commit of every row is not required.
    */
-  async recordObjects(records) {
+  async recordObjects(records, options) {
     if (!Array.isArray(records) || records.length === 0) {
       return [];
     }
-    const response = await this.controlPlaneRequest(
-      `/control/environments/${this.environmentId}/records/batch`,
-      {
-        method: "POST",
-        body: JSON.stringify({ records })
-      }
+    const batchSize = Math.max(
+      1,
+      Math.min(
+        records.length,
+        options?.batchSize ?? DEFAULT_DIRECT_RECORD_OBJECTS_REQUEST_BATCH_SIZE
+      )
     );
-    return Array.isArray(response.items) ? response.items : [];
+    const concurrency = Math.min(
+      MAX_RECORD_OBJECTS_CONCURRENCY,
+      Math.max(1, options?.concurrency ?? 1)
+    );
+    const plans = planRecordObjectsChunks(records, batchSize);
+    const total = records.length;
+    const results = new Array(total);
+    const onChunk = options?.onChunkComplete;
+    for (let waveStart = 0; waveStart < plans.length; waveStart += concurrency) {
+      const wave = plans.slice(waveStart, waveStart + concurrency);
+      await Promise.all(
+        wave.map(async (plan) => {
+          const { items, durationMs } = await this.executeRecordObjectsChunk(plan.slice);
+          if (items.length !== plan.slice.length) {
+            throw new Error(
+              `recordObjects: chunk ${plan.chunkIndex + 1} returned ${items.length} results, expected ${plan.slice.length}`
+            );
+          }
+          for (let index = 0; index < items.length; index += 1) {
+            results[plan.offset + index] = items[index];
+          }
+          if (onChunk) {
+            const info = {
+              chunkIndex: plan.chunkIndex,
+              totalChunks: plan.chunkCount,
+              offset: plan.offset,
+              recordCount: plan.slice.length,
+              durationMs,
+              results: items
+            };
+            await onChunk(info);
+          }
+        })
+      );
+    }
+    return results;
+  }
+  async executeRecordObjectsChunk(chunk) {
+    const wallStart = Date.now();
+    let lastError;
+    for (let attempt = 1; attempt <= DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_COUNT; attempt += 1) {
+      try {
+        const response = await this.controlPlaneRequest(
+          `/control/environments/${this.environmentId}/records/batch`,
+          {
+            method: "POST",
+            body: JSON.stringify({ records: chunk })
+          }
+        );
+        const items = Array.isArray(response.items) ? response.items : [];
+        return { items, durationMs: Date.now() - wallStart };
+      } catch (error) {
+        lastError = error;
+        if (!isRetryableRecordObjectsError(error) || attempt === DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_COUNT) {
+          throw error;
+        }
+        await sleep(DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_DELAY_MS * attempt);
+      }
+    }
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
   }
   /**
-   * Queue a background record import for this environment.
+   * Queue a background record import for this environment (async worker pipeline).
+   *
+   * **vs `recordObjects`:** this path accepts the full payload in one request, returns an
+   * **`importId`**, and processes rows in the background — use **`getRecordImport`** /
+   * **`getRecordImportSummary`** for progress. Choose it for large bulk loads where you do not
+   * need every row committed before the HTTP call returns. Use **`recordObjects`** when you need
+   * synchronous upserts and fine-grained chunk progress via **`onChunkComplete`**.
    */
   async enqueueRecordImport(records, options = {}) {
     return this.controlPlaneRequest(
@@ -13198,23 +13315,36 @@ var Granular = class _Granular {
     if (this.debugHttp) {
       console.log(`[SDK] Requesting: ${url}`);
     }
-    const response = await fetch(url, {
-      ...options,
-      headers: {
-        "Authorization": `Bearer ${this.apiKey}`,
-        "Content-Type": "application/json",
-        "Connection": "close",
-        ...options.headers
+    for (let attempt = 1; attempt <= LOCAL_CONTROL_REQUEST_RETRY_COUNT; attempt += 1) {
+      const response = await fetch(url, {
+        ...options,
+        headers: {
+          "Authorization": `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "Connection": "close",
+          ...options.headers
+        }
+      });
+      if (response.ok) {
+        if (response.status === 204) {
+          return { deleted: true };
+        }
+        return response.json();
       }
-    });
-    if (!response.ok) {
       const errorText = await response.text();
+      const retryable = isRetryableLocalWorkerRestart(response.status, errorText, url);
+      if (retryable && attempt < LOCAL_CONTROL_REQUEST_RETRY_COUNT) {
+        if (this.debugHttp) {
+          console.warn(
+            `[SDK] Retrying local control request after worker restart (${attempt}/${LOCAL_CONTROL_REQUEST_RETRY_COUNT - 1} retries used): ${url}`
+          );
+        }
+        await sleep(LOCAL_CONTROL_REQUEST_RETRY_DELAY_MS * attempt);
+        continue;
+      }
       throw new Error(`Granular API Error (${response.status}): ${errorText}`);
     }
-    if (response.status === 204) {
-      return { deleted: true };
-    }
-    return response.json();
+    throw new Error(`Granular API Error: exhausted retries for ${url}`);
   }
 };
 
@@ -14135,7 +14265,10 @@ ${loopBlock}
 - Only use classes, methods, and parameter shapes that are explicitly declared in those typedefs.
 - Never invent helper methods such as \`find(...)\` or unsupported parameters such as \`id\` when the typedefs require \`path\`.
 - Use \`ClassName.get({ path })\` only when you already know an object's graph path.
-- Use \`ClassName.list({ limit, saveAs })\` to load typed lists and persist reusable named lists in the heap.
+- Use \`ClassName.count()\` when you only need a total.
+- Use \`ClassName.page({ page, perPage, saveAs })\` when you need both records and pagination metadata like \`totalCount\` or \`hasMore\`.
+- Use \`ClassName.list({ page, perPage, saveAs })\` to load one typed page of records. \`limit\` is only a legacy alias for \`perPage\`.
+- Use \`for await (const item of ClassName.iterate({ perPage, maxItems }))\` for large batch jobs so you do not materialize the whole result set at once.
 - Instance methods: \`await instance.method_name(params)\`.
 - Static methods: \`await ClassName.static_method(params)\`.
 - Global effects: \`await effect_name(params)\`.
@@ -14147,7 +14280,7 @@ ${loopBlock}
 - Status fields are free-form operational strings, not strict enums. Normalize spelling mentally and do not rely on brittle hard-coded sets that miss variants like \`in-progress\`, \`in_progress\`, \`awaiting-part\`, or \`approval-submitted\`.
 - Do not discard a case, work order, part request, or shipment only because its status string does not match your preferred "open" spelling. If the record is otherwise the clear match, inspect it.
 - Reuse \`heap.getVar(name)\`, \`heap.setVar(name, value)\`, and \`heap.deleteVar(name)\` only when it clearly helps the next step. Do not mirror data into the heap just for completeness.
-- Prefer \`heap.setVar(name, value)\` for scalars or one selected instance. Prefer \`ClassName.list({ saveAs })\` for lists instead of \`heap.setVar(name, array)\`.
+- Prefer \`heap.setVar(name, value)\` for scalars or one selected instance. Prefer \`ClassName.list({ page, perPage, saveAs })\` for reusable list pages instead of \`heap.setVar(name, array)\`.
 - Never write an empty array into the heap. If a filtered list is empty, keep it local or clear the previous heap value with \`heap.deleteVar(name)\`.
 - Prefer heap-backed state that represents the current choice or recommendation. Avoid storing extra scalar bookkeeping unless it is needed for the next concrete step.
 - Only store true sandbox instances, typed lists of sandbox instances, or scalars in the heap. Results returned by static effects like availability/search helpers are often plain JSON, not sandbox instances.
@@ -14589,7 +14722,7 @@ ${modelOutputInstruction()}` },
         if (!response.ok) {
           const errorText = await response.text();
           if (attempt < 3 && (response.status >= 500 || response.status === 429)) {
-            await sleep(500 * attempt);
+            await sleep2(500 * attempt);
             continue;
           }
           throw new Error(`OpenAI chat generation failed: ${response.status} ${errorText}`);
@@ -14600,7 +14733,7 @@ ${modelOutputInstruction()}` },
         const parsed = extractJsonObject(text);
         if (!parsed) {
           if (attempt < 3) {
-            await sleep(300 * attempt);
+            await sleep2(300 * attempt);
             continue;
           }
           throw new Error(`Model output was not valid JSON:
@@ -14614,7 +14747,7 @@ ${text}`);
       } catch (error) {
         lastError = error instanceof Error ? error : new Error(String(error));
         if (attempt < 3 && /socket connection was closed unexpectedly|ECONNRESET|network|timed out/i.test(lastError.message)) {
-          await sleep(500 * attempt);
+          await sleep2(500 * attempt);
           continue;
         }
         throw lastError;
@@ -14626,7 +14759,7 @@ ${text}`);
 async function ensureDir(dir) {
   await promises.mkdir(dir, { recursive: true });
 }
-async function sleep(ms) {
+async function sleep2(ms) {
   await new Promise((resolve) => setTimeout(resolve, ms));
 }
 async function withTimeout(promise, ms, label) {
@@ -15069,7 +15202,7 @@ function createAgentEvalHarness(options) {
         stderr: [...pending.stderr, ...resumed.stderr]
       };
     }
-    await sleep(350);
+    await sleep2(350);
     const liveDoc = cloneJson(pending.conversation.environment.document);
     const presentation = resolveJobPresentation({
       jobId: pending.job.id,
@@ -15238,7 +15371,7 @@ function createAgentEvalHarness(options) {
       if (outcome.kind !== "completed") {
         throw new Error("Unexpected non-completed outcome after prompt handling");
       }
-      await sleep(350);
+      await sleep2(350);
       const settledLiveDoc = cloneJson(conversation.environment.document);
       const sessionHeap = normalizeHeapSnapshot2(asRecord4(settledLiveDoc?.heap));
       const presentation = resolveJobPresentation({