@granular-software/sdk 0.4.34 → 0.4.36

package/dist/index.mjs

@@ -12350,6 +12350,38 @@ function normalizeUser(user) {
     permissions: Array.isArray(user.permissions) ? user.permissions : []
   };
 }
+function normalizeEnvironmentSetupSummary(setup) {
+  if (!setup) {
+    return null;
+  }
+  const queuedRecords = Number(setup.queuedRecords || 0);
+  const processingRecords = Number(setup.processingRecords || 0);
+  return {
+    ...setup,
+    setupRunId: String(setup.setupRunId || ""),
+    environmentId: String(setup.environmentId || ""),
+    sandboxId: String(setup.sandboxId || ""),
+    subjectId: String(setup.subjectId || ""),
+    triggerReason: setup.triggerReason === "fresh_after_version_update" ? "fresh_after_version_update" : "new_environment",
+    lifecycleStatus: setup.lifecycleStatus === "completed" || setup.lifecycleStatus === "failed" ? setup.lifecycleStatus : "running",
+    stage: typeof setup.stage === "string" ? setup.stage : null,
+    totalObjectsToImport: Number(setup.totalObjectsToImport || 0),
+    totalImports: Number(setup.totalImports || 0),
+    activeImports: Number(setup.activeImports || 0),
+    totalRecords: Number(setup.totalRecords || 0),
+    queuedRecords,
+    processingRecords,
+    completedRecords: Number(setup.completedRecords || 0),
+    failedRecords: Number(setup.failedRecords || 0),
+    canceledRecords: Number(setup.canceledRecords || 0),
+    awaitingRecords: Number(setup.awaitingRecords || 0) || queuedRecords + processingRecords,
+    errorMessage: typeof setup.errorMessage === "string" ? setup.errorMessage : null,
+    startedAt: Number(setup.startedAt || Date.now()),
+    hookCompletedAt: setup.hookCompletedAt == null ? null : Number(setup.hookCompletedAt),
+    finishedAt: setup.finishedAt == null ? null : Number(setup.finishedAt),
+    updatedAt: Number(setup.updatedAt || Date.now())
+  };
+}
 function normalizeEnvironmentData(environment) {
   const buildPolicy = environment.buildPolicy || environment.tracking || (environment.tagId ? { mode: "tag", tagId: environment.tagId } : {
     mode: "pinned",
@@ -12363,7 +12395,8 @@ function normalizeEnvironmentData(environment) {
     envName: environmentName,
     environment: environmentName,
     buildPolicy,
-    tracking: environment.tracking || buildPolicy
+    tracking: environment.tracking || buildPolicy,
+    setup: normalizeEnvironmentSetupSummary(environment.setup)
   };
 }
 var Environment = class {
@@ -12421,6 +12454,10 @@ var Environment = class {
   get updateState() {
     return this.envData.updateState;
   }
+  /** The latest setup/import run summary for this environment, when available. */
+  get setup() {
+    return this.envData.setup || null;
+  }
   /** Convenience flag for whether this environment trails the current tag target */
   get isOutdated() {
     return this.envData.updateState === "update_available";
@@ -12441,6 +12478,9 @@ var Environment = class {
   get runtimeBaseUrl() {
     return this.getRuntimeBaseUrl();
   }
+  syncEnvironmentData(envData) {
+    this.envData = normalizeEnvironmentData(envData);
+  }
   get sessions() {
     return {
       list: async (options) => this.listSessions(options?.status || "active"),
@@ -13386,7 +13426,8 @@ var Environment = class {
         method: "POST",
         body: JSON.stringify({
           records,
-          batchSize: options.batchSize
+          batchSize: options.batchSize,
+          setupRunId: options.setupRunId
         })
       }
     );
@@ -13534,18 +13575,12 @@ var EnvironmentSession = class extends Session {
   }
   get messages() {
     return {
-      list: (options = {}) => this.sessionDataRequest(
-        "/messages",
-        options
-      )
+      list: (options = {}) => this.sessionDataRequest("/messages", options)
     };
   }
   get timeline() {
     return {
-      list: (options = {}) => this.sessionDataRequest(
-        "/timeline",
-        options
-      )
+      list: (options = {}) => this.sessionDataRequest("/timeline", options)
     };
   }
   get jobs() {
@@ -13562,10 +13597,7 @@ var EnvironmentSession = class extends Session {
   get heap() {
     return {
       entries: {
-        list: (options = {}) => this.sessionDataRequest(
-          "/heap/entries",
-          options
-        ),
+        list: (options = {}) => this.sessionDataRequest("/heap/entries", options),
         get: (path) => this.sessionDataRequest(
           `/heap/entries/${encodeURIComponent(path)}`
         )
@@ -13609,10 +13641,7 @@ var EnvironmentSession = class extends Session {
         const heap = normalizeHeapSnapshot({
           entriesByPath: Object.fromEntries(
             entries.map((entry) => {
-              return entry?.path ? [
-                entry.path,
-                entry
-              ] : null;
+              return entry?.path ? [entry.path, entry] : null;
             }).filter(
               (entry) => Boolean(entry)
             )
@@ -13778,6 +13807,15 @@ var OntologyHandle = class {
       disconnect: async () => this.granular.disconnectEffects(this.ontologyNameOrId)
     };
   }
+  get importer() {
+    return {
+      onEnvironmentCreate: (handler) => this.granular.registerEnvironmentImporter(
+        this.ontologyNameOrId,
+        handler
+      ),
+      clear: () => this.granular.clearEnvironmentImporter(this.ontologyNameOrId)
+    };
+  }
 };
 var Granular = class _Granular {
   apiKey;
@@ -13794,6 +13832,10 @@ var Granular = class _Granular {
   sandboxEffectHosts = /* @__PURE__ */ new Map();
   /** In-flight host connection promises to avoid duplicate concurrent connects */
   sandboxEffectHostPromises = /* @__PURE__ */ new Map();
+  /** Ontology-bound environment importer hooks keyed by the caller's ontology identifier. */
+  ontologyImporters = /* @__PURE__ */ new Map();
+  /** Resolved importer hooks keyed by sandboxId for fast lookups during openEnvironment(). */
+  sandboxImporters = /* @__PURE__ */ new Map();
   /**
    * Create a new Granular client
    * @param options - Client configuration
@@ -13819,6 +13861,32 @@ var Granular = class _Granular {
   ontology(ontologyNameOrId) {
     return new OntologyHandle(this, ontologyNameOrId);
   }
+  registerEnvironmentImporter(ontologyNameOrId, handler) {
+    this.ontologyImporters.set(ontologyNameOrId, handler);
+    if (ontologyNameOrId.startsWith("sbx_")) {
+      this.sandboxImporters.set(ontologyNameOrId, {
+        handler,
+        sourceOntology: ontologyNameOrId
+      });
+      return;
+    }
+    for (const [sandboxId, importer] of this.sandboxImporters.entries()) {
+      if (importer.sourceOntology === ontologyNameOrId) {
+        this.sandboxImporters.set(sandboxId, {
+          handler,
+          sourceOntology: ontologyNameOrId
+        });
+      }
+    }
+  }
+  clearEnvironmentImporter(ontologyNameOrId) {
+    this.ontologyImporters.delete(ontologyNameOrId);
+    for (const [sandboxId, importer] of this.sandboxImporters.entries()) {
+      if (importer.sourceOntology === ontologyNameOrId) {
+        this.sandboxImporters.delete(sandboxId);
+      }
+    }
+  }
   /**
    * Records/upserts a user and prepares them for sandbox connections
    *
@@ -13935,11 +14003,13 @@ var Granular = class _Granular {
    * ```
    */
   async openEnvironment(options) {
-    const envData = await this.resolveOpenEnvironmentData(
+    const resolved = await this.resolveOpenEnvironmentData(
       options,
       "openEnvironment"
     );
-    return this.bindEnvironmentHandle(envData);
+    const environment = this.bindEnvironmentHandle(resolved.environment);
+    await this.maybeRunEnvironmentImporter(resolved, environment);
+    return environment;
   }
   /**
    * Deprecated compatibility alias for `openEnvironment()`.
@@ -14026,7 +14096,12 @@ var Granular = class _Granular {
       )
     );
     if (currentMatches.length > 0) {
-      return currentMatches[0];
+      return {
+        environment: currentMatches[0],
+        requestedOntology: ontology,
+        sandboxId: sandbox.sandboxId,
+        subjectId: user.granularId
+      };
     }
     const outdatedMatches = this.sortEnvironmentsByRecency(
       userEnvironments.filter(
@@ -14034,14 +14109,25 @@ var Granular = class _Granular {
       )
     );
     if (outdatedMatches.length > 0 && options.createFreshIfOutdated !== true) {
-      return outdatedMatches[0];
+      return {
+        environment: outdatedMatches[0],
+        requestedOntology: ontology,
+        sandboxId: sandbox.sandboxId,
+        subjectId: user.granularId
+      };
     }
-    return this.environments.create(sandbox.sandboxId, {
+    return {
+      environment: await this.environments.create(sandbox.sandboxId, {
+        subjectId: user.granularId,
+        environment: this.buildManagedEnvironmentName(tagName, targetVersionId),
+        tagId: tag.tagId,
+        permissionProfileId: null
+      }),
+      requestedOntology: ontology,
+      sandboxId: sandbox.sandboxId,
       subjectId: user.granularId,
-      environment: this.buildManagedEnvironmentName(tagName, targetVersionId),
-      tagId: tag.tagId,
-      permissionProfileId: null
-    });
+      setupTriggerReason: outdatedMatches.length > 0 ? "fresh_after_version_update" : "new_environment"
+    };
   }
   /**
    * List active (open) sessions for an environment — each session is one agent conversation thread.
@@ -14158,6 +14244,94 @@ var Granular = class _Granular {
     });
     return this.connectSession({ sessionId, clientId: options?.clientId });
   }
+  resolveEnvironmentImporter(requestedOntology, sandboxId) {
+    const sandboxImporter = this.sandboxImporters.get(sandboxId);
+    if (sandboxImporter) {
+      const sourceImporter = this.ontologyImporters.get(
+        sandboxImporter.sourceOntology
+      );
+      if (sourceImporter === sandboxImporter.handler) {
+        return sandboxImporter.handler;
+      }
+      this.sandboxImporters.delete(sandboxId);
+    }
+    const ontologyImporter = this.ontologyImporters.get(requestedOntology);
+    if (!ontologyImporter) {
+      return void 0;
+    }
+    this.sandboxImporters.set(sandboxId, {
+      handler: ontologyImporter,
+      sourceOntology: requestedOntology
+    });
+    return ontologyImporter;
+  }
+  async maybeRunEnvironmentImporter(resolved, environment) {
+    if (!resolved.setupTriggerReason) {
+      return;
+    }
+    const importer = this.resolveEnvironmentImporter(
+      resolved.requestedOntology,
+      resolved.sandboxId
+    );
+    if (!importer) {
+      return;
+    }
+    const setupRun = await this.request(
+      `/control/environments/${environment.environmentId}/setup-runs`,
+      {
+        method: "POST",
+        body: JSON.stringify({
+          triggerReason: resolved.setupTriggerReason
+        })
+      }
+    );
+    const setupRunId = setupRun.setupRunId;
+    const updateSetupRun = async (patch) => {
+      await this.request(
+        `/control/environment-setup-runs/${setupRunId}`,
+        {
+          method: "PATCH",
+          body: JSON.stringify(patch)
+        }
+      );
+    };
+    const importerContext = {
+      environmentId: environment.environmentId,
+      sandboxId: environment.sandboxId,
+      subjectId: environment.subjectId,
+      reason: resolved.setupTriggerReason,
+      incrementTotalObjectsToImportCount: async (n) => {
+        const safeIncrement = Math.max(0, Math.trunc(n));
+        if (safeIncrement <= 0) {
+          return;
+        }
+        await updateSetupRun({
+          incrementTotalObjectsToImportCount: safeIncrement
+        });
+      },
+      setStage: async (stage) => {
+        await updateSetupRun({ stage });
+      },
+      importRecords: async (records, options) => environment.enqueueRecordImport(records, {
+        batchSize: options?.batchSize,
+        setupRunId
+      })
+    };
+    try {
+      await importer(importerContext);
+      await updateSetupRun({ markHookCompleted: true });
+      const refreshedEnvironment = await this.environments.get(
+        environment.environmentId
+      );
+      environment.syncEnvironmentData(refreshedEnvironment);
+    } catch (error) {
+      await updateSetupRun({
+        status: "failed",
+        errorMessage: error instanceof Error ? error.message : String(error)
+      }).catch(() => void 0);
+      throw error;
+    }
+  }
   bindEnvironmentHandle(envData) {
     const graphqlEndpoint = `${this.httpUrl}/orchestrator/graphql`;
     return new Environment(this, envData, this.apiKey, graphqlEndpoint);
@@ -15799,12 +15973,11 @@ function buildContinuationInstruction(resultPreview) {
     "Continue the same user request using the latest structured session state.",
     "Take only the minimum next step that directly helps the user.",
     "Use the active tasks, decisions, prompts, and heap references as the source of truth instead of replaying old work.",
-    "If the user names a concrete record that is not already in the heap, fetch it from the graph instead of replying that it is not in context.",
+    "If the user names a concrete record that is not already in the heap, resolve it from the graph before saying it is missing: try a broad search, then a small set of normalized/fuzzy variants or a paged scan when the domain supports it.",
+    "If the request needs all matching records, use iterate(...) or page until hasMore is false. A single list(...) or page(...) call is only one page.",
     "If this request clearly spans multiple steps and there are no active tasks yet, create 2-4 short user-visible tasks now.",
     "Reuse any existing taskId and decisionId values exactly as they appear in AGENT LOOP STATE.",
-    "Use ask_user with type input for open-ended preferences or missing text. Use type choice only for a short explicit shortlist.",
-    "Do not ask for confirmation in plain text. Use loop.confirm(...) when approval is needed.",
-    "Await loop.ask_user(...) and loop.confirm(...). Those helpers pause the current job and resume it after the user answers.",
+    "When progress depends on the user's choice, missing detail, or approval, use loop.ask_user(...) or loop.confirm(...) so the job pauses and resumes through the live workflow.",
     "After a resumed ask_user or confirm call, continue the same job and perform the newly authorized action when the answer is sufficient. Do not stop with placeholder text like 'I'm ready to do it next.'",
     "If you ask the user a new question in this job, do not also close the loop in the same job.",
     "Write the smallest straightforward code for the current step. Avoid defensive fallback branches for hypothetical states that are not currently true.",
@@ -15992,12 +16165,13 @@ ${loopBlock}
 - Continue from the latest structured state. Treat WORKFLOW SNAPSHOT, EXECUTION CHECKPOINT, RECENT REFERENTS, SESSION HEAP, and AGENT LOOP STATE as the working memory for this request.
 - Use CAPABILITY SNAPSHOT to choose the next step, then use DOMAIN REFERENCE for exact signatures and query shapes.
 - Take the minimum next step that directly helps the user. Avoid duplicate work, speculative cleanup, or extra fetching that is not needed yet.
-- If the user names a record that is not already in the heap, fetch it from the graph instead of saying it is not in context.
-- Treat user-provided names as human references, not exact keys. If one strong partial match exists, use it. If several plausible matches exist, ask the user to choose.
 - Use RECENT REFERENTS to resolve follow-up references across turns, such as "that invoice", "that customer", "those products", or "the other one".
+- Treat user-provided names, numbers, and labels as human references, not exact keys. Resolve them with code: check recent referents/heap first, then query the graph with the broadest supported \`search\` or \`filter\`, then retry with a few normalized/fuzzy/prefix variants when the first pass is empty or ambiguous. Only say a record does not exist after a reasonable lookup across the relevant class.
+- If one strong match exists, use it. If several plausible matches remain, use \`loop.ask_user({ type: 'choice', ... })\` with the grounded candidates instead of guessing.
 - If the request has more than one reasonable interpretation, ask the user to clarify instead of guessing.
 - For comparisons, rankings, selections, or summaries, first identify the rule you are using. If that rule is not clear from the user request and DOMAIN REFERENCE, ask the user before choosing anything.
 - When the ranking, comparison, or selection rule is unclear, the minimum next step is the clarification itself. Do not run a placeholder query for a provisional winner before asking.
+- If a user request matches both a domain type/effect and a loop helper, prioritize the domain type/effect. For example, if DOMAIN REFERENCE contains a \`Task\` class and the user asks to create a task, create the domain task record; do not call \`loop.create_task(...)\` unless you are only tracking your own workflow.
 - Reuse exact \`taskId\`, \`decisionId\`, and \`closureId\` values from AGENT LOOP STATE. Never invent or rewrite them.
 - If the request is ambiguous or clearly multi-step, create 2-4 short user-visible tasks and keep them updated as the workflow advances.
 - Use \`loop.ask_user({ type: 'choice', options: [...] })\` when you have a short, grounded shortlist the user can choose from. Otherwise use \`type: 'input'\`.
@@ -16008,6 +16182,14 @@ ${loopBlock}
 - Use \`loop.open_decision(...)\` to persist grounded candidates, \`loop.close_decision(...)\` to resolve one, and \`loop.close_loop(...)\` when the workflow is completed, canceled, or blocked.
 - If you ask a new question in the current job, do not also close the loop in that same job.
 
+\u2500\u2500\u2500 LOOP HELPER REFERENCE \u2500\u2500\u2500
+- \`loop.ask_user(...)\`: pause the current job for missing input; use \`type: 'choice'\` only for a short grounded shortlist.
+- \`loop.confirm(...)\`: pause for yes/no approval before a consequential action, then branch on the returned boolean.
+- \`loop.open_decision(...)\`: save explicit candidates that later jobs can revisit; each candidate needs an \`id\`.
+- \`loop.close_decision(...)\`: resolve an open decision with a stored \`selectedId\` and optional rationale.
+- \`loop.create_task(...)\`, \`loop.update_task(...)\`, \`loop.complete_task(...)\`: keep a short resumable task list for the agent's workflow; these are not domain \`Task\` records.
+- \`loop.close_loop(...)\`: record the workflow outcome when it is completed, canceled, or blocked.
+
 \u2500\u2500\u2500 CODE RULES \u2500\u2500\u2500
 - Import from \`./sandbox-tools\`.
 - If you use \`heap\`, \`loop\`, \`agent_text_message\`, or \`agent_heap_objects\`, import them explicitly from \`./sandbox-tools\`.
@@ -16017,6 +16199,7 @@ ${loopBlock}
 - Use \`ClassName.get({ path })\` only for known graph paths when you want a direct graph fetch.
 - Use \`ClassName.count()\` for totals, \`ClassName.page({ page, perPage, saveAs })\` when you need \`items\` plus \`totalCount\` or \`hasMore\`, \`ClassName.list({ page, perPage, saveAs })\` for one page of records, and \`ClassName.iterate({ perPage, maxItems })\` for large scans.
 - \`perPage\` defaults to \`100\` and is capped at \`100\`.
+- A single \`list(...)\` or \`page(...)\` call never proves there are no more records. For "all", "every", exports, broad scans, or exhaustive searches, use \`iterate(...)\` when available or loop \`page(...)\` until \`hasMore\` is false.
 - Push \`filter\`, \`search\`, and \`sort\` into graph queries instead of fetching a page and processing it locally.
 - A property appearing on a record does not make it valid in \`filter\` or \`sort\`; only use fields and operators that are explicitly exposed in DOMAIN REFERENCE.
 - Choose \`sort.field\` verbatim from the sortable fields listed in DOMAIN REFERENCE. Do not sort by relationship names, related-record collections, counts, totals, or other derived metrics unless they are explicitly listed as sortable.