@granular-software/sdk 0.4.20 → 0.4.21

package/dist/cli/index.js

@@ -17990,10 +17990,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
@@ -18860,9 +18865,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 = {
@@ -18872,6 +18877,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));
@@ -18886,6 +18893,17 @@ function planRecordObjectsChunks(records, batchSize) {
 function sleep(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, 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(error2) {
   const message = error2 instanceof Error ? error2.message : String(error2);
   return /worker restarted mid-request|econnreset|network|socket connection was closed unexpectedly|timed out/i.test(message);
@@ -20909,23 +20927,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}`);
   }
 };
 

package/dist/{client-DWYdWpS-.d.mts → client-DLGC0mJk.d.mts}

@@ -1314,10 +1314,15 @@ declare class Session {
      * ```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
@@ -2048,4 +2053,4 @@ declare class Granular {
     private request;
 }
 
-export { type EffectInvocationMode as $, type AccessTokenProvider as A, type BuildPolicy as B, type ConnectOptions as C, type DomainState as D, type EffectHandlerContext as E, type Manifest as F, Granular as G, type ManifestListResponse as H, type InstanceToolHandler as I, type BuildStatus as J, type Build as K, type Version as L, type ManifestEffectMetamodelSpec as M, type BuildListResponse as N, type SemanticVersionDiffEntry as O, type Prompt as P, type SemanticVersionDiff as Q, type ResolvedEffectBehaviors as R, type SessionHeapEntry as S, type ToolWithHandler as T, type User as U, type VersionTracking as V, WSClient as W, type ResolvedEffectPostCondition as X, type ResolvedEffectDryRun as Y, type ResolvedEffectReverse as Z, type ResolvedEffectApprovalRequired as _, type SessionHeapList as a, type ManifestContent as a$, type EffectInvocationMetadata as a0, type EffectSchema as a1, type EffectWithHandler as a2, type PublishEffectsResult as a3, type ToolInfo as a4, type EffectInfo as a5, type ToolsChangedEvent as a6, type EffectsChangedEvent as a7, type EffectHandler as a8, type InstanceEffectHandler as a9, type RecordObjectsOptions as aA, type RecordImportStatus as aB, type RecordImportItemStatus as aC, type RecordImportStats as aD, type RecordImportItem as aE, type RecordImport as aF, type EnvironmentRecordImportSummary as aG, type ManifestPropertySpec as aH, type ManifestValidationOperator as aI, type ManifestEnumRuleSpec as aJ, type ManifestFilterBySpec as aK, type ManifestValidationRuleSpec as aL, type ManifestStateMachineStateSpec as aM, type ManifestStateMachineTransitionSpec as aN, type ManifestStateMachineSpec as aO, type ManifestPostConditionSpec as aP, type ManifestDryRunSpec as aQ, type ManifestReverseSpec as aR, type ManifestApprovalRequiredSpec as aS, type ManifestRelationshipDef as aT, type ManifestEffectSchema as aU, type ManifestEffectDeclaration as aV, type ManifestEventTypeDef as aW, type ManifestEventStreamDef as aX, type ManifestOperation as aY, type ManifestImport as aZ, type ManifestVolume as a_, type JobStatus as aa, type JobFeedbackSentiment as ab, type JobFeedbackToolCall as ac, type JobFeedbackMetadata as ad, type JobFeedbackInput as ae, type JobFeedbackRecord as af, type JobSubmitResult as ag, type Job as ah, type SessionHeapFieldType as ai, type SessionHeapFieldValue as aj, type SessionHeapVariable as ak, type WSDisconnectInfo as al, type WSReconnectErrorInfo as am, type WSClientOptions as an, type RPCRequest as ao, type RPCResponse as ap, type SyncMessage as aq, type RPCRequestFromServer as ar, type ToolInvokeParams as as, type ToolResultParams as at, type ModelRef as au, type RelationshipInfo as av, type DefineRelationshipOptions as aw, type RecordObjectOptions as ax, type RecordObjectResult as ay, type RecordObjectsChunkInfo as az, type SessionHeapSnapshot as b, type GraphQLResult as b0, type APIError as b1, type DeleteResponse as b2, type StreamEvent as b3, type StreamSubscription as b4, type StreamStats as b5, Environment as c, Session as d, type ToolSchema as e, type PublishToolsResult as f, type ToolHandler as g, type EndpointMode as h, type GranularOptions as i, type GranularAuth as j, type RecordUserOptions as k, type Subject as l, type ConversationSessionInfo as m, type Sandbox as n, type CreateSandboxData as o, type SandboxListResponse as p, type PermissionRules as q, type PermissionProfile as r, type CreatePermissionProfileData as s, type PermissionProfileListResponse as t, type Assignment as u, type AssignmentListResponse as v, type VersionTag as w, type EnvironmentData as x, type CreateEnvironmentData as y, type EnvironmentListResponse as z };
+export { type EffectInvocationMode as $, type AccessTokenProvider as A, type BuildPolicy as B, type ConnectOptions as C, type DomainState as D, type EndpointMode as E, type Manifest as F, Granular as G, type ManifestListResponse as H, type InstanceToolHandler as I, type BuildStatus as J, type Build as K, type Version as L, type ManifestEffectMetamodelSpec as M, type BuildListResponse as N, type SemanticVersionDiffEntry as O, type Prompt as P, type SemanticVersionDiff as Q, type ResolvedEffectBehaviors as R, type SessionHeapEntry as S, type ToolWithHandler as T, type User as U, type VersionTracking as V, WSClient as W, type ResolvedEffectPostCondition as X, type ResolvedEffectDryRun as Y, type ResolvedEffectReverse as Z, type ResolvedEffectApprovalRequired as _, type EffectHandlerContext as a, type ManifestContent as a$, type EffectInvocationMetadata as a0, type EffectSchema as a1, type EffectWithHandler as a2, type PublishEffectsResult as a3, type ToolInfo as a4, type EffectInfo as a5, type ToolsChangedEvent as a6, type EffectsChangedEvent as a7, type EffectHandler as a8, type InstanceEffectHandler as a9, type RecordObjectsOptions as aA, type RecordImportStatus as aB, type RecordImportItemStatus as aC, type RecordImportStats as aD, type RecordImportItem as aE, type RecordImport as aF, type EnvironmentRecordImportSummary as aG, type ManifestPropertySpec as aH, type ManifestValidationOperator as aI, type ManifestEnumRuleSpec as aJ, type ManifestFilterBySpec as aK, type ManifestValidationRuleSpec as aL, type ManifestStateMachineStateSpec as aM, type ManifestStateMachineTransitionSpec as aN, type ManifestStateMachineSpec as aO, type ManifestPostConditionSpec as aP, type ManifestDryRunSpec as aQ, type ManifestReverseSpec as aR, type ManifestApprovalRequiredSpec as aS, type ManifestRelationshipDef as aT, type ManifestEffectSchema as aU, type ManifestEffectDeclaration as aV, type ManifestEventTypeDef as aW, type ManifestEventStreamDef as aX, type ManifestOperation as aY, type ManifestImport as aZ, type ManifestVolume as a_, type JobStatus as aa, type JobFeedbackSentiment as ab, type JobFeedbackToolCall as ac, type JobFeedbackMetadata as ad, type JobFeedbackInput as ae, type JobFeedbackRecord as af, type JobSubmitResult as ag, type Job as ah, type SessionHeapFieldType as ai, type SessionHeapFieldValue as aj, type SessionHeapVariable as ak, type WSDisconnectInfo as al, type WSReconnectErrorInfo as am, type WSClientOptions as an, type RPCRequest as ao, type RPCResponse as ap, type SyncMessage as aq, type RPCRequestFromServer as ar, type ToolInvokeParams as as, type ToolResultParams as at, type ModelRef as au, type RelationshipInfo as av, type DefineRelationshipOptions as aw, type RecordObjectOptions as ax, type RecordObjectResult as ay, type RecordObjectsChunkInfo as az, type SessionHeapList as b, type GraphQLResult as b0, type APIError as b1, type DeleteResponse as b2, type StreamEvent as b3, type StreamSubscription as b4, type StreamStats as b5, type SessionHeapSnapshot as c, Environment as d, Session as e, type ToolSchema as f, type PublishToolsResult as g, type ToolHandler as h, type GranularOptions as i, type GranularAuth as j, type RecordUserOptions as k, type Subject as l, type ConversationSessionInfo as m, type Sandbox as n, type CreateSandboxData as o, type SandboxListResponse as p, type PermissionRules as q, type PermissionProfile as r, type CreatePermissionProfileData as s, type PermissionProfileListResponse as t, type Assignment as u, type AssignmentListResponse as v, type VersionTag as w, type EnvironmentData as x, type CreateEnvironmentData as y, type EnvironmentListResponse as z };

package/dist/{client-DWYdWpS-.d.ts → client-DLGC0mJk.d.ts}

@@ -1314,10 +1314,15 @@ declare class Session {
      * ```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
@@ -2048,4 +2053,4 @@ declare class Granular {
     private request;
 }
 
-export { type EffectInvocationMode as $, type AccessTokenProvider as A, type BuildPolicy as B, type ConnectOptions as C, type DomainState as D, type EffectHandlerContext as E, type Manifest as F, Granular as G, type ManifestListResponse as H, type InstanceToolHandler as I, type BuildStatus as J, type Build as K, type Version as L, type ManifestEffectMetamodelSpec as M, type BuildListResponse as N, type SemanticVersionDiffEntry as O, type Prompt as P, type SemanticVersionDiff as Q, type ResolvedEffectBehaviors as R, type SessionHeapEntry as S, type ToolWithHandler as T, type User as U, type VersionTracking as V, WSClient as W, type ResolvedEffectPostCondition as X, type ResolvedEffectDryRun as Y, type ResolvedEffectReverse as Z, type ResolvedEffectApprovalRequired as _, type SessionHeapList as a, type ManifestContent as a$, type EffectInvocationMetadata as a0, type EffectSchema as a1, type EffectWithHandler as a2, type PublishEffectsResult as a3, type ToolInfo as a4, type EffectInfo as a5, type ToolsChangedEvent as a6, type EffectsChangedEvent as a7, type EffectHandler as a8, type InstanceEffectHandler as a9, type RecordObjectsOptions as aA, type RecordImportStatus as aB, type RecordImportItemStatus as aC, type RecordImportStats as aD, type RecordImportItem as aE, type RecordImport as aF, type EnvironmentRecordImportSummary as aG, type ManifestPropertySpec as aH, type ManifestValidationOperator as aI, type ManifestEnumRuleSpec as aJ, type ManifestFilterBySpec as aK, type ManifestValidationRuleSpec as aL, type ManifestStateMachineStateSpec as aM, type ManifestStateMachineTransitionSpec as aN, type ManifestStateMachineSpec as aO, type ManifestPostConditionSpec as aP, type ManifestDryRunSpec as aQ, type ManifestReverseSpec as aR, type ManifestApprovalRequiredSpec as aS, type ManifestRelationshipDef as aT, type ManifestEffectSchema as aU, type ManifestEffectDeclaration as aV, type ManifestEventTypeDef as aW, type ManifestEventStreamDef as aX, type ManifestOperation as aY, type ManifestImport as aZ, type ManifestVolume as a_, type JobStatus as aa, type JobFeedbackSentiment as ab, type JobFeedbackToolCall as ac, type JobFeedbackMetadata as ad, type JobFeedbackInput as ae, type JobFeedbackRecord as af, type JobSubmitResult as ag, type Job as ah, type SessionHeapFieldType as ai, type SessionHeapFieldValue as aj, type SessionHeapVariable as ak, type WSDisconnectInfo as al, type WSReconnectErrorInfo as am, type WSClientOptions as an, type RPCRequest as ao, type RPCResponse as ap, type SyncMessage as aq, type RPCRequestFromServer as ar, type ToolInvokeParams as as, type ToolResultParams as at, type ModelRef as au, type RelationshipInfo as av, type DefineRelationshipOptions as aw, type RecordObjectOptions as ax, type RecordObjectResult as ay, type RecordObjectsChunkInfo as az, type SessionHeapSnapshot as b, type GraphQLResult as b0, type APIError as b1, type DeleteResponse as b2, type StreamEvent as b3, type StreamSubscription as b4, type StreamStats as b5, Environment as c, Session as d, type ToolSchema as e, type PublishToolsResult as f, type ToolHandler as g, type EndpointMode as h, type GranularOptions as i, type GranularAuth as j, type RecordUserOptions as k, type Subject as l, type ConversationSessionInfo as m, type Sandbox as n, type CreateSandboxData as o, type SandboxListResponse as p, type PermissionRules as q, type PermissionProfile as r, type CreatePermissionProfileData as s, type PermissionProfileListResponse as t, type Assignment as u, type AssignmentListResponse as v, type VersionTag as w, type EnvironmentData as x, type CreateEnvironmentData as y, type EnvironmentListResponse as z };
+export { type EffectInvocationMode as $, type AccessTokenProvider as A, type BuildPolicy as B, type ConnectOptions as C, type DomainState as D, type EndpointMode as E, type Manifest as F, Granular as G, type ManifestListResponse as H, type InstanceToolHandler as I, type BuildStatus as J, type Build as K, type Version as L, type ManifestEffectMetamodelSpec as M, type BuildListResponse as N, type SemanticVersionDiffEntry as O, type Prompt as P, type SemanticVersionDiff as Q, type ResolvedEffectBehaviors as R, type SessionHeapEntry as S, type ToolWithHandler as T, type User as U, type VersionTracking as V, WSClient as W, type ResolvedEffectPostCondition as X, type ResolvedEffectDryRun as Y, type ResolvedEffectReverse as Z, type ResolvedEffectApprovalRequired as _, type EffectHandlerContext as a, type ManifestContent as a$, type EffectInvocationMetadata as a0, type EffectSchema as a1, type EffectWithHandler as a2, type PublishEffectsResult as a3, type ToolInfo as a4, type EffectInfo as a5, type ToolsChangedEvent as a6, type EffectsChangedEvent as a7, type EffectHandler as a8, type InstanceEffectHandler as a9, type RecordObjectsOptions as aA, type RecordImportStatus as aB, type RecordImportItemStatus as aC, type RecordImportStats as aD, type RecordImportItem as aE, type RecordImport as aF, type EnvironmentRecordImportSummary as aG, type ManifestPropertySpec as aH, type ManifestValidationOperator as aI, type ManifestEnumRuleSpec as aJ, type ManifestFilterBySpec as aK, type ManifestValidationRuleSpec as aL, type ManifestStateMachineStateSpec as aM, type ManifestStateMachineTransitionSpec as aN, type ManifestStateMachineSpec as aO, type ManifestPostConditionSpec as aP, type ManifestDryRunSpec as aQ, type ManifestReverseSpec as aR, type ManifestApprovalRequiredSpec as aS, type ManifestRelationshipDef as aT, type ManifestEffectSchema as aU, type ManifestEffectDeclaration as aV, type ManifestEventTypeDef as aW, type ManifestEventStreamDef as aX, type ManifestOperation as aY, type ManifestImport as aZ, type ManifestVolume as a_, type JobStatus as aa, type JobFeedbackSentiment as ab, type JobFeedbackToolCall as ac, type JobFeedbackMetadata as ad, type JobFeedbackInput as ae, type JobFeedbackRecord as af, type JobSubmitResult as ag, type Job as ah, type SessionHeapFieldType as ai, type SessionHeapFieldValue as aj, type SessionHeapVariable as ak, type WSDisconnectInfo as al, type WSReconnectErrorInfo as am, type WSClientOptions as an, type RPCRequest as ao, type RPCResponse as ap, type SyncMessage as aq, type RPCRequestFromServer as ar, type ToolInvokeParams as as, type ToolResultParams as at, type ModelRef as au, type RelationshipInfo as av, type DefineRelationshipOptions as aw, type RecordObjectOptions as ax, type RecordObjectResult as ay, type RecordObjectsChunkInfo as az, type SessionHeapList as b, type GraphQLResult as b0, type APIError as b1, type DeleteResponse as b2, type StreamEvent as b3, type StreamSubscription as b4, type StreamStats as b5, type SessionHeapSnapshot as c, Environment as d, Session as e, type ToolSchema as f, type PublishToolsResult as g, type ToolHandler as h, type GranularOptions as i, type GranularAuth as j, type RecordUserOptions as k, type Subject as l, type ConversationSessionInfo as m, type Sandbox as n, type CreateSandboxData as o, type SandboxListResponse as p, type PermissionRules as q, type PermissionProfile as r, type CreatePermissionProfileData as s, type PermissionProfileListResponse as t, type Assignment as u, type AssignmentListResponse as v, type VersionTag as w, type EnvironmentData as x, type CreateEnvironmentData as y, type EnvironmentListResponse as z };

package/dist/index.d.mts

@@ -1,9 +1,24 @@
-import { T as ToolWithHandler, E as EffectHandlerContext, M as ManifestEffectMetamodelSpec, R as ResolvedEffectBehaviors, S as SessionHeapEntry, a as SessionHeapList, b as SessionHeapSnapshot, P as Prompt } from './client-DWYdWpS-.mjs';
-export { b1 as APIError, A as AccessTokenProvider, u as Assignment, v as AssignmentListResponse, K as Build, N as BuildListResponse, B as BuildPolicy, J as BuildStatus, C as ConnectOptions, m as ConversationSessionInfo, y as CreateEnvironmentData, s as CreatePermissionProfileData, o as CreateSandboxData, aw as DefineRelationshipOptions, b2 as DeleteResponse, D as DomainState, a8 as EffectHandler, a5 as EffectInfo, a0 as EffectInvocationMetadata, $ as EffectInvocationMode, a1 as EffectSchema, a2 as EffectWithHandler, a7 as EffectsChangedEvent, h as EndpointMode, c as Environment, x as EnvironmentData, z as EnvironmentListResponse, aG as EnvironmentRecordImportSummary, G as Granular, j as GranularAuth, i as GranularOptions, b0 as GraphQLResult, a9 as InstanceEffectHandler, I as InstanceToolHandler, ah as Job, ae as JobFeedbackInput, ad as JobFeedbackMetadata, af as JobFeedbackRecord, ab as JobFeedbackSentiment, ac as JobFeedbackToolCall, aa as JobStatus, ag as JobSubmitResult, F as Manifest, aS as ManifestApprovalRequiredSpec, a$ as ManifestContent, aQ as ManifestDryRunSpec, aV as ManifestEffectDeclaration, aU as ManifestEffectSchema, aJ as ManifestEnumRuleSpec, aX as ManifestEventStreamDef, aW as ManifestEventTypeDef, aK as ManifestFilterBySpec, aZ as ManifestImport, H as ManifestListResponse, aY as ManifestOperation, aP as ManifestPostConditionSpec, aH as ManifestPropertySpec, aT as ManifestRelationshipDef, aR as ManifestReverseSpec, aO as ManifestStateMachineSpec, aM as ManifestStateMachineStateSpec, aN as ManifestStateMachineTransitionSpec, aI as ManifestValidationOperator, aL as ManifestValidationRuleSpec, a_ as ManifestVolume, au as ModelRef, r as PermissionProfile, t as PermissionProfileListResponse, q as PermissionRules, a3 as PublishEffectsResult, f as PublishToolsResult, ao as RPCRequest, ar as RPCRequestFromServer, ap as RPCResponse, aF as RecordImport, aE as RecordImportItem, aC as RecordImportItemStatus, aD as RecordImportStats, aB as RecordImportStatus, ax as RecordObjectOptions, ay as RecordObjectResult, az as RecordObjectsChunkInfo, aA as RecordObjectsOptions, k as RecordUserOptions, av as RelationshipInfo, _ as ResolvedEffectApprovalRequired, Y as ResolvedEffectDryRun, X as ResolvedEffectPostCondition, Z as ResolvedEffectReverse, n as Sandbox, p as SandboxListResponse, Q as SemanticVersionDiff, O as SemanticVersionDiffEntry, d as Session, ai as SessionHeapFieldType, aj as SessionHeapFieldValue, ak as SessionHeapVariable, b3 as StreamEvent, b5 as StreamStats, b4 as StreamSubscription, l as Subject, aq as SyncMessage, g as ToolHandler, a4 as ToolInfo, as as ToolInvokeParams, at as ToolResultParams, e as ToolSchema, a6 as ToolsChangedEvent, U as User, L as Version, w as VersionTag, V as VersionTracking, W as WSClient, an as WSClientOptions, al as WSDisconnectInfo, am as WSReconnectErrorInfo } from './client-DWYdWpS-.mjs';
+import { E as EndpointMode, T as ToolWithHandler, a as EffectHandlerContext, M as ManifestEffectMetamodelSpec, R as ResolvedEffectBehaviors, S as SessionHeapEntry, b as SessionHeapList, c as SessionHeapSnapshot, P as Prompt } from './client-DLGC0mJk.mjs';
+export { b1 as APIError, A as AccessTokenProvider, u as Assignment, v as AssignmentListResponse, K as Build, N as BuildListResponse, B as BuildPolicy, J as BuildStatus, C as ConnectOptions, m as ConversationSessionInfo, y as CreateEnvironmentData, s as CreatePermissionProfileData, o as CreateSandboxData, aw as DefineRelationshipOptions, b2 as DeleteResponse, D as DomainState, a8 as EffectHandler, a5 as EffectInfo, a0 as EffectInvocationMetadata, $ as EffectInvocationMode, a1 as EffectSchema, a2 as EffectWithHandler, a7 as EffectsChangedEvent, d as Environment, x as EnvironmentData, z as EnvironmentListResponse, aG as EnvironmentRecordImportSummary, G as Granular, j as GranularAuth, i as GranularOptions, b0 as GraphQLResult, a9 as InstanceEffectHandler, I as InstanceToolHandler, ah as Job, ae as JobFeedbackInput, ad as JobFeedbackMetadata, af as JobFeedbackRecord, ab as JobFeedbackSentiment, ac as JobFeedbackToolCall, aa as JobStatus, ag as JobSubmitResult, F as Manifest, aS as ManifestApprovalRequiredSpec, a$ as ManifestContent, aQ as ManifestDryRunSpec, aV as ManifestEffectDeclaration, aU as ManifestEffectSchema, aJ as ManifestEnumRuleSpec, aX as ManifestEventStreamDef, aW as ManifestEventTypeDef, aK as ManifestFilterBySpec, aZ as ManifestImport, H as ManifestListResponse, aY as ManifestOperation, aP as ManifestPostConditionSpec, aH as ManifestPropertySpec, aT as ManifestRelationshipDef, aR as ManifestReverseSpec, aO as ManifestStateMachineSpec, aM as ManifestStateMachineStateSpec, aN as ManifestStateMachineTransitionSpec, aI as ManifestValidationOperator, aL as ManifestValidationRuleSpec, a_ as ManifestVolume, au as ModelRef, r as PermissionProfile, t as PermissionProfileListResponse, q as PermissionRules, a3 as PublishEffectsResult, g as PublishToolsResult, ao as RPCRequest, ar as RPCRequestFromServer, ap as RPCResponse, aF as RecordImport, aE as RecordImportItem, aC as RecordImportItemStatus, aD as RecordImportStats, aB as RecordImportStatus, ax as RecordObjectOptions, ay as RecordObjectResult, az as RecordObjectsChunkInfo, aA as RecordObjectsOptions, k as RecordUserOptions, av as RelationshipInfo, _ as ResolvedEffectApprovalRequired, Y as ResolvedEffectDryRun, X as ResolvedEffectPostCondition, Z as ResolvedEffectReverse, n as Sandbox, p as SandboxListResponse, Q as SemanticVersionDiff, O as SemanticVersionDiffEntry, e as Session, ai as SessionHeapFieldType, aj as SessionHeapFieldValue, ak as SessionHeapVariable, b3 as StreamEvent, b5 as StreamStats, b4 as StreamSubscription, l as Subject, aq as SyncMessage, h as ToolHandler, a4 as ToolInfo, as as ToolInvokeParams, at as ToolResultParams, f as ToolSchema, a6 as ToolsChangedEvent, U as User, L as Version, w as VersionTag, V as VersionTracking, W as WSClient, an as WSClientOptions, al as WSDisconnectInfo, am as WSReconnectErrorInfo } from './client-DLGC0mJk.mjs';
 export { BuildGranularAgentSystemPromptInput, GeneratedJobCodeIssue, GranularAgentExecutionCheckpoint, GranularAgentHeapSummaryOptions, GranularAgentSessionContext, GranularAgentToolInfo, GranularAgentWorkflowFocus, HarnessContinuationDecision, HarnessControllerBudgets, HarnessProjectionOptions, HarnessPromptLike, HarnessVerifierSnapshot, HarnessVerifierSnapshotInput, buildContinuationInstruction, buildGranularAgentCheckpointBlock, buildGranularAgentDomainBlock, buildGranularAgentHeapBlock, buildGranularAgentLoopBlock, buildGranularAgentSessionBlock, buildGranularAgentSystemPrompt, buildGranularAgentToolBlock, buildGranularAgentWorkflowBlock, createHarnessVerifierSnapshot, evaluateContinuation, getCurrentClosureId, getExclusivePromptTarget, hasOpenPrompt, projectHeapSummary, projectLoopSummary, projectWorkflowFocus, projectWorkflowSummary, reviewGeneratedJobCode } from './agent-harness.mjs';
 import '@automerge/automerge';
 import '@automerge/automerge/slim';
 
+declare function isLocalApiUrl(url: string): boolean;
+/**
+ * Local dev + `sk_*` (WorkOS org key in env): map to the local gn_sk e2e key by default so every
+ * request (HTTP + WebSocket) uses the same tenant as the v2 UI on localhost (`default`). Without
+ * this, the SDK passes `sk_*` through → gateway resolves org_… while the UI still uses gn_sk →
+ * you only see old default-tenant sandboxes and new ingest data looks “missing”.
+ *
+ * - `GRANULAR_LOCAL_API_KEY` — explicit key to use instead (e.g. another gn_sk).
+ * - `GRANULAR_DISABLE_LOCAL_API_KEY_FALLBACK=1` — do not swap; send the real `sk_*` (org tenant +
+ *   WorkOS validation on the gateway). Use when the UI is also on that org (e.g. session auth +
+ *   NEXT_PUBLIC_DISABLE_LOCAL_API_KEY_FALLBACK on the app).
+ */
+declare function resolveAuthTokenForApiUrl(authToken: string, apiUrl: string): string;
+declare function resolveApiUrl(explicitApiUrl?: string, mode?: EndpointMode): string;
+
 type EffectRuntimeRequest = {
     effectKey: string;
     effectName: string;
@@ -41,4 +56,4 @@ declare function normalizePromptType(raw: Record<string, unknown> | null | undef
 declare function normalizePrompt(rawValue: unknown): Prompt | null;
 declare function resolvePromptAnswer(prompt: Prompt | undefined, answer: unknown): unknown;
 
-export { EffectHandlerContext, type JobPresentation, ManifestEffectMetamodelSpec, Prompt, ResolvedEffectBehaviors, SessionHeapEntry, SessionHeapList, SessionHeapSnapshot, ToolWithHandler, extractPromptTokens, invokeRegisteredEffect, normalizeEffectBehaviors, normalizePrompt, normalizePromptText, normalizePromptType, resolveJobPresentation, resolvePromptAnswer, scorePromptChoiceMatch };
+export { EffectHandlerContext, EndpointMode, type JobPresentation, ManifestEffectMetamodelSpec, Prompt, ResolvedEffectBehaviors, SessionHeapEntry, SessionHeapList, SessionHeapSnapshot, ToolWithHandler, extractPromptTokens, invokeRegisteredEffect, isLocalApiUrl, normalizeEffectBehaviors, normalizePrompt, normalizePromptText, normalizePromptType, resolveApiUrl, resolveAuthTokenForApiUrl, resolveJobPresentation, resolvePromptAnswer, scorePromptChoiceMatch };

package/dist/index.d.ts

@@ -1,9 +1,24 @@
-import { T as ToolWithHandler, E as EffectHandlerContext, M as ManifestEffectMetamodelSpec, R as ResolvedEffectBehaviors, S as SessionHeapEntry, a as SessionHeapList, b as SessionHeapSnapshot, P as Prompt } from './client-DWYdWpS-.js';
-export { b1 as APIError, A as AccessTokenProvider, u as Assignment, v as AssignmentListResponse, K as Build, N as BuildListResponse, B as BuildPolicy, J as BuildStatus, C as ConnectOptions, m as ConversationSessionInfo, y as CreateEnvironmentData, s as CreatePermissionProfileData, o as CreateSandboxData, aw as DefineRelationshipOptions, b2 as DeleteResponse, D as DomainState, a8 as EffectHandler, a5 as EffectInfo, a0 as EffectInvocationMetadata, $ as EffectInvocationMode, a1 as EffectSchema, a2 as EffectWithHandler, a7 as EffectsChangedEvent, h as EndpointMode, c as Environment, x as EnvironmentData, z as EnvironmentListResponse, aG as EnvironmentRecordImportSummary, G as Granular, j as GranularAuth, i as GranularOptions, b0 as GraphQLResult, a9 as InstanceEffectHandler, I as InstanceToolHandler, ah as Job, ae as JobFeedbackInput, ad as JobFeedbackMetadata, af as JobFeedbackRecord, ab as JobFeedbackSentiment, ac as JobFeedbackToolCall, aa as JobStatus, ag as JobSubmitResult, F as Manifest, aS as ManifestApprovalRequiredSpec, a$ as ManifestContent, aQ as ManifestDryRunSpec, aV as ManifestEffectDeclaration, aU as ManifestEffectSchema, aJ as ManifestEnumRuleSpec, aX as ManifestEventStreamDef, aW as ManifestEventTypeDef, aK as ManifestFilterBySpec, aZ as ManifestImport, H as ManifestListResponse, aY as ManifestOperation, aP as ManifestPostConditionSpec, aH as ManifestPropertySpec, aT as ManifestRelationshipDef, aR as ManifestReverseSpec, aO as ManifestStateMachineSpec, aM as ManifestStateMachineStateSpec, aN as ManifestStateMachineTransitionSpec, aI as ManifestValidationOperator, aL as ManifestValidationRuleSpec, a_ as ManifestVolume, au as ModelRef, r as PermissionProfile, t as PermissionProfileListResponse, q as PermissionRules, a3 as PublishEffectsResult, f as PublishToolsResult, ao as RPCRequest, ar as RPCRequestFromServer, ap as RPCResponse, aF as RecordImport, aE as RecordImportItem, aC as RecordImportItemStatus, aD as RecordImportStats, aB as RecordImportStatus, ax as RecordObjectOptions, ay as RecordObjectResult, az as RecordObjectsChunkInfo, aA as RecordObjectsOptions, k as RecordUserOptions, av as RelationshipInfo, _ as ResolvedEffectApprovalRequired, Y as ResolvedEffectDryRun, X as ResolvedEffectPostCondition, Z as ResolvedEffectReverse, n as Sandbox, p as SandboxListResponse, Q as SemanticVersionDiff, O as SemanticVersionDiffEntry, d as Session, ai as SessionHeapFieldType, aj as SessionHeapFieldValue, ak as SessionHeapVariable, b3 as StreamEvent, b5 as StreamStats, b4 as StreamSubscription, l as Subject, aq as SyncMessage, g as ToolHandler, a4 as ToolInfo, as as ToolInvokeParams, at as ToolResultParams, e as ToolSchema, a6 as ToolsChangedEvent, U as User, L as Version, w as VersionTag, V as VersionTracking, W as WSClient, an as WSClientOptions, al as WSDisconnectInfo, am as WSReconnectErrorInfo } from './client-DWYdWpS-.js';
+import { E as EndpointMode, T as ToolWithHandler, a as EffectHandlerContext, M as ManifestEffectMetamodelSpec, R as ResolvedEffectBehaviors, S as SessionHeapEntry, b as SessionHeapList, c as SessionHeapSnapshot, P as Prompt } from './client-DLGC0mJk.js';
+export { b1 as APIError, A as AccessTokenProvider, u as Assignment, v as AssignmentListResponse, K as Build, N as BuildListResponse, B as BuildPolicy, J as BuildStatus, C as ConnectOptions, m as ConversationSessionInfo, y as CreateEnvironmentData, s as CreatePermissionProfileData, o as CreateSandboxData, aw as DefineRelationshipOptions, b2 as DeleteResponse, D as DomainState, a8 as EffectHandler, a5 as EffectInfo, a0 as EffectInvocationMetadata, $ as EffectInvocationMode, a1 as EffectSchema, a2 as EffectWithHandler, a7 as EffectsChangedEvent, d as Environment, x as EnvironmentData, z as EnvironmentListResponse, aG as EnvironmentRecordImportSummary, G as Granular, j as GranularAuth, i as GranularOptions, b0 as GraphQLResult, a9 as InstanceEffectHandler, I as InstanceToolHandler, ah as Job, ae as JobFeedbackInput, ad as JobFeedbackMetadata, af as JobFeedbackRecord, ab as JobFeedbackSentiment, ac as JobFeedbackToolCall, aa as JobStatus, ag as JobSubmitResult, F as Manifest, aS as ManifestApprovalRequiredSpec, a$ as ManifestContent, aQ as ManifestDryRunSpec, aV as ManifestEffectDeclaration, aU as ManifestEffectSchema, aJ as ManifestEnumRuleSpec, aX as ManifestEventStreamDef, aW as ManifestEventTypeDef, aK as ManifestFilterBySpec, aZ as ManifestImport, H as ManifestListResponse, aY as ManifestOperation, aP as ManifestPostConditionSpec, aH as ManifestPropertySpec, aT as ManifestRelationshipDef, aR as ManifestReverseSpec, aO as ManifestStateMachineSpec, aM as ManifestStateMachineStateSpec, aN as ManifestStateMachineTransitionSpec, aI as ManifestValidationOperator, aL as ManifestValidationRuleSpec, a_ as ManifestVolume, au as ModelRef, r as PermissionProfile, t as PermissionProfileListResponse, q as PermissionRules, a3 as PublishEffectsResult, g as PublishToolsResult, ao as RPCRequest, ar as RPCRequestFromServer, ap as RPCResponse, aF as RecordImport, aE as RecordImportItem, aC as RecordImportItemStatus, aD as RecordImportStats, aB as RecordImportStatus, ax as RecordObjectOptions, ay as RecordObjectResult, az as RecordObjectsChunkInfo, aA as RecordObjectsOptions, k as RecordUserOptions, av as RelationshipInfo, _ as ResolvedEffectApprovalRequired, Y as ResolvedEffectDryRun, X as ResolvedEffectPostCondition, Z as ResolvedEffectReverse, n as Sandbox, p as SandboxListResponse, Q as SemanticVersionDiff, O as SemanticVersionDiffEntry, e as Session, ai as SessionHeapFieldType, aj as SessionHeapFieldValue, ak as SessionHeapVariable, b3 as StreamEvent, b5 as StreamStats, b4 as StreamSubscription, l as Subject, aq as SyncMessage, h as ToolHandler, a4 as ToolInfo, as as ToolInvokeParams, at as ToolResultParams, f as ToolSchema, a6 as ToolsChangedEvent, U as User, L as Version, w as VersionTag, V as VersionTracking, W as WSClient, an as WSClientOptions, al as WSDisconnectInfo, am as WSReconnectErrorInfo } from './client-DLGC0mJk.js';
 export { BuildGranularAgentSystemPromptInput, GeneratedJobCodeIssue, GranularAgentExecutionCheckpoint, GranularAgentHeapSummaryOptions, GranularAgentSessionContext, GranularAgentToolInfo, GranularAgentWorkflowFocus, HarnessContinuationDecision, HarnessControllerBudgets, HarnessProjectionOptions, HarnessPromptLike, HarnessVerifierSnapshot, HarnessVerifierSnapshotInput, buildContinuationInstruction, buildGranularAgentCheckpointBlock, buildGranularAgentDomainBlock, buildGranularAgentHeapBlock, buildGranularAgentLoopBlock, buildGranularAgentSessionBlock, buildGranularAgentSystemPrompt, buildGranularAgentToolBlock, buildGranularAgentWorkflowBlock, createHarnessVerifierSnapshot, evaluateContinuation, getCurrentClosureId, getExclusivePromptTarget, hasOpenPrompt, projectHeapSummary, projectLoopSummary, projectWorkflowFocus, projectWorkflowSummary, reviewGeneratedJobCode } from './agent-harness.js';
 import '@automerge/automerge';
 import '@automerge/automerge/slim';
 
+declare function isLocalApiUrl(url: string): boolean;
+/**
+ * Local dev + `sk_*` (WorkOS org key in env): map to the local gn_sk e2e key by default so every
+ * request (HTTP + WebSocket) uses the same tenant as the v2 UI on localhost (`default`). Without
+ * this, the SDK passes `sk_*` through → gateway resolves org_… while the UI still uses gn_sk →
+ * you only see old default-tenant sandboxes and new ingest data looks “missing”.
+ *
+ * - `GRANULAR_LOCAL_API_KEY` — explicit key to use instead (e.g. another gn_sk).
+ * - `GRANULAR_DISABLE_LOCAL_API_KEY_FALLBACK=1` — do not swap; send the real `sk_*` (org tenant +
+ *   WorkOS validation on the gateway). Use when the UI is also on that org (e.g. session auth +
+ *   NEXT_PUBLIC_DISABLE_LOCAL_API_KEY_FALLBACK on the app).
+ */
+declare function resolveAuthTokenForApiUrl(authToken: string, apiUrl: string): string;
+declare function resolveApiUrl(explicitApiUrl?: string, mode?: EndpointMode): string;
+
 type EffectRuntimeRequest = {
     effectKey: string;
     effectName: string;
@@ -41,4 +56,4 @@ declare function normalizePromptType(raw: Record<string, unknown> | null | undef
 declare function normalizePrompt(rawValue: unknown): Prompt | null;
 declare function resolvePromptAnswer(prompt: Prompt | undefined, answer: unknown): unknown;
 
-export { EffectHandlerContext, type JobPresentation, ManifestEffectMetamodelSpec, Prompt, ResolvedEffectBehaviors, SessionHeapEntry, SessionHeapList, SessionHeapSnapshot, ToolWithHandler, extractPromptTokens, invokeRegisteredEffect, normalizeEffectBehaviors, normalizePrompt, normalizePromptText, normalizePromptType, resolveJobPresentation, resolvePromptAnswer, scorePromptChoiceMatch };
+export { EffectHandlerContext, EndpointMode, type JobPresentation, ManifestEffectMetamodelSpec, Prompt, ResolvedEffectBehaviors, SessionHeapEntry, SessionHeapList, SessionHeapSnapshot, ToolWithHandler, extractPromptTokens, invokeRegisteredEffect, isLocalApiUrl, normalizeEffectBehaviors, normalizePrompt, normalizePromptText, normalizePromptType, resolveApiUrl, resolveAuthTokenForApiUrl, resolveJobPresentation, resolvePromptAnswer, scorePromptChoiceMatch };

package/dist/index.js

@@ -4682,10 +4682,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
@@ -11243,9 +11248,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 = {
@@ -11255,6 +11260,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));
@@ -11269,6 +11276,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);
@@ -13292,23 +13310,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}`);
   }
 };
 
@@ -14234,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)\`.
@@ -14246,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.
@@ -14502,6 +14536,7 @@ exports.getCurrentClosureId = getCurrentClosureId;
 exports.getExclusivePromptTarget = getExclusivePromptTarget;
 exports.hasOpenPrompt = hasOpenPrompt;
 exports.invokeRegisteredEffect = invokeRegisteredEffect;
+exports.isLocalApiUrl = isLocalApiUrl;
 exports.normalizeEffectBehaviors = normalizeEffectBehaviors;
 exports.normalizePrompt = normalizePrompt;
 exports.normalizePromptText = normalizePromptText;
@@ -14510,6 +14545,8 @@ exports.projectHeapSummary = projectHeapSummary;
 exports.projectLoopSummary = projectLoopSummary;
 exports.projectWorkflowFocus = projectWorkflowFocus;
 exports.projectWorkflowSummary = projectWorkflowSummary;
+exports.resolveApiUrl = resolveApiUrl;
+exports.resolveAuthTokenForApiUrl = resolveAuthTokenForApiUrl;
 exports.resolveJobPresentation = resolveJobPresentation;
 exports.resolvePromptAnswer = resolvePromptAnswer;
 exports.reviewGeneratedJobCode = reviewGeneratedJobCode;