@granular-software/sdk 0.4.20 → 0.4.21

package/dist/index.mjs

@@ -4660,10 +4660,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
@@ -11221,9 +11226,9 @@ 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 = {
@@ -11233,6 +11238,8 @@ 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));
@@ -11247,6 +11254,17 @@ function planRecordObjectsChunks(records, batchSize) {
 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);
@@ -13270,23 +13288,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}`);
   }
 };
 
@@ -14212,7 +14243,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)\`.
@@ -14224,7 +14258,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.
@@ -14460,6 +14494,6 @@ function resolveJobPresentation({
   };
 }
 
-export { Environment, Granular, Session, WSClient, buildContinuationInstruction, buildGranularAgentCheckpointBlock, buildGranularAgentDomainBlock, buildGranularAgentHeapBlock, buildGranularAgentLoopBlock, buildGranularAgentSessionBlock, buildGranularAgentSystemPrompt, buildGranularAgentToolBlock, buildGranularAgentWorkflowBlock, createHarnessVerifierSnapshot, evaluateContinuation, extractPromptTokens, getCurrentClosureId, getExclusivePromptTarget, hasOpenPrompt, invokeRegisteredEffect, normalizeEffectBehaviors, normalizePrompt, normalizePromptText, normalizePromptType, projectHeapSummary, projectLoopSummary, projectWorkflowFocus, projectWorkflowSummary, resolveJobPresentation, resolvePromptAnswer, reviewGeneratedJobCode, scorePromptChoiceMatch };
+export { Environment, Granular, Session, WSClient, buildContinuationInstruction, buildGranularAgentCheckpointBlock, buildGranularAgentDomainBlock, buildGranularAgentHeapBlock, buildGranularAgentLoopBlock, buildGranularAgentSessionBlock, buildGranularAgentSystemPrompt, buildGranularAgentToolBlock, buildGranularAgentWorkflowBlock, createHarnessVerifierSnapshot, evaluateContinuation, extractPromptTokens, getCurrentClosureId, getExclusivePromptTarget, hasOpenPrompt, invokeRegisteredEffect, isLocalApiUrl, normalizeEffectBehaviors, normalizePrompt, normalizePromptText, normalizePromptType, projectHeapSummary, projectLoopSummary, projectWorkflowFocus, projectWorkflowSummary, resolveApiUrl, resolveAuthTokenForApiUrl, resolveJobPresentation, resolvePromptAnswer, reviewGeneratedJobCode, scorePromptChoiceMatch };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map