@granular-software/sdk 0.4.51 → 0.4.53

package/dist/cli/index.js

@@ -7898,14 +7898,14 @@ var ApiClient = class {
   async getVersion(versionId) {
     return this.request(`/control/versions/${versionId}`);
   }
-  async triggerBuild(sandboxId, manifestId) {
+  async triggerBuild(sandboxId, manifestId, releaseKey) {
     return this.request(`/control/sandboxes/${sandboxId}/builds`, {
       method: "POST",
-      body: JSON.stringify({ manifestId })
+      body: JSON.stringify({ manifestId, releaseKey })
     });
   }
-  async createVersion(sandboxId, manifestId) {
-    return this.triggerBuild(sandboxId, manifestId);
+  async createVersion(sandboxId, manifestId, releaseKey) {
+    return this.triggerBuild(sandboxId, manifestId, releaseKey);
   }
   async listTags(sandboxId) {
     const result = await this.request(
@@ -18947,7 +18947,7 @@ async function deployCommand(options = {}) {
     ]);
     const devTag = tags.find((tag2) => tag2.name === "dev");
     const prodTag = tags.find((tag2) => tag2.name === "prod");
-    const existingVersion = versions.find(
+    const existingVersion = options.releaseKey ? null : versions.find(
       (version2) => version2.manifestDigest === uploadedManifest.digest
     ) || null;
     const existingVersionId = existingVersion?.buildId || null;
@@ -18965,19 +18965,27 @@ async function deployCommand(options = {}) {
     } else {
       const version2 = await api.createVersion(
         config.sandboxId,
-        uploadedManifest.manifestId
-      );
-      const startTime = Date.now();
-      building.text = `  Running build for version... ${brand.muted(version2.buildId)}`;
-      completed = await api.waitForVersionBuild(version2.buildId, (status) => {
-        const elapsed = Math.round((Date.now() - startTime) / 1e3);
-        building.text = `  Running build for version... ${brand.muted(`${status} (${elapsed}s)`)}`;
-      });
-      totalTime = Math.round((Date.now() - startTime) / 1e3);
-      deployedToDev = true;
-      building.succeed(
-        `  Dev now points to ${brand.secondary(completed.buildId)} (${totalTime}s)`
+        uploadedManifest.manifestId,
+        options.releaseKey
       );
+      if (version2.createdNewVersion === false && version2.status === "completed") {
+        completed = version2;
+        building.succeed(
+          `  Reused ${brand.secondary(version2.buildId)}; the release key is unchanged.`
+        );
+      } else {
+        const startTime = Date.now();
+        building.text = `  Running build for version... ${brand.muted(version2.buildId)}`;
+        completed = await api.waitForVersionBuild(version2.buildId, (status) => {
+          const elapsed = Math.round((Date.now() - startTime) / 1e3);
+          building.text = `  Running build for version... ${brand.muted(`${status} (${elapsed}s)`)}`;
+        });
+        totalTime = Math.round((Date.now() - startTime) / 1e3);
+        deployedToDev = true;
+        building.succeed(
+          `  Dev now points to ${brand.secondary(completed.buildId)} (${totalTime}s)`
+        );
+      }
     }
     if (!completed) {
       throw new Error("Could not resolve the current ontology version.");
@@ -19008,6 +19016,7 @@ async function deployCommand(options = {}) {
       Release: options.prod ? deployedToDev ? "dev and prod now point to this version" : "prod promoted to the version already on dev" : "dev updated to this version",
       "Agent doc": "GRANULAR_SANDBOX.md"
     });
+    console.log(`GRANULAR_RELEASE_CHANGED=${deployedToDev ? "true" : "false"}`);
     console.log();
     if (options.prod) {
       info(
@@ -23201,7 +23210,8 @@ function normalizeEnvironmentSetupSummary(setup) {
     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",
+    triggerReason: setup.triggerReason === "fresh_after_version_update" ? "fresh_after_version_update" : setup.triggerReason === "explicit_reset" ? "explicit_reset" : "new_environment",
+    operationKey: typeof setup.operationKey === "string" ? setup.operationKey : null,
     lifecycleStatus: setup.lifecycleStatus === "completed" || setup.lifecycleStatus === "failed" ? setup.lifecycleStatus : "running",
     stage: typeof setup.stage === "string" ? setup.stage : null,
     totalObjectsToImport: Number(setup.totalObjectsToImport || 0),
@@ -24483,6 +24493,7 @@ var Environment = class _Environment {
           records: recordsToImport,
           batchSize: options.batchSize,
           setupRunId: options.setupRunId,
+          operationKey: options.operationKey,
           writeMode: options.writeMode
         })
       }
@@ -25287,6 +25298,156 @@ var Granular = class _Granular {
     await this.maybeRunEnvironmentImporter(resolved, environment);
     return environment;
   }
+  /**
+   * Read the active environment selected by Granular for an already-recorded
+   * external user. This is intentionally read-only: browser/login code must
+   * not create subjects or environments as a side effect.
+   */
+  async getActiveEnvironmentForUser(options) {
+    const sandboxId = options.sandboxId.trim();
+    const tagName = options.tag.trim();
+    const userId = options.userId.trim();
+    if (!sandboxId || !tagName || !userId) {
+      throw new Error(
+        "getActiveEnvironmentForUser() requires sandboxId, tag, and userId."
+      );
+    }
+    const subjects = await this.request(
+      `/control/subjects?identityId=${encodeURIComponent(userId)}`
+    );
+    const subject = (subjects.items || []).find(
+      (item) => item.identityId === userId || item.userId === userId
+    );
+    if (!subject?.subjectId && !subject?.granularId) {
+      return null;
+    }
+    const subjectId = subject.subjectId || subject.granularId;
+    const tags = await this.request(
+      `/control/sandboxes/${encodeURIComponent(sandboxId)}/tags`
+    );
+    const tag2 = (tags.items || []).find(
+      (item) => item?.name === tagName
+    );
+    if (!tag2) return null;
+    const query = new URLSearchParams({
+      tagId: tag2.tagId,
+      slot: options.slot?.trim() || "default"
+    });
+    try {
+      const payload = await this.request(
+        `/control/sandboxes/${encodeURIComponent(sandboxId)}/subjects/${encodeURIComponent(subjectId)}/active-environment?${query.toString()}`
+      );
+      return payload.environment ? this.bindEnvironmentHandle(
+        normalizeEnvironmentData(payload.environment)
+      ) : null;
+    } catch (error2) {
+      const message = error2 instanceof Error ? error2.message : String(error2);
+      if (message.includes("404") || message.includes("not found")) {
+        return null;
+      }
+      throw error2;
+    }
+  }
+  /**
+   * Resolve one exact environment only when Granular confirms that it belongs
+   * to the given external user in the requested sandbox (and, optionally,
+   * tag). This is deliberately read-only: callers use it to keep an already
+   * opened delegated workspace stable while a newer active environment is
+   * being prepared in the background.
+   */
+  async getEnvironmentForUser(options) {
+    const sandboxId = options.sandboxId.trim();
+    const userId = options.userId.trim();
+    const environmentId = options.environmentId.trim();
+    const tagName = options.tag?.trim();
+    if (!sandboxId || !userId || !environmentId) {
+      throw new Error(
+        "getEnvironmentForUser() requires sandboxId, userId, and environmentId."
+      );
+    }
+    const subjects = await this.request(
+      `/control/subjects?identityId=${encodeURIComponent(userId)}`
+    );
+    const subject = (subjects.items || []).find(
+      (item) => item.identityId === userId || item.userId === userId
+    );
+    const subjectId = subject?.subjectId || subject?.granularId;
+    if (!subjectId) return null;
+    let environment;
+    try {
+      environment = await this.environments.get(environmentId);
+    } catch (error2) {
+      const message = error2 instanceof Error ? error2.message : String(error2);
+      if (message.includes("404") || message.includes("not found")) {
+        return null;
+      }
+      throw error2;
+    }
+    if (environment.sandboxId !== sandboxId || environment.subjectId !== subjectId) {
+      return null;
+    }
+    if (tagName) {
+      const tags = await this.request(`/control/sandboxes/${encodeURIComponent(sandboxId)}/tags`);
+      const tag2 = (tags.items || []).find(
+        (candidate) => candidate?.name === tagName
+      );
+      if (!tag2 || environment.tagId !== tag2.tagId) {
+        return null;
+      }
+    }
+    return this.bindEnvironmentHandle(environment);
+  }
+  /**
+   * Register one reviewed, pre-existing environment as the active workspace
+   * for an external user. This is for a controlled migration only: it does
+   * not create an environment and it does not run an importer.
+   */
+  async adoptEnvironmentForUser(options) {
+    const sandboxId = options.sandboxId.trim();
+    const tagName = options.tag.trim();
+    const userId = options.userId.trim();
+    const environmentId = options.environmentId.trim();
+    if (!sandboxId || !tagName || !userId || !environmentId) {
+      throw new Error(
+        "adoptEnvironmentForUser() requires sandboxId, tag, userId, and environmentId."
+      );
+    }
+    const subjects = await this.request(
+      `/control/subjects?identityId=${encodeURIComponent(userId)}`
+    );
+    const subject = (subjects.items || []).find(
+      (item) => item.identityId === userId || item.userId === userId
+    );
+    if (!subject?.subjectId && !subject?.granularId) {
+      throw new Error(`No Granular subject exists for user ${userId}.`);
+    }
+    const tags = await this.request(`/control/sandboxes/${encodeURIComponent(sandboxId)}/tags`);
+    const tag2 = (tags.items || []).find(
+      (item) => item?.name === tagName
+    );
+    if (!tag2) {
+      throw new Error(`Tag ${tagName} was not found in sandbox ${sandboxId}.`);
+    }
+    const payload = await this.request(
+      "/control/environment-activations/adopt",
+      {
+        method: "POST",
+        body: JSON.stringify({
+          environmentId,
+          subjectId: subject.subjectId || subject.granularId,
+          tagId: tag2.tagId,
+          slot: options.slot?.trim() || "default",
+          confirmExistingData: true
+        })
+      }
+    );
+    if (!payload.environment) {
+      throw new Error("Granular did not return the adopted environment.");
+    }
+    return this.bindEnvironmentHandle(
+      normalizeEnvironmentData(payload.environment)
+    );
+  }
   /**
    * Deprecated compatibility alias for `openEnvironment()`.
    *
@@ -25318,7 +25479,9 @@ var Granular = class _Granular {
         requestedOntology,
         sandboxId: environmentData.sandboxId,
         subjectId: environmentData.subjectId,
-        setupTriggerReason: options.reason || "new_environment"
+        externalUserId: environmentData.subjectId,
+        setupTriggerReason: options.reason || "new_environment",
+        setupOperationKey: options.operationKey
       },
       environment
     );
@@ -25330,20 +25493,17 @@ var Granular = class _Granular {
     }
     return tag2;
   }
-  buildManagedEnvironmentName(tag2, versionId) {
-    return `__sdk__${tag2}__${versionId}__pinned`;
+  buildManagedEnvironmentName(tag2, versionId, resetKey) {
+    if (!resetKey) {
+      return `__sdk__${tag2}__${versionId}__tracked`;
+    }
+    const safeResetKey = resetKey.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 80);
+    return `__sdk__${tag2}__${versionId}__reset__${safeResetKey}`;
   }
   isManagedEnvironmentName(environment, tagName) {
     const name = environment.environment || environment.envName || "";
     return name.startsWith(`__sdk__${tagName}__`);
   }
-  isPinnedToVersion(environment, versionId) {
-    return environment.buildPolicy.mode === "pinned" && (environment.versionId === versionId || environment.buildPolicy.versionId === versionId || environment.buildPolicy.buildId === versionId);
-  }
-  matchesTagTrackedEnvironment(environment, tagName, tagId) {
-    const environmentTagName = environment.tag?.name || environment.buildPolicy.tagName || null;
-    return environment.tagId === tagId || environmentTagName === tagName || environment.environment === tagName || environment.envName === tagName || environment.environment === this.buildManagedEnvironmentName(tagName, environment.versionId) || environment.envName === this.buildManagedEnvironmentName(tagName, environment.versionId);
-  }
   sortEnvironmentsByRecency(environments) {
     return [...environments].sort(
       (left, right) => right.updatedAt - left.updatedAt
@@ -25393,48 +25553,119 @@ var Granular = class _Granular {
         `Tag "${tagName}" does not currently point to a build/version.`
       );
     }
+    const slot = options.slot?.trim() || "default";
+    const resetKey = options.resetKey?.trim() || void 0;
+    const resolveActive = async (operationKey) => {
+      const query = new URLSearchParams({ tagId: tag2.tagId, slot });
+      if (operationKey) query.set("operationKey", operationKey);
+      try {
+        const payload = await this.request(
+          `/control/sandboxes/${encodeURIComponent(sandbox.sandboxId)}/subjects/${encodeURIComponent(user.granularId)}/active-environment?${query.toString()}`
+        );
+        return payload.environment ? normalizeEnvironmentData(payload.environment) : null;
+      } catch (error2) {
+        const message = error2 instanceof Error ? error2.message : String(error2);
+        if (message.includes("404") || message.includes("not found")) {
+          return null;
+        }
+        throw error2;
+      }
+    };
+    const activate = async (environment2) => {
+      const payload = await this.request(
+        "/control/environment-activations",
+        {
+          method: "POST",
+          body: JSON.stringify({
+            environmentId: environment2.environmentId,
+            tagId: tag2.tagId,
+            slot,
+            operationKey: resetKey,
+            operation: resetKey ? "explicit_reset" : void 0
+          })
+        }
+      );
+      return normalizeEnvironmentData(payload.environment);
+    };
+    if (resetKey) {
+      const resetEnvironment = await resolveActive(resetKey);
+      if (resetEnvironment) {
+        return {
+          environment: resetEnvironment,
+          requestedOntology: ontology,
+          sandboxId: sandbox.sandboxId,
+          subjectId: user.granularId,
+          externalUserId: user.userId,
+          // Retrying an explicit reset must also resume its durable setup run.
+          // Otherwise a Container crash after queue submission would leave a
+          // valid environment permanently marked as "running".
+          setupTriggerReason: "explicit_reset",
+          setupOperationKey: resetKey
+        };
+      }
+    } else {
+      const active = await resolveActive();
+      if (active && (active.versionId === targetVersionId || options.createFreshIfOutdated !== true)) {
+        return {
+          environment: active,
+          requestedOntology: ontology,
+          sandboxId: sandbox.sandboxId,
+          subjectId: user.granularId,
+          externalUserId: user.userId
+        };
+      }
+    }
     const allEnvironments = await this.environments.list(sandbox.sandboxId);
     const userEnvironments = allEnvironments.filter(
-      (environment) => environment.subjectId === user.granularId
+      (environment2) => environment2.subjectId === user.granularId
     );
     const currentMatches = this.sortEnvironmentsByRecency(
       userEnvironments.filter(
-        (environment) => this.matchesTagTrackedEnvironment(environment, tagName, tag2.tagId) && environment.versionId === targetVersionId && (!this.isManagedEnvironmentName(environment, tagName) || this.isPinnedToVersion(environment, targetVersionId))
+        (environment2) => environment2.tagId === tag2.tagId && environment2.versionId === targetVersionId
       )
     );
-    if (currentMatches.length > 0) {
+    if (!resetKey && currentMatches.length > 0) {
+      const environment2 = await activate(currentMatches[0]);
       return {
-        environment: currentMatches[0],
+        environment: environment2,
         requestedOntology: ontology,
         sandboxId: sandbox.sandboxId,
-        subjectId: user.granularId
+        subjectId: user.granularId,
+        externalUserId: user.userId
       };
     }
     const outdatedMatches = this.sortEnvironmentsByRecency(
-      userEnvironments.filter(
-        (environment) => this.matchesTagTrackedEnvironment(environment, tagName, tag2.tagId)
-      )
+      userEnvironments.filter((environment2) => environment2.tagId === tag2.tagId)
     );
     if (outdatedMatches.length > 0 && options.createFreshIfOutdated !== true) {
+      const environment2 = await activate(outdatedMatches[0]);
       return {
-        environment: outdatedMatches[0],
+        environment: environment2,
         requestedOntology: ontology,
         sandboxId: sandbox.sandboxId,
-        subjectId: user.granularId
+        subjectId: user.granularId,
+        externalUserId: user.userId
       };
     }
+    const created = await this.environments.create(sandbox.sandboxId, {
+      subjectId: user.granularId,
+      environment: this.buildManagedEnvironmentName(
+        tagName,
+        targetVersionId,
+        resetKey
+      ),
+      tagId: tag2.tagId,
+      permissionProfileId: null
+    });
+    const environment = await activate(created);
     return {
-      environment: await this.environments.create(sandbox.sandboxId, {
-        subjectId: user.granularId,
-        environment: this.buildManagedEnvironmentName(tagName, targetVersionId),
-        tagId: tag2.tagId,
-        versionId: targetVersionId,
-        permissionProfileId: null
-      }),
+      environment,
       requestedOntology: ontology,
       sandboxId: sandbox.sandboxId,
       subjectId: user.granularId,
-      setupTriggerReason: outdatedMatches.length > 0 ? "fresh_after_version_update" : "new_environment"
+      externalUserId: user.userId,
+      setupTriggerReason: resetKey ? "explicit_reset" : outdatedMatches.length > 0 ? "fresh_after_version_update" : "new_environment",
+      setupOperationKey: resetKey
     };
   }
   /**
@@ -25713,11 +25944,24 @@ var Granular = class _Granular {
       {
         method: "POST",
         body: JSON.stringify({
-          triggerReason: resolved.setupTriggerReason
+          triggerReason: resolved.setupTriggerReason,
+          operationKey: resolved.setupOperationKey
         })
       }
     );
     const setupRunId = setupRun.setupRunId;
+    let claim = null;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      claim = await this.request(
+        `/control/environment-setup-runs/${setupRunId}/importer-claim`,
+        { method: "POST", body: JSON.stringify({}) }
+      );
+      if (claim.action !== "busy") break;
+      await sleep(Math.min(3e4, Math.max(250, claim.retryAfterMs || 1e3)));
+    }
+    if (!claim) {
+      throw new Error(`Unable to claim environment setup run ${setupRunId}.`);
+    }
     const updateSetupRun = async (patch) => {
       await this.request(
         `/control/environment-setup-runs/${setupRunId}`,
@@ -25727,10 +25971,26 @@ var Granular = class _Granular {
         }
       );
     };
+    if (claim.action === "submitted") {
+      const completedSetupRun = await this.request(
+        `/control/environment-setup-runs/${setupRunId}`,
+        { method: "PATCH", body: JSON.stringify({ markHookCompleted: true }) }
+      );
+      const refreshedEnvironment = await this.environments.get(
+        environment.environmentId
+      );
+      environment.syncEnvironmentData(refreshedEnvironment);
+      return completedSetupRun;
+    }
+    if (claim.action === "busy" || claim.action === "terminal") {
+      return claim.summary;
+    }
+    let importSequence = 0;
     const importerContext = {
       environmentId: environment.environmentId,
       sandboxId: environment.sandboxId,
       subjectId: environment.subjectId,
+      externalUserId: resolved.externalUserId,
       reason: resolved.setupTriggerReason,
       incrementTotalObjectsToImportCount: async (n) => {
         const safeIncrement = Math.max(0, Math.trunc(n));
@@ -25747,7 +26007,10 @@ var Granular = class _Granular {
       importRecords: async (records, options) => environment.enqueueRecordImport(records, {
         batchSize: options?.batchSize,
         writeMode: options?.writeMode,
-        setupRunId
+        setupRunId,
+        // Sequence is deterministic for a retry of one importer hook. It
+        // prevents a Container restart from creating a second queue import.
+        operationKey: `${setupRunId}:import:${importSequence++}`
       })
     };
     try {
@@ -27964,9 +28227,12 @@ program2.command("build").description(
 });
 program2.command("deploy").description(
   "Push the current revision to dev; use --prod to move prod there too"
-).option("--prod", "Also point prod to the current version").action(async (opts) => {
+).option("--prod", "Also point prod to the current version").option(
+  "--release-key <key>",
+  "Version data/importer changes with this immutable release key"
+).action(async (opts) => {
   try {
-    await deployCommand({ prod: opts.prod });
+    await deployCommand({ prod: opts.prod, releaseKey: opts.releaseKey });
   } catch (err) {
     error(err.message);
     process.exit(1);

package/dist/{client-djorlOpn.d.mts → client-CfTDojJF.d.mts}

@@ -1,4 +1,4 @@
-import { bL as WSClientOptions, a1 as GranularQuotaProgress, T as ToolWithHandler, f as PublishToolsResult, aN as Job, g as ToolHandler, I as InstanceToolHandler, aX as ConversationMessageInput, aY as ConversationAppendResult, aA as EffectInfo, P as Prompt, az as ToolInfo, aC as EffectsChangedEvent, aB as ToolsChangedEvent, D as DomainState, y as GranularOptions, cg as EnvironmentImporter, B as RecordUserOptions, U as User, H as OpenEnvironmentOptions, ae as EnvironmentData, ab as BuildPolicy, ce as EnvironmentSetupSummary, V as ConversationSessionListOptions, L as ConversationSessionInfo, K as CreateSessionOptions, bV as RecordObjectOptions, c0 as RecordObjectResult, c2 as RecordObjectsOptions, c9 as RecordImport, c5 as RecordImportStatus, ca as EnvironmentRecordImportSummary, aL as EnvironmentFeedbackRecord, c as SessionHeapSnapshot, bz as SessionDocumentResult, bA as SessionCollectionListOptions, bC as SessionCollectionListResult, aZ as SessionConversationMessage, a_ as SessionTimelineEvent, bB as SessionJobListOptions, bs as SessionJobRecord, b7 as SessionArtifactListOptions, b6 as SessionArtifactRecord, b8 as SessionArtifactValidationResult, ba as SessionArtifactExecutionOptions, b9 as SessionArtifactExecutionResult, bb as SessionArtifactApprovalOptions, bl as RecordManualActionInput, bn as ManualActionRecordResult, bo as ManualActionListOptions, bm as ManualActionOccurrence, bq as ManualActionSuggestionOptions, bp as ManualActionSuggestion, be as ArtifactApprovalTaskListOptions, bd as ArtifactApprovalTask, bf as ArtifactApprovalDecisionInput, bg as ArtifactApprovalDecisionResult, b2 as SessionFileRecord, br as SessionFileUploadOptions, S as SessionHeapEntry, b as SessionHeapList, bv as SessionHeapVariable, d as SessionTranscriptEntry, cK as GraphQLResult, bx as RecordSearchOptions, bw as RecordSearchResult, by as RecordMentionInput, bU as DefineRelationshipOptions, bT as RelationshipInfo, bS as ModelRef, cJ as ManifestContent, bZ as EnvironmentStateUpdateInput, bX as EnvironmentStateTarget, b$ as EnvironmentStateProxy, c4 as RecordImportOptions, bH as UserEnvironmentStateOptions, bG as UserEnvironmentState, bI as MarkUserEnvironmentReadOptions, J as ConnectOptions, cc as RunEnvironmentImporterOptions, l as OpenAIUsageSpendEvent, G as GranularSpendContext, o as RecordOpenAIUsageSpendResult, a4 as SandboxListResponse, a2 as Sandbox, a3 as CreateSandboxData, cM as DeleteResponse, a6 as PermissionProfile, a7 as CreatePermissionProfileData, af as CreateEnvironmentData, cN as StreamEvent, cO as StreamSubscription, cP as StreamStats, F as Subject, aa as AssignmentListResponse } from './spend-BA-jZwZ0.mjs';
+import { bM as WSClientOptions, a2 as GranularQuotaProgress, T as ToolWithHandler, f as PublishToolsResult, aO as Job, g as ToolHandler, I as InstanceToolHandler, aY as ConversationMessageInput, aZ as ConversationAppendResult, aB as EffectInfo, P as Prompt, aA as ToolInfo, aD as EffectsChangedEvent, aC as ToolsChangedEvent, D as DomainState, y as GranularOptions, ci as EnvironmentImporter, B as RecordUserOptions, U as User, H as OpenEnvironmentOptions, af as EnvironmentData, ac as BuildPolicy, cf as EnvironmentSetupSummary, W as ConversationSessionListOptions, Q as ConversationSessionInfo, L as CreateSessionOptions, bW as RecordObjectOptions, c1 as RecordObjectResult, c3 as RecordObjectsOptions, ca as RecordImport, c6 as RecordImportStatus, cb as EnvironmentRecordImportSummary, aM as EnvironmentFeedbackRecord, c as SessionHeapSnapshot, bA as SessionDocumentResult, bB as SessionCollectionListOptions, bD as SessionCollectionListResult, a_ as SessionConversationMessage, a$ as SessionTimelineEvent, bC as SessionJobListOptions, bt as SessionJobRecord, b8 as SessionArtifactListOptions, b7 as SessionArtifactRecord, b9 as SessionArtifactValidationResult, bb as SessionArtifactExecutionOptions, ba as SessionArtifactExecutionResult, bc as SessionArtifactApprovalOptions, bm as RecordManualActionInput, bo as ManualActionRecordResult, bp as ManualActionListOptions, bn as ManualActionOccurrence, br as ManualActionSuggestionOptions, bq as ManualActionSuggestion, bf as ArtifactApprovalTaskListOptions, be as ArtifactApprovalTask, bg as ArtifactApprovalDecisionInput, bh as ArtifactApprovalDecisionResult, b3 as SessionFileRecord, bs as SessionFileUploadOptions, S as SessionHeapEntry, b as SessionHeapList, bw as SessionHeapVariable, d as SessionTranscriptEntry, cM as GraphQLResult, by as RecordSearchOptions, bx as RecordSearchResult, bz as RecordMentionInput, bV as DefineRelationshipOptions, bU as RelationshipInfo, bT as ModelRef, cL as ManifestContent, b_ as EnvironmentStateUpdateInput, bY as EnvironmentStateTarget, c0 as EnvironmentStateProxy, c5 as RecordImportOptions, bI as UserEnvironmentStateOptions, bH as UserEnvironmentState, bJ as MarkUserEnvironmentReadOptions, J as AdoptEnvironmentOptions, K as ConnectOptions, cd as RunEnvironmentImporterOptions, l as OpenAIUsageSpendEvent, G as GranularSpendContext, o as RecordOpenAIUsageSpendResult, a5 as SandboxListResponse, a3 as Sandbox, a4 as CreateSandboxData, cO as DeleteResponse, a7 as PermissionProfile, a8 as CreatePermissionProfileData, ag as CreateEnvironmentData, cP as StreamEvent, cQ as StreamSubscription, cR as StreamStats, F as Subject, ab as AssignmentListResponse } from './spend-DpRRCrAr.mjs';
 import * as Automerge from '@automerge/automerge';
 import { Doc } from '@automerge/automerge/slim';
 
@@ -952,6 +952,36 @@ declare class Granular {
      * ```
      */
     openEnvironment(options: OpenEnvironmentOptions): Promise<Environment>;
+    /**
+     * Read the active environment selected by Granular for an already-recorded
+     * external user. This is intentionally read-only: browser/login code must
+     * not create subjects or environments as a side effect.
+     */
+    getActiveEnvironmentForUser(options: {
+        sandboxId: string;
+        tag: string;
+        userId: string;
+        slot?: string;
+    }): Promise<Environment | null>;
+    /**
+     * Resolve one exact environment only when Granular confirms that it belongs
+     * to the given external user in the requested sandbox (and, optionally,
+     * tag). This is deliberately read-only: callers use it to keep an already
+     * opened delegated workspace stable while a newer active environment is
+     * being prepared in the background.
+     */
+    getEnvironmentForUser(options: {
+        sandboxId: string;
+        userId: string;
+        environmentId: string;
+        tag?: string;
+    }): Promise<Environment | null>;
+    /**
+     * Register one reviewed, pre-existing environment as the active workspace
+     * for an external user. This is for a controlled migration only: it does
+     * not create an environment and it does not run an importer.
+     */
+    adoptEnvironmentForUser(options: AdoptEnvironmentOptions): Promise<Environment>;
     /**
      * Deprecated compatibility alias for `openEnvironment()`.
      *
@@ -971,8 +1001,6 @@ declare class Granular {
     private resolveRequestedTag;
     private buildManagedEnvironmentName;
     private isManagedEnvironmentName;
-    private isPinnedToVersion;
-    private matchesTagTrackedEnvironment;
     private sortEnvironmentsByRecency;
     private resolveOpenEnvironmentData;
     /**

package/dist/{client-NSH-tpNU.d.ts → client-DcRzwuGp.d.ts}

@@ -1,4 +1,4 @@
-import { bL as WSClientOptions, a1 as GranularQuotaProgress, T as ToolWithHandler, f as PublishToolsResult, aN as Job, g as ToolHandler, I as InstanceToolHandler, aX as ConversationMessageInput, aY as ConversationAppendResult, aA as EffectInfo, P as Prompt, az as ToolInfo, aC as EffectsChangedEvent, aB as ToolsChangedEvent, D as DomainState, y as GranularOptions, cg as EnvironmentImporter, B as RecordUserOptions, U as User, H as OpenEnvironmentOptions, ae as EnvironmentData, ab as BuildPolicy, ce as EnvironmentSetupSummary, V as ConversationSessionListOptions, L as ConversationSessionInfo, K as CreateSessionOptions, bV as RecordObjectOptions, c0 as RecordObjectResult, c2 as RecordObjectsOptions, c9 as RecordImport, c5 as RecordImportStatus, ca as EnvironmentRecordImportSummary, aL as EnvironmentFeedbackRecord, c as SessionHeapSnapshot, bz as SessionDocumentResult, bA as SessionCollectionListOptions, bC as SessionCollectionListResult, aZ as SessionConversationMessage, a_ as SessionTimelineEvent, bB as SessionJobListOptions, bs as SessionJobRecord, b7 as SessionArtifactListOptions, b6 as SessionArtifactRecord, b8 as SessionArtifactValidationResult, ba as SessionArtifactExecutionOptions, b9 as SessionArtifactExecutionResult, bb as SessionArtifactApprovalOptions, bl as RecordManualActionInput, bn as ManualActionRecordResult, bo as ManualActionListOptions, bm as ManualActionOccurrence, bq as ManualActionSuggestionOptions, bp as ManualActionSuggestion, be as ArtifactApprovalTaskListOptions, bd as ArtifactApprovalTask, bf as ArtifactApprovalDecisionInput, bg as ArtifactApprovalDecisionResult, b2 as SessionFileRecord, br as SessionFileUploadOptions, S as SessionHeapEntry, b as SessionHeapList, bv as SessionHeapVariable, d as SessionTranscriptEntry, cK as GraphQLResult, bx as RecordSearchOptions, bw as RecordSearchResult, by as RecordMentionInput, bU as DefineRelationshipOptions, bT as RelationshipInfo, bS as ModelRef, cJ as ManifestContent, bZ as EnvironmentStateUpdateInput, bX as EnvironmentStateTarget, b$ as EnvironmentStateProxy, c4 as RecordImportOptions, bH as UserEnvironmentStateOptions, bG as UserEnvironmentState, bI as MarkUserEnvironmentReadOptions, J as ConnectOptions, cc as RunEnvironmentImporterOptions, l as OpenAIUsageSpendEvent, G as GranularSpendContext, o as RecordOpenAIUsageSpendResult, a4 as SandboxListResponse, a2 as Sandbox, a3 as CreateSandboxData, cM as DeleteResponse, a6 as PermissionProfile, a7 as CreatePermissionProfileData, af as CreateEnvironmentData, cN as StreamEvent, cO as StreamSubscription, cP as StreamStats, F as Subject, aa as AssignmentListResponse } from './spend-BA-jZwZ0.js';
+import { bM as WSClientOptions, a2 as GranularQuotaProgress, T as ToolWithHandler, f as PublishToolsResult, aO as Job, g as ToolHandler, I as InstanceToolHandler, aY as ConversationMessageInput, aZ as ConversationAppendResult, aB as EffectInfo, P as Prompt, aA as ToolInfo, aD as EffectsChangedEvent, aC as ToolsChangedEvent, D as DomainState, y as GranularOptions, ci as EnvironmentImporter, B as RecordUserOptions, U as User, H as OpenEnvironmentOptions, af as EnvironmentData, ac as BuildPolicy, cf as EnvironmentSetupSummary, W as ConversationSessionListOptions, Q as ConversationSessionInfo, L as CreateSessionOptions, bW as RecordObjectOptions, c1 as RecordObjectResult, c3 as RecordObjectsOptions, ca as RecordImport, c6 as RecordImportStatus, cb as EnvironmentRecordImportSummary, aM as EnvironmentFeedbackRecord, c as SessionHeapSnapshot, bA as SessionDocumentResult, bB as SessionCollectionListOptions, bD as SessionCollectionListResult, a_ as SessionConversationMessage, a$ as SessionTimelineEvent, bC as SessionJobListOptions, bt as SessionJobRecord, b8 as SessionArtifactListOptions, b7 as SessionArtifactRecord, b9 as SessionArtifactValidationResult, bb as SessionArtifactExecutionOptions, ba as SessionArtifactExecutionResult, bc as SessionArtifactApprovalOptions, bm as RecordManualActionInput, bo as ManualActionRecordResult, bp as ManualActionListOptions, bn as ManualActionOccurrence, br as ManualActionSuggestionOptions, bq as ManualActionSuggestion, bf as ArtifactApprovalTaskListOptions, be as ArtifactApprovalTask, bg as ArtifactApprovalDecisionInput, bh as ArtifactApprovalDecisionResult, b3 as SessionFileRecord, bs as SessionFileUploadOptions, S as SessionHeapEntry, b as SessionHeapList, bw as SessionHeapVariable, d as SessionTranscriptEntry, cM as GraphQLResult, by as RecordSearchOptions, bx as RecordSearchResult, bz as RecordMentionInput, bV as DefineRelationshipOptions, bU as RelationshipInfo, bT as ModelRef, cL as ManifestContent, b_ as EnvironmentStateUpdateInput, bY as EnvironmentStateTarget, c0 as EnvironmentStateProxy, c5 as RecordImportOptions, bI as UserEnvironmentStateOptions, bH as UserEnvironmentState, bJ as MarkUserEnvironmentReadOptions, J as AdoptEnvironmentOptions, K as ConnectOptions, cd as RunEnvironmentImporterOptions, l as OpenAIUsageSpendEvent, G as GranularSpendContext, o as RecordOpenAIUsageSpendResult, a5 as SandboxListResponse, a3 as Sandbox, a4 as CreateSandboxData, cO as DeleteResponse, a7 as PermissionProfile, a8 as CreatePermissionProfileData, ag as CreateEnvironmentData, cP as StreamEvent, cQ as StreamSubscription, cR as StreamStats, F as Subject, ab as AssignmentListResponse } from './spend-DpRRCrAr.js';
 import * as Automerge from '@automerge/automerge';
 import { Doc } from '@automerge/automerge/slim';
 
@@ -952,6 +952,36 @@ declare class Granular {
      * ```
      */
     openEnvironment(options: OpenEnvironmentOptions): Promise<Environment>;
+    /**
+     * Read the active environment selected by Granular for an already-recorded
+     * external user. This is intentionally read-only: browser/login code must
+     * not create subjects or environments as a side effect.
+     */
+    getActiveEnvironmentForUser(options: {
+        sandboxId: string;
+        tag: string;
+        userId: string;
+        slot?: string;
+    }): Promise<Environment | null>;
+    /**
+     * Resolve one exact environment only when Granular confirms that it belongs
+     * to the given external user in the requested sandbox (and, optionally,
+     * tag). This is deliberately read-only: callers use it to keep an already
+     * opened delegated workspace stable while a newer active environment is
+     * being prepared in the background.
+     */
+    getEnvironmentForUser(options: {
+        sandboxId: string;
+        userId: string;
+        environmentId: string;
+        tag?: string;
+    }): Promise<Environment | null>;
+    /**
+     * Register one reviewed, pre-existing environment as the active workspace
+     * for an external user. This is for a controlled migration only: it does
+     * not create an environment and it does not run an importer.
+     */
+    adoptEnvironmentForUser(options: AdoptEnvironmentOptions): Promise<Environment>;
     /**
      * Deprecated compatibility alias for `openEnvironment()`.
      *
@@ -971,8 +1001,6 @@ declare class Granular {
     private resolveRequestedTag;
     private buildManagedEnvironmentName;
     private isManagedEnvironmentName;
-    private isPinnedToVersion;
-    private matchesTagTrackedEnvironment;
     private sortEnvironmentsByRecency;
     private resolveOpenEnvironmentData;
     /**