@granular-software/sdk 0.4.33 → 0.4.35

package/dist/cli/index.js

@@ -19956,6 +19956,50 @@ function computeEffectKey(effect) {
   }
   return effect.static ? `class:${attachedClass}:static:${effect.name}` : `class:${attachedClass}:instance:${effect.name}`;
 }
+function computeEffectVersionSelectorSpecificity(selector) {
+  if (!selector || selector.mode === "all") {
+    return 0;
+  }
+  if (selector.mode === "exact") {
+    return 2;
+  }
+  return 1;
+}
+function matchesEffectVersionSelector(selector, buildVersionNumber) {
+  if (!selector || selector.mode === "all") {
+    return true;
+  }
+  if (typeof buildVersionNumber !== "number" || !Number.isFinite(buildVersionNumber)) {
+    return false;
+  }
+  if (selector.mode === "exact") {
+    return buildVersionNumber === selector.versionNumber;
+  }
+  if (selector.mode === "before") {
+    return buildVersionNumber < selector.versionNumber;
+  }
+  return buildVersionNumber > selector.versionNumber;
+}
+function selectRegisteredEffect(effectMap, effectKey, buildVersionNumber) {
+  let bestEffect;
+  let bestSpecificity = Number.NEGATIVE_INFINITY;
+  for (const effect of effectMap.values()) {
+    if (computeEffectKey(effect) !== effectKey) {
+      continue;
+    }
+    if (!matchesEffectVersionSelector(effect.versionSelector, buildVersionNumber)) {
+      continue;
+    }
+    const specificity = computeEffectVersionSelectorSpecificity(
+      effect.versionSelector
+    );
+    if (!bestEffect || specificity > bestSpecificity) {
+      bestEffect = effect;
+      bestSpecificity = specificity;
+    }
+  }
+  return bestEffect;
+}
 function normalizeEffectBehaviors(value) {
   return normalizeEffectBehaviorSummary(
     value
@@ -19976,9 +20020,17 @@ function resolveReverseEffect(effectMap, currentEffect, request, behaviors) {
     return void 0;
   }
   if (reverseHandler.includes(":")) {
-    return effectMap.get(reverseHandler);
+    return selectRegisteredEffect(
+      effectMap,
+      reverseHandler,
+      request.context?.buildVersionNumber
+    );
   }
-  const directMatch = effectMap.get(reverseHandler);
+  const directMatch = selectRegisteredEffect(
+    effectMap,
+    reverseHandler,
+    request.context?.buildVersionNumber
+  );
   if (directMatch) {
     return directMatch;
   }
@@ -19993,7 +20045,11 @@ function resolveReverseEffect(effectMap, currentEffect, request, behaviors) {
     })
   ];
   for (const candidateKey of candidateKeys) {
-    const candidate = effectMap.get(candidateKey);
+    const candidate = selectRegisteredEffect(
+      effectMap,
+      candidateKey,
+      request.context?.buildVersionNumber
+    );
     if (candidate) {
       return candidate;
     }
@@ -20029,7 +20085,11 @@ function resolveHandlerForMode(effectMap, effect, request) {
   return { effect, mode, handler: effect.handler };
 }
 async function invokeRegisteredEffect(effectMap, request) {
-  const effect = effectMap.get(request.effectKey);
+  const effect = selectRegisteredEffect(
+    effectMap,
+    request.effectKey,
+    request.context?.buildVersionNumber
+  );
   if (!effect) {
     throw new Error(`Effect handler not found: ${request.effectKey}`);
   }
@@ -20150,6 +20210,17 @@ function computeEffectKey2(effect) {
   }
   return effect.static ? `class:${attachedClass}:static:${effect.name}` : `class:${attachedClass}:instance:${effect.name}`;
 }
+function computeEffectVersionSelectorKey(selector) {
+  if (!selector || selector.mode === "all") {
+    return "all";
+  }
+  return `${selector.mode}:${selector.versionNumber}`;
+}
+function computeEffectRegistrationKey(effect) {
+  return `${computeEffectKey2(effect)}@${computeEffectVersionSelectorKey(
+    effect.versionSelector
+  )}`;
+}
 function buildEffectHostUrl(apiUrl, sandboxId, effectClientId, clientId) {
   const url = new URL(apiUrl);
   if (url.pathname.endsWith("/granular/ws/connect")) {
@@ -20233,6 +20304,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",
@@ -20246,7 +20349,8 @@ function normalizeEnvironmentData(environment) {
     envName: environmentName,
     environment: environmentName,
     buildPolicy,
-    tracking: environment.tracking || buildPolicy
+    tracking: environment.tracking || buildPolicy,
+    setup: normalizeEnvironmentSetupSummary(environment.setup)
   };
 }
 var Environment = class {
@@ -20304,6 +20408,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";
@@ -20324,6 +20432,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"),
@@ -21269,7 +21380,8 @@ var Environment = class {
         method: "POST",
         body: JSON.stringify({
           records,
-          batchSize: options.batchSize
+          batchSize: options.batchSize,
+          setupRunId: options.setupRunId
         })
       }
     );
@@ -21417,18 +21529,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() {
@@ -21445,10 +21551,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: (path6) => this.sessionDataRequest(
           `/heap/entries/${encodeURIComponent(path6)}`
         )
@@ -21492,10 +21595,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)
             )
@@ -21661,6 +21761,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;
@@ -21671,12 +21780,16 @@ var Granular = class _Granular {
   onUnexpectedClose;
   onReconnectError;
   debugHttp = process.env.GRANULAR_DEBUG_HTTP === "1";
-  /** Sandbox-level effect registry: sandboxId → (effectKey → ToolWithHandler) */
+  /** Sandbox-level effect registry: sandboxId → (effectKey@selector → ToolWithHandler) */
   sandboxEffects = /* @__PURE__ */ new Map();
   /** Live sandbox-scoped effect hosts keyed by sandboxId */
   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
@@ -21702,6 +21815,18 @@ 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);
+    }
+  }
+  clearEnvironmentImporter(ontologyNameOrId) {
+    this.ontologyImporters.delete(ontologyNameOrId);
+    if (ontologyNameOrId.startsWith("sbx_")) {
+      this.sandboxImporters.delete(ontologyNameOrId);
+    }
+  }
   /**
    * Records/upserts a user and prepares them for sandbox connections
    *
@@ -21818,11 +21943,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()`.
@@ -21909,7 +22036,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(
@@ -21917,14 +22049,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: tag2.tagId,
+        permissionProfileId: null
+      }),
+      requestedOntology: ontology,
+      sandboxId: sandbox.sandboxId,
       subjectId: user.granularId,
-      environment: this.buildManagedEnvironmentName(tagName, targetVersionId),
-      tagId: tag2.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.
@@ -22041,6 +22184,80 @@ var Granular = class _Granular {
     });
     return this.connectSession({ sessionId, clientId: options?.clientId });
   }
+  resolveEnvironmentImporter(requestedOntology, sandboxId) {
+    const resolved = this.sandboxImporters.get(sandboxId) || this.ontologyImporters.get(requestedOntology);
+    if (resolved && !this.sandboxImporters.has(sandboxId) && this.ontologyImporters.get(requestedOntology) === resolved) {
+      this.sandboxImporters.set(sandboxId, resolved);
+    }
+    return resolved;
+  }
+  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 (error2) {
+      await updateSetupRun({
+        status: "failed",
+        errorMessage: error2 instanceof Error ? error2.message : String(error2)
+      }).catch(() => void 0);
+      throw error2;
+    }
+  }
   bindEnvironmentHandle(envData) {
     const graphqlEndpoint = `${this.httpUrl}/orchestrator/graphql`;
     return new Environment(this, envData, this.apiKey, graphqlEndpoint);
@@ -22090,7 +22307,8 @@ var Granular = class _Granular {
       provenance: effect.provenance || { source: "custom" },
       tags: effect.tags,
       className: effect.className,
-      static: effect.static
+      static: effect.static,
+      versionSelector: effect.versionSelector
     };
   }
   async publishSandboxEffectCatalog(host) {
@@ -22278,7 +22496,10 @@ var Granular = class _Granular {
   async registerEffect(sandboxNameOrId, effect) {
     const sandbox = await this.findOrCreateSandbox(sandboxNameOrId);
     const sandboxId = sandbox.sandboxId;
-    this.getSandboxEffectMap(sandboxId).set(computeEffectKey2(effect), effect);
+    this.getSandboxEffectMap(sandboxId).set(
+      computeEffectRegistrationKey(effect),
+      effect
+    );
     await this.syncSandboxEffectCatalog(sandboxId);
   }
   /**
@@ -22291,7 +22512,7 @@ var Granular = class _Granular {
     const sandboxId = sandbox.sandboxId;
     const map = this.getSandboxEffectMap(sandboxId);
     for (const effect of effects2) {
-      map.set(computeEffectKey2(effect), effect);
+      map.set(computeEffectRegistrationKey(effect), effect);
     }
     await this.syncSandboxEffectCatalog(sandboxId);
   }
@@ -22309,7 +22530,7 @@ var Granular = class _Granular {
       return;
     }
     const nextEntries = Array.from(currentMap.entries()).filter(
-      ([effectKey, effect]) => effectKey !== name && effect.name !== name
+      ([, effect]) => computeEffectKey2(effect) !== name && effect.name !== name
     );
     if (nextEntries.length === currentMap.size) {
       return;

package/dist/{client-DTvI5MUG.d.mts → client-Cq8onk2D.d.mts}

@@ -303,6 +303,7 @@ interface EnvironmentData {
     sandboxId: string;
     ontologyId?: string;
     buildId: string;
+    versionNumber?: number | null;
     versionId: string;
     subjectId: string;
     envName: string;
@@ -312,6 +313,7 @@ interface EnvironmentData {
     tag?: VersionTag | null;
     tracking?: BuildPolicy;
     buildPolicy: BuildPolicy;
+    setup?: EnvironmentSetupSummary | null;
     updateState?: "up_to_date" | "update_available" | "upgrading" | "failed";
     createdAt: number;
     updatedAt: number;
@@ -422,6 +424,8 @@ interface EffectHandlerContext {
     effectClientId: string;
     sandboxId: string;
     environmentId: string;
+    buildId?: string;
+    buildVersionNumber?: number;
     sessionId: string;
     tenantId?: string;
     principalId?: string;
@@ -534,6 +538,12 @@ interface ToolSchema {
      * passed as the first argument to the handler).
      */
     static?: boolean;
+    /**
+     * Optional build-version selector for this live effect binding.
+     *
+     * When omitted, the binding applies to all build versions for the sandbox.
+     */
+    versionSelector?: EffectVersionSelector;
     /** Declarative runtime behaviors attached to the effect. */
     metamodels?: ManifestEffectMetamodelSpec;
 }
@@ -566,6 +576,18 @@ interface PublishToolsResult {
     }>;
 }
 type PublishEffectsResult = PublishToolsResult;
+type EffectVersionSelector = {
+    mode: "all";
+} | {
+    mode: "exact";
+    versionNumber: number;
+} | {
+    mode: "before";
+    versionNumber: number;
+} | {
+    mode: "after";
+    versionNumber: number;
+};
 /**
  * Domain state response
  */
@@ -603,6 +625,8 @@ interface ToolInfo {
     className?: string;
     /** Whether this is a static method */
     static?: boolean;
+    /** Optional build-version selector associated with the live binding. */
+    versionSelector?: EffectVersionSelector;
     /** Declarative runtime behaviors attached to the effect. */
     metamodels?: ManifestEffectMetamodelSpec;
 }
@@ -1082,6 +1106,7 @@ interface RecordImport {
     environmentId: string;
     sandboxId: string;
     subjectId: string;
+    setupRunId?: string | null;
     status: RecordImportStatus;
     batchSize: number;
     errorMessage: string | null;
@@ -1098,6 +1123,37 @@ interface EnvironmentRecordImportSummary extends RecordImportStats {
     activeImports: number;
     updatedAt: number;
 }
+type EnvironmentSetupTriggerReason = "new_environment" | "fresh_after_version_update";
+type EnvironmentSetupLifecycleStatus = "running" | "completed" | "failed";
+interface EnvironmentSetupSummary extends RecordImportStats {
+    setupRunId: string;
+    environmentId: string;
+    sandboxId: string;
+    subjectId: string;
+    triggerReason: EnvironmentSetupTriggerReason;
+    lifecycleStatus: EnvironmentSetupLifecycleStatus;
+    stage: string | null;
+    totalObjectsToImport: number;
+    totalImports: number;
+    activeImports: number;
+    errorMessage: string | null;
+    startedAt: number;
+    hookCompletedAt: number | null;
+    finishedAt: number | null;
+    updatedAt: number;
+}
+interface EnvironmentImporterImportOptions {
+    batchSize?: number;
+}
+interface EnvironmentImporter {
+    environmentId: string;
+    sandboxId: string;
+    subjectId: string;
+    reason: EnvironmentSetupTriggerReason;
+    incrementTotalObjectsToImportCount: (n: number) => Promise<void>;
+    setStage: (stage: string | null) => Promise<void>;
+    importRecords: (records: RecordObjectOptions[], options?: EnvironmentImporterImportOptions) => Promise<RecordImport>;
+}
 /**
  * Property specification in a manifest operation
  */
@@ -1554,6 +1610,7 @@ declare class Session {
     private checkForToolChanges;
 }
 
+type EnvironmentImporterHandler = (importer: EnvironmentImporter) => Promise<void> | void;
 /**
  * Environment is the sessionless handle for one resolved ontology environment.
  *
@@ -1589,6 +1646,8 @@ declare class Environment {
     get buildPolicy(): BuildPolicy;
     /** The current update state relative to the followed tag */
     get updateState(): EnvironmentData["updateState"];
+    /** The latest setup/import run summary for this environment, when available. */
+    get setup(): EnvironmentSetupSummary | null;
     /** Convenience flag for whether this environment trails the current tag target */
     get isOutdated(): boolean;
     /** The followed tag name when this environment is tag-tracked */
@@ -1599,6 +1658,7 @@ declare class Environment {
     get authToken(): string;
     /** Base runtime URL derived from the GraphQL endpoint */
     get runtimeBaseUrl(): string;
+    syncEnvironmentData(envData: EnvironmentData): void;
     get sessions(): {
         list: (options?: {
             status?: "active" | "closed" | "all";
@@ -1903,6 +1963,7 @@ declare class Environment {
      */
     enqueueRecordImport(records: RecordObjectOptions[], options?: {
         batchSize?: number;
+        setupRunId?: string;
     }): Promise<RecordImport>;
     /**
      * List queued or completed record imports for this environment.
@@ -2058,6 +2119,10 @@ declare class OntologyHandle {
         clear: () => Promise<void>;
         disconnect: () => Promise<void>;
     };
+    get importer(): {
+        onEnvironmentCreate: (handler: EnvironmentImporterHandler) => void;
+        clear: () => void;
+    };
 }
 declare class Granular {
     private apiKey;
@@ -2068,12 +2133,16 @@ declare class Granular {
     private onUnexpectedClose?;
     private onReconnectError?;
     private debugHttp;
-    /** Sandbox-level effect registry: sandboxId → (effectKey → ToolWithHandler) */
+    /** Sandbox-level effect registry: sandboxId → (effectKey@selector → ToolWithHandler) */
     private sandboxEffects;
     /** Live sandbox-scoped effect hosts keyed by sandboxId */
     private sandboxEffectHosts;
     /** In-flight host connection promises to avoid duplicate concurrent connects */
     private sandboxEffectHostPromises;
+    /** Ontology-bound environment importer hooks keyed by the caller's ontology identifier. */
+    private ontologyImporters;
+    /** Resolved importer hooks keyed by sandboxId for fast lookups during openEnvironment(). */
+    private sandboxImporters;
     /**
      * Create a new Granular client
      * @param options - Client configuration
@@ -2083,6 +2152,8 @@ declare class Granular {
      * Return an ontology-scoped handle for effects and other ontology-level APIs.
      */
     ontology(ontologyNameOrId: string): OntologyHandle;
+    registerEnvironmentImporter(ontologyNameOrId: string, handler: EnvironmentImporterHandler): void;
+    clearEnvironmentImporter(ontologyNameOrId: string): void;
     /**
      * Records/upserts a user and prepares them for sandbox connections
      *
@@ -2181,6 +2252,8 @@ declare class Granular {
     reopenSession(sessionId: string, options?: {
         clientId?: string;
     }): Promise<EnvironmentSession>;
+    private resolveEnvironmentImporter;
+    private maybeRunEnvironmentImporter;
     private bindEnvironmentHandle;
     private bindWebSocketEnvironmentSession;
     private activateEnvironment;
@@ -2326,4 +2399,4 @@ declare class Granular {
     private request;
 }
 
-export { type SemanticVersionDiff as $, type AccessTokenProvider as A, type BuildPolicy as B, type ConnectOptions as C, type DomainState as D, type EndpointMode as E, type VersionTag as F, Granular as G, type EnvironmentData as H, type InstanceToolHandler as I, type CreateEnvironmentData as J, type EnvironmentListResponse as K, type Manifest as L, type ManifestEffectMetamodelSpec as M, type ManifestListResponse as N, OntologyHandle as O, type Prompt as P, type BuildStatus 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 Build as X, type Version as Y, type BuildListResponse as Z, type SemanticVersionDiffEntry as _, type EffectHandlerContext as a, type ManifestValidationRuleSpec as a$, type ResolvedEffectPostCondition as a0, type ResolvedEffectDryRun as a1, type ResolvedEffectReverse as a2, type ResolvedEffectApprovalRequired as a3, type EffectInvocationMode as a4, type EffectInvocationMetadata as a5, type EffectSchema as a6, type EffectWithHandler as a7, type PublishEffectsResult as a8, type ToolInfo as a9, type SessionCollectionListResult as aA, type WSDisconnectInfo as aB, type WSReconnectErrorInfo as aC, type WSClientOptions as aD, type RPCRequest as aE, type RPCResponse as aF, type SyncMessage as aG, type RPCRequestFromServer as aH, type ToolInvokeParams as aI, type ToolResultParams as aJ, type ModelRef as aK, type RelationshipInfo as aL, type DefineRelationshipOptions as aM, type RecordObjectOptions as aN, type RecordObjectResult as aO, type RecordObjectsChunkInfo as aP, type RecordObjectsOptions as aQ, type RecordImportStatus as aR, type RecordImportItemStatus as aS, type RecordImportStats as aT, type RecordImportItem as aU, type RecordImport as aV, type EnvironmentRecordImportSummary as aW, type ManifestPropertySpec as aX, type ManifestValidationOperator as aY, type ManifestEnumRuleSpec as aZ, type ManifestFilterBySpec as a_, type EffectInfo as aa, type ToolsChangedEvent as ab, type EffectsChangedEvent as ac, type EffectHandler as ad, type InstanceEffectHandler as ae, type JobStatus as af, type JobFeedbackSentiment as ag, type JobFeedbackToolCall as ah, type JobFeedbackMetadata as ai, type JobFeedbackInput as aj, type JobFeedbackRecord as ak, type EnvironmentFeedbackRecord as al, type JobSubmitResult as am, type Job as an, type ConversationMessageShowRefs as ao, type ConversationMessageInput as ap, type ConversationAppendResult as aq, type SessionConversationMessage as ar, type SessionTimelineEvent as as, type SessionJobRecord as at, type SessionHeapFieldType as au, type SessionHeapFieldValue as av, type SessionHeapVariable as aw, type SessionDocumentResult as ax, type SessionCollectionListOptions as ay, type SessionJobListOptions as az, type SessionHeapList as b, type ManifestStateMachineStateSpec as b0, type ManifestStateMachineTransitionSpec as b1, type ManifestStateMachineSpec as b2, type ManifestPostConditionSpec as b3, type ManifestDryRunSpec as b4, type ManifestReverseSpec as b5, type ManifestApprovalRequiredSpec as b6, type ManifestRelationshipDef as b7, type ManifestEffectSchema as b8, type ManifestEffectDeclaration as b9, type ManifestEventTypeDef as ba, type ManifestEventStreamDef as bb, type ManifestOperation as bc, type ManifestImport as bd, type ManifestVolume as be, type ManifestContent as bf, type GraphQLResult as bg, type APIError as bh, type DeleteResponse as bi, type StreamEvent as bj, type StreamSubscription as bk, type StreamStats as bl, type SessionHeapSnapshot as c, type SessionTranscriptEntry as d, Environment as e, EnvironmentSession as f, Session as g, type ToolSchema as h, type PublishToolsResult as i, type ToolHandler as j, type GranularOptions as k, type GranularAuth as l, type RecordUserOptions as m, type Subject as n, type OpenEnvironmentOptions as o, type CreateSessionOptions as p, type ConversationSessionInfo as q, type Sandbox as r, type CreateSandboxData as s, type SandboxListResponse as t, type PermissionRules as u, type PermissionProfile as v, type CreatePermissionProfileData as w, type PermissionProfileListResponse as x, type Assignment as y, type AssignmentListResponse as z };
+export { type SemanticVersionDiff as $, type AccessTokenProvider as A, type BuildPolicy as B, type ConnectOptions as C, type DomainState as D, type EndpointMode as E, type VersionTag as F, Granular as G, type EnvironmentData as H, type InstanceToolHandler as I, type CreateEnvironmentData as J, type EnvironmentListResponse as K, type Manifest as L, type ManifestEffectMetamodelSpec as M, type ManifestListResponse as N, OntologyHandle as O, type Prompt as P, type BuildStatus 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 Build as X, type Version as Y, type BuildListResponse as Z, type SemanticVersionDiffEntry as _, type EffectHandlerContext as a, type EnvironmentImporterImportOptions as a$, type ResolvedEffectPostCondition as a0, type ResolvedEffectDryRun as a1, type ResolvedEffectReverse as a2, type ResolvedEffectApprovalRequired as a3, type EffectInvocationMode as a4, type EffectInvocationMetadata as a5, type EffectSchema as a6, type EffectWithHandler as a7, type PublishEffectsResult as a8, type EffectVersionSelector as a9, type SessionJobListOptions as aA, type SessionCollectionListResult as aB, type WSDisconnectInfo as aC, type WSReconnectErrorInfo as aD, type WSClientOptions as aE, type RPCRequest as aF, type RPCResponse as aG, type SyncMessage as aH, type RPCRequestFromServer as aI, type ToolInvokeParams as aJ, type ToolResultParams as aK, type ModelRef as aL, type RelationshipInfo as aM, type DefineRelationshipOptions as aN, type RecordObjectOptions as aO, type RecordObjectResult as aP, type RecordObjectsChunkInfo as aQ, type RecordObjectsOptions as aR, type RecordImportStatus as aS, type RecordImportItemStatus as aT, type RecordImportStats as aU, type RecordImportItem as aV, type RecordImport as aW, type EnvironmentRecordImportSummary as aX, type EnvironmentSetupTriggerReason as aY, type EnvironmentSetupLifecycleStatus as aZ, type EnvironmentSetupSummary as a_, type ToolInfo as aa, type EffectInfo as ab, type ToolsChangedEvent as ac, type EffectsChangedEvent as ad, type EffectHandler as ae, type InstanceEffectHandler as af, type JobStatus as ag, type JobFeedbackSentiment as ah, type JobFeedbackToolCall as ai, type JobFeedbackMetadata as aj, type JobFeedbackInput as ak, type JobFeedbackRecord as al, type EnvironmentFeedbackRecord as am, type JobSubmitResult as an, type Job as ao, type ConversationMessageShowRefs as ap, type ConversationMessageInput as aq, type ConversationAppendResult as ar, type SessionConversationMessage as as, type SessionTimelineEvent as at, type SessionJobRecord as au, type SessionHeapFieldType as av, type SessionHeapFieldValue as aw, type SessionHeapVariable as ax, type SessionDocumentResult as ay, type SessionCollectionListOptions as az, type SessionHeapList as b, type EnvironmentImporter as b0, type ManifestPropertySpec as b1, type ManifestValidationOperator as b2, type ManifestEnumRuleSpec as b3, type ManifestFilterBySpec as b4, type ManifestValidationRuleSpec as b5, type ManifestStateMachineStateSpec as b6, type ManifestStateMachineTransitionSpec as b7, type ManifestStateMachineSpec as b8, type ManifestPostConditionSpec as b9, type ManifestDryRunSpec as ba, type ManifestReverseSpec as bb, type ManifestApprovalRequiredSpec as bc, type ManifestRelationshipDef as bd, type ManifestEffectSchema as be, type ManifestEffectDeclaration as bf, type ManifestEventTypeDef as bg, type ManifestEventStreamDef as bh, type ManifestOperation as bi, type ManifestImport as bj, type ManifestVolume as bk, type ManifestContent as bl, type GraphQLResult as bm, type APIError as bn, type DeleteResponse as bo, type StreamEvent as bp, type StreamSubscription as bq, type StreamStats as br, type SessionHeapSnapshot as c, type SessionTranscriptEntry as d, Environment as e, EnvironmentSession as f, Session as g, type ToolSchema as h, type PublishToolsResult as i, type ToolHandler as j, type GranularOptions as k, type GranularAuth as l, type RecordUserOptions as m, type Subject as n, type OpenEnvironmentOptions as o, type CreateSessionOptions as p, type ConversationSessionInfo as q, type Sandbox as r, type CreateSandboxData as s, type SandboxListResponse as t, type PermissionRules as u, type PermissionProfile as v, type CreatePermissionProfileData as w, type PermissionProfileListResponse as x, type Assignment as y, type AssignmentListResponse as z };