@granular-software/sdk 0.4.19 → 0.4.21

package/dist/cli/index.js

@@ -8941,7 +8941,7 @@ function manifestGuideEndToEndSection() {
 | 2 | \`granular build\` | Manifest **uploaded**; ontology version created or reused; build run compiles it; errors surface here |
 | 3 | (Optional) Run your **effects host** \u2014 e.g. \`npx tsx granular-effects.ts\` \u2014 calling \`registerEffects(sandboxId, \u2026)\` | Effect **handlers** attached in **your** process |
 | 4 | \`new Granular({ apiKey })\` then \`connect({ ontology, environment, userId, permissions })\` | **\`Environment\`** for that ontology environment slot |
-| 5 | \`recordObject\` / \`recordObjects\` | **Records** stored with correct fields and relationship keys |
+| 5 | \`recordObject\` / \`recordObjects\` | **Records** stored with correct fields and relationship keys. \`recordObjects\` chunks to the control plane (default 100 rows/request); pass \`onChunkComplete\` / \`concurrency\` for UI progress. For async bulk loads use \`enqueueRecordImport\` + import status APIs. |
 | 6 | \`submitJob(\`\u2026\`)\` with imports from \`./sandbox-tools\` | **Jobs** run; may call **effects** \u2192 your handlers execute and return results |
 
 **Accuracy tip:** After changing the manifest, always **re-build** before assuming generated types, \`./sandbox-tools\` names, or effect signatures match the file on disk.`;
@@ -14961,8 +14961,8 @@ ${effectMetamodelTable}
 |-----|---------|
 | \`environmentId\`, \`sandboxId\`, \`apiEndpoint\`, \u2026 | Session context. |
 | \`applyManifest(manifest)\` | Apply manifest operations at runtime (alternative to CLI build for dynamic ontologies). |
-| \`recordObject\` / \`recordObjects\` | Upsert instances and relationships. |
-| \`enqueueRecordImport\`, \`listRecordImports\`, \`getRecordImportSummary\`, \u2026 | Background bulk import. |
+| \`recordObject\` / \`recordObjects\` | Upsert instances and relationships. \`recordObjects\` uses chunked HTTP batch writes (default 100 rows/chunk); optional \`onChunkComplete\`, \`batchSize\`, \`concurrency\`. |
+| \`enqueueRecordImport\`, \`listRecordImports\`, \`getRecordImportSummary\`, \u2026 | **Async** bulk import (worker queue + aggregate progress). Prefer when loads are huge and fire-and-forget is OK. |
 | \`graphql(query, variables?)\` | **GraphQL** \u2014 see dedicated subsection below. |
 | \`defineRelationship\`, \`getRelationships\`, \`attach\`, \`detach\`, \`listRelated\` | Imperative relationship operations (same ideas as manifest \`defineRelationship\`). |
 | \`submitJob(code)\` | Run code in the sandbox; import from \`./sandbox-tools\`. |
@@ -15502,6 +15502,7 @@ edit granular.json -> granular build -> granular document -> run tests -> option
 
 - Default auth story: \`granular login\`. Manual \`.env.local\` editing is fallback guidance only.
 - Read \`GRANULAR_SANDBOX.md\` before writing \`recordObject\` payloads or relationship keys.
+- Large ingests: use \`recordObjects(rows, { onChunkComplete, concurrency })\` for synchronous chunked writes with progress, or \`enqueueRecordImport\` + \`getRecordImport\` for async queue-based bulk loads.
 - Build failures should be mapped to the exact class, relationship, or effect declaration that caused them.
 - If the user starts from the control plane UI, converge back to the same repo state and the same CLI commands.
         `
@@ -17989,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
@@ -18859,14 +18865,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((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);
+}
 function computeEffectKey2(effect) {
   const attachedClass = effect.className?.trim();
   if (!attachedClass) {
@@ -19824,24 +19865,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 info2 = {
+              chunkIndex: plan.chunkIndex,
+              totalChunks: plan.chunkCount,
+              offset: plan.offset,
+              recordCount: plan.slice.length,
+              durationMs,
+              results: items
+            };
+            await onChunk(info2);
+          }
+        })
+      );
+    }
+    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 (error2) {
+        lastError = error2;
+        if (!isRetryableRecordObjectsError(error2) || attempt === DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_COUNT) {
+          throw error2;
+        }
+        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(
@@ -20809,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-BQw_gUK3.d.mts → client-DLGC0mJk.d.mts}

@@ -862,6 +862,43 @@ interface RecordObjectResult {
     /** Whether the instance was newly created (false = updated) */
     created: boolean;
 }
+/**
+ * Metadata for one completed HTTP chunk in `recordObjects()`.
+ * Chunk indices follow input order; when concurrency is greater than 1, completion order may differ.
+ */
+interface RecordObjectsChunkInfo {
+    /** Zero-based chunk index */
+    chunkIndex: number;
+    totalChunks: number;
+    /** Zero-based offset into the original `records` array */
+    offset: number;
+    /** Number of records in this chunk */
+    recordCount: number;
+    /** Wall time for this chunk’s POST (including retries) */
+    durationMs: number;
+    /** Acknowledgements for this chunk, in the same order as the slice sent */
+    results: RecordObjectResult[];
+}
+/**
+ * Optional tuning for `recordObjects()` — batching, parallelism, and progress hooks.
+ */
+interface RecordObjectsOptions {
+    /**
+     * Max records per HTTP POST to the control-plane batch endpoint. Default 100.
+     * Smaller values: more round trips and finer `onChunkComplete` updates.
+     * Larger values: fewer requests (watch request size/timeouts).
+     */
+    batchSize?: number;
+    /**
+     * How many chunk POSTs may run concurrently. Default 1 (strictly sequential).
+     * Values above 1 can reduce wall time when the server can overlap work; capped at 16.
+     */
+    concurrency?: number;
+    /**
+     * Called after each chunk succeeds (after retries). Useful for UI progress bars.
+     */
+    onChunkComplete?: (info: RecordObjectsChunkInfo) => void | Promise<void>;
+}
 type RecordImportStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'canceled';
 type RecordImportItemStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'canceled';
 interface RecordImportStats {
@@ -1277,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
@@ -1682,12 +1724,31 @@ declare class Environment 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.
      */
-    recordObjects(records: RecordObjectOptions[]): Promise<RecordObjectResult[]>;
+    recordObjects(records: RecordObjectOptions[], options?: RecordObjectsOptions): Promise<RecordObjectResult[]>;
+    private executeRecordObjectsChunk;
     /**
-     * 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`**.
      */
     enqueueRecordImport(records: RecordObjectOptions[], options?: {
         batchSize?: number;
@@ -1992,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 APIError 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 RecordImportItemStatus as aA, type RecordImportStats as aB, type RecordImportItem as aC, type RecordImport as aD, type EnvironmentRecordImportSummary as aE, type ManifestPropertySpec as aF, type ManifestValidationOperator as aG, type ManifestEnumRuleSpec as aH, type ManifestFilterBySpec as aI, type ManifestValidationRuleSpec as aJ, type ManifestStateMachineStateSpec as aK, type ManifestStateMachineTransitionSpec as aL, type ManifestStateMachineSpec as aM, type ManifestPostConditionSpec as aN, type ManifestDryRunSpec as aO, type ManifestReverseSpec as aP, type ManifestApprovalRequiredSpec as aQ, type ManifestRelationshipDef as aR, type ManifestEffectSchema as aS, type ManifestEffectDeclaration as aT, type ManifestEventTypeDef as aU, type ManifestEventStreamDef as aV, type ManifestOperation as aW, type ManifestImport as aX, type ManifestVolume as aY, type ManifestContent as aZ, type GraphQLResult 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 RecordImportStatus as az, type SessionHeapSnapshot as b, type DeleteResponse as b0, type StreamEvent as b1, type StreamSubscription as b2, type StreamStats as b3, 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-BQw_gUK3.d.ts → client-DLGC0mJk.d.ts}

@@ -862,6 +862,43 @@ interface RecordObjectResult {
     /** Whether the instance was newly created (false = updated) */
     created: boolean;
 }
+/**
+ * Metadata for one completed HTTP chunk in `recordObjects()`.
+ * Chunk indices follow input order; when concurrency is greater than 1, completion order may differ.
+ */
+interface RecordObjectsChunkInfo {
+    /** Zero-based chunk index */
+    chunkIndex: number;
+    totalChunks: number;
+    /** Zero-based offset into the original `records` array */
+    offset: number;
+    /** Number of records in this chunk */
+    recordCount: number;
+    /** Wall time for this chunk’s POST (including retries) */
+    durationMs: number;
+    /** Acknowledgements for this chunk, in the same order as the slice sent */
+    results: RecordObjectResult[];
+}
+/**
+ * Optional tuning for `recordObjects()` — batching, parallelism, and progress hooks.
+ */
+interface RecordObjectsOptions {
+    /**
+     * Max records per HTTP POST to the control-plane batch endpoint. Default 100.
+     * Smaller values: more round trips and finer `onChunkComplete` updates.
+     * Larger values: fewer requests (watch request size/timeouts).
+     */
+    batchSize?: number;
+    /**
+     * How many chunk POSTs may run concurrently. Default 1 (strictly sequential).
+     * Values above 1 can reduce wall time when the server can overlap work; capped at 16.
+     */
+    concurrency?: number;
+    /**
+     * Called after each chunk succeeds (after retries). Useful for UI progress bars.
+     */
+    onChunkComplete?: (info: RecordObjectsChunkInfo) => void | Promise<void>;
+}
 type RecordImportStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'canceled';
 type RecordImportItemStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'canceled';
 interface RecordImportStats {
@@ -1277,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
@@ -1682,12 +1724,31 @@ declare class Environment 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.
      */
-    recordObjects(records: RecordObjectOptions[]): Promise<RecordObjectResult[]>;
+    recordObjects(records: RecordObjectOptions[], options?: RecordObjectsOptions): Promise<RecordObjectResult[]>;
+    private executeRecordObjectsChunk;
     /**
-     * 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`**.
      */
     enqueueRecordImport(records: RecordObjectOptions[], options?: {
         batchSize?: number;
@@ -1992,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 APIError 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 RecordImportItemStatus as aA, type RecordImportStats as aB, type RecordImportItem as aC, type RecordImport as aD, type EnvironmentRecordImportSummary as aE, type ManifestPropertySpec as aF, type ManifestValidationOperator as aG, type ManifestEnumRuleSpec as aH, type ManifestFilterBySpec as aI, type ManifestValidationRuleSpec as aJ, type ManifestStateMachineStateSpec as aK, type ManifestStateMachineTransitionSpec as aL, type ManifestStateMachineSpec as aM, type ManifestPostConditionSpec as aN, type ManifestDryRunSpec as aO, type ManifestReverseSpec as aP, type ManifestApprovalRequiredSpec as aQ, type ManifestRelationshipDef as aR, type ManifestEffectSchema as aS, type ManifestEffectDeclaration as aT, type ManifestEventTypeDef as aU, type ManifestEventStreamDef as aV, type ManifestOperation as aW, type ManifestImport as aX, type ManifestVolume as aY, type ManifestContent as aZ, type GraphQLResult 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 RecordImportStatus as az, type SessionHeapSnapshot as b, type DeleteResponse as b0, type StreamEvent as b1, type StreamSubscription as b2, type StreamStats as b3, 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-BQw_gUK3.mjs';
-export { a$ 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, b0 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, aE as EnvironmentRecordImportSummary, G as Granular, j as GranularAuth, i as GranularOptions, a_ 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, aQ as ManifestApprovalRequiredSpec, aZ as ManifestContent, aO as ManifestDryRunSpec, aT as ManifestEffectDeclaration, aS as ManifestEffectSchema, aH as ManifestEnumRuleSpec, aV as ManifestEventStreamDef, aU as ManifestEventTypeDef, aI as ManifestFilterBySpec, aX as ManifestImport, H as ManifestListResponse, aW as ManifestOperation, aN as ManifestPostConditionSpec, aF as ManifestPropertySpec, aR as ManifestRelationshipDef, aP as ManifestReverseSpec, aM as ManifestStateMachineSpec, aK as ManifestStateMachineStateSpec, aL as ManifestStateMachineTransitionSpec, aG as ManifestValidationOperator, aJ as ManifestValidationRuleSpec, aY 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, aD as RecordImport, aC as RecordImportItem, aA as RecordImportItemStatus, aB as RecordImportStats, az as RecordImportStatus, ax as RecordObjectOptions, ay as RecordObjectResult, 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, b1 as StreamEvent, b3 as StreamStats, b2 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-BQw_gUK3.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-BQw_gUK3.js';
-export { a$ 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, b0 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, aE as EnvironmentRecordImportSummary, G as Granular, j as GranularAuth, i as GranularOptions, a_ 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, aQ as ManifestApprovalRequiredSpec, aZ as ManifestContent, aO as ManifestDryRunSpec, aT as ManifestEffectDeclaration, aS as ManifestEffectSchema, aH as ManifestEnumRuleSpec, aV as ManifestEventStreamDef, aU as ManifestEventTypeDef, aI as ManifestFilterBySpec, aX as ManifestImport, H as ManifestListResponse, aW as ManifestOperation, aN as ManifestPostConditionSpec, aF as ManifestPropertySpec, aR as ManifestRelationshipDef, aP as ManifestReverseSpec, aM as ManifestStateMachineSpec, aK as ManifestStateMachineStateSpec, aL as ManifestStateMachineTransitionSpec, aG as ManifestValidationOperator, aJ as ManifestValidationRuleSpec, aY 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, aD as RecordImport, aC as RecordImportItem, aA as RecordImportItemStatus, aB as RecordImportStats, az as RecordImportStatus, ax as RecordObjectOptions, ay as RecordObjectResult, 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, b1 as StreamEvent, b3 as StreamStats, b2 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-BQw_gUK3.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 };