@granular-software/sdk 0.4.51 → 0.4.52

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { E as Environment, a as EnvironmentSession, G as Granular, O as OntologyHandle, S as Session, W as WSClient } from './client-NSH-tpNU.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, d as SessionTranscriptEntry } from './spend-BA-jZwZ0.js';
-export { cL as APIError, A as AccessTokenProvider, bf as ArtifactApprovalDecisionInput, bg as ArtifactApprovalDecisionResult, bd as ArtifactApprovalTask, be as ArtifactApprovalTaskListOptions, bc as ArtifactApprovalTaskStatus, a9 as Assignment, aa as AssignmentListResponse, ak as Build, am as BuildListResponse, ab as BuildPolicy, aj as BuildStatus, C as ConditionIR, J as ConnectOptions, aU as ConversationActionSuggestion, aY as ConversationAppendResult, aV as ConversationMessageAction, aX as ConversationMessageInput, aW as ConversationMessagePart, aO as ConversationMessageShowRefs, L as ConversationSessionInfo, V as ConversationSessionListOptions, Q as ConversationSessionListStatus, aP as ConversationTableCell, aQ as ConversationTableColumn, aT as ConversationTableProjection, aS as ConversationTableRow, aR as ConversationTableRowReference, af as CreateEnvironmentData, a7 as CreatePermissionProfileData, a3 as CreateSandboxData, K as CreateSessionOptions, bU as DefineRelationshipOptions, cM as DeleteResponse, D as DomainState, aD as EffectHandler, aA as EffectInfo, au as EffectInvocationMetadata, at as EffectInvocationMode, av as EffectSchema, ay as EffectVersionSelector, aw as EffectWithHandler, aC as EffectsChangedEvent, ae as EnvironmentData, aL as EnvironmentFeedbackRecord, cg as EnvironmentImporter, cf as EnvironmentImporterImportOptions, ag as EnvironmentListResponse, ca as EnvironmentRecordImportSummary, cd as EnvironmentSetupLifecycleStatus, ce as EnvironmentSetupSummary, cb as EnvironmentSetupTriggerReason, b_ as EnvironmentStateMachineProxy, bY as EnvironmentStateObservationInput, b$ as EnvironmentStateProxy, bX as EnvironmentStateTarget, bZ as EnvironmentStateUpdateInput, z as GranularAuth, y as GranularOptions, a0 as GranularQuotaPolicy, a1 as GranularQuotaProgress, G as GranularSpendContext, cK as GraphQLResult, aE as InstanceEffectHandler, I as InstanceToolHandler, aN as Job, aJ as JobFeedbackInput, aI as JobFeedbackMetadata, aK as JobFeedbackRecord, aG as JobFeedbackSentiment, aH as JobFeedbackToolCall, aF as JobStatus, aM as JobSubmitResult, ah as Manifest, cz as ManifestApprovalRequiredSpec, cJ as ManifestContent, cA as ManifestCreatesSpec, cx as ManifestDryRunSpec, cD as ManifestEffectDeclaration, cC as ManifestEffectSchema, cj as ManifestEnumRuleSpec, cF as ManifestEventStreamDef, cE as ManifestEventTypeDef, ck as ManifestFilterBySpec, cH as ManifestImport, ai as ManifestListResponse, cG as ManifestOperation, cw as ManifestPostConditionSpec, ch as ManifestPropertySpec, cB as ManifestRelationshipDef, cy as ManifestReverseSpec, cv as ManifestStateMachineSpec, cm as ManifestStateMachineStateSpec, cu as ManifestStateMachineTransitionSpec, co as ManifestStateTransitionActionSpec, cp as ManifestStateTransitionAssigneeSpec, ct as ManifestStateTransitionExpectedOutcomeSpec, cn as ManifestStateTransitionInputBinding, cs as ManifestStateTransitionPermissionSpec, cq as ManifestStateTransitionRelatedStateRequirementSpec, cr as ManifestStateTransitionRequirementsSpec, ci as ManifestValidationOperator, cl as ManifestValidationRuleSpec, cI as ManifestVolume, bo as ManualActionListOptions, bm as ManualActionOccurrence, bn as ManualActionRecordResult, bk as ManualActionRelatedRecord, bi as ManualActionSource, bh as ManualActionStatus, bp as ManualActionSuggestion, bq as ManualActionSuggestionOptions, bj as ManualActionTarget, bI as MarkUserEnvironmentReadOptions, x as MatchedPolicy, bS as ModelRef, N as NormalizedOpenAIUsage, i as OPENAI_MODEL_PRICING_USD_PER_MILLION, O as OpenAIModelPricing, h as OpenAITokenSpend, l as OpenAIUsageSpendEvent, H as OpenEnvironmentOptions, a6 as PermissionProfile, a8 as PermissionProfileListResponse, a5 as PermissionRules, u as PolicyOperator, v as PolicyOrigin, s as PolicyPredicateSource, w as PolicyRuleIR, q as PolicySource, ax as PublishEffectsResult, f as PublishToolsResult, $ as QuotaLineItemFilter, Y as QuotaPeriod, X as QuotaScopeType, Z as QuotaStatus, bM as RPCRequest, bP as RPCRequestFromServer, bN as RPCResponse, c9 as RecordImport, c8 as RecordImportItem, c6 as RecordImportItemStatus, c4 as RecordImportOptions, c7 as RecordImportStats, c5 as RecordImportStatus, c3 as RecordImportWriteMode, bl as RecordManualActionInput, by as RecordMentionInput, bV as RecordObjectOptions, c0 as RecordObjectResult, bW as RecordObjectStateValue, c1 as RecordObjectsChunkInfo, c2 as RecordObjectsOptions, m as RecordOpenAIUsageSpendOptions, o as RecordOpenAIUsageSpendResult, bx as RecordSearchOptions, bw as RecordSearchResult, B as RecordUserOptions, bT as RelationshipInfo, as as ResolvedEffectApprovalRequired, aq as ResolvedEffectDryRun, ap as ResolvedEffectPostCondition, ar as ResolvedEffectReverse, cc as RunEnvironmentImporterOptions, a2 as Sandbox, a4 as SandboxListResponse, ao as SemanticVersionDiff, an as SemanticVersionDiffEntry, bb as SessionArtifactApprovalOptions, b5 as SessionArtifactAutonomyPolicy, ba as SessionArtifactExecutionOptions, b9 as SessionArtifactExecutionResult, b4 as SessionArtifactKind, b7 as SessionArtifactListOptions, b6 as SessionArtifactRecord, b3 as SessionArtifactStatus, b8 as SessionArtifactValidationResult, bA as SessionCollectionListOptions, bC as SessionCollectionListResult, aZ as SessionConversationMessage, bz as SessionDocumentResult, b0 as SessionFileKind, b2 as SessionFileRecord, a$ as SessionFileSource, b1 as SessionFileStatus, br as SessionFileUploadOptions, bt as SessionHeapFieldType, bu as SessionHeapFieldValue, bv as SessionHeapVariable, bB as SessionJobListOptions, bs as SessionJobRecord, a_ as SessionTimelineEvent, W as SpendLineItemType, _ as SpendSummary, cN as StreamEvent, cP as StreamStats, cO as StreamSubscription, F as Subject, bO as SyncMessage, g as ToolHandler, az as ToolInfo, bQ as ToolInvokeParams, bR as ToolResultParams, e as ToolSchema, aB as ToolsChangedEvent, U as User, bE as UserEnvironmentMessagePreview, bD as UserEnvironmentPrompt, bF as UserEnvironmentSessionState, bG as UserEnvironmentState, bH as UserEnvironmentStateOptions, al as Version, ad as VersionTag, ac as VersionTracking, bL as WSClientOptions, bJ as WSDisconnectInfo, bK as WSReconnectErrorInfo, p as buildOpenAISpendEventId, k as calculateOpenAITokenSpend, j as getOpenAIModelPricing, n as normalizeOpenAIUsage, r as recordOpenAIUsageSpend, t as toGranularHttpBase } from './spend-BA-jZwZ0.js';
+export { E as Environment, a as EnvironmentSession, G as Granular, O as OntologyHandle, S as Session, W as WSClient } from './client-BMfjRJTs.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, d as SessionTranscriptEntry } from './spend-DpRRCrAr.js';
+export { cN as APIError, A as AccessTokenProvider, J as AdoptEnvironmentOptions, bg as ArtifactApprovalDecisionInput, bh as ArtifactApprovalDecisionResult, be as ArtifactApprovalTask, bf as ArtifactApprovalTaskListOptions, bd as ArtifactApprovalTaskStatus, aa as Assignment, ab as AssignmentListResponse, al as Build, an as BuildListResponse, ac as BuildPolicy, ak as BuildStatus, C as ConditionIR, K as ConnectOptions, aV as ConversationActionSuggestion, aZ as ConversationAppendResult, aW as ConversationMessageAction, aY as ConversationMessageInput, aX as ConversationMessagePart, aP as ConversationMessageShowRefs, Q as ConversationSessionInfo, W as ConversationSessionListOptions, V as ConversationSessionListStatus, aQ as ConversationTableCell, aR as ConversationTableColumn, aU as ConversationTableProjection, aT as ConversationTableRow, aS as ConversationTableRowReference, ag as CreateEnvironmentData, a8 as CreatePermissionProfileData, a4 as CreateSandboxData, L as CreateSessionOptions, bV as DefineRelationshipOptions, cO as DeleteResponse, D as DomainState, aE as EffectHandler, aB as EffectInfo, av as EffectInvocationMetadata, au as EffectInvocationMode, aw as EffectSchema, az as EffectVersionSelector, ax as EffectWithHandler, aD as EffectsChangedEvent, af as EnvironmentData, aM as EnvironmentFeedbackRecord, ci as EnvironmentImporter, ch as EnvironmentImporterImportOptions, ah as EnvironmentListResponse, cb as EnvironmentRecordImportSummary, cg as EnvironmentSetupImporterClaim, ce as EnvironmentSetupLifecycleStatus, cf as EnvironmentSetupSummary, cc as EnvironmentSetupTriggerReason, b$ as EnvironmentStateMachineProxy, bZ as EnvironmentStateObservationInput, c0 as EnvironmentStateProxy, bY as EnvironmentStateTarget, b_ as EnvironmentStateUpdateInput, z as GranularAuth, y as GranularOptions, a1 as GranularQuotaPolicy, a2 as GranularQuotaProgress, G as GranularSpendContext, cM as GraphQLResult, aF as InstanceEffectHandler, I as InstanceToolHandler, aO as Job, aK as JobFeedbackInput, aJ as JobFeedbackMetadata, aL as JobFeedbackRecord, aH as JobFeedbackSentiment, aI as JobFeedbackToolCall, aG as JobStatus, aN as JobSubmitResult, ai as Manifest, cB as ManifestApprovalRequiredSpec, cL as ManifestContent, cC as ManifestCreatesSpec, cz as ManifestDryRunSpec, cF as ManifestEffectDeclaration, cE as ManifestEffectSchema, cl as ManifestEnumRuleSpec, cH as ManifestEventStreamDef, cG as ManifestEventTypeDef, cm as ManifestFilterBySpec, cJ as ManifestImport, aj as ManifestListResponse, cI as ManifestOperation, cy as ManifestPostConditionSpec, cj as ManifestPropertySpec, cD as ManifestRelationshipDef, cA as ManifestReverseSpec, cx as ManifestStateMachineSpec, co as ManifestStateMachineStateSpec, cw as ManifestStateMachineTransitionSpec, cq as ManifestStateTransitionActionSpec, cr as ManifestStateTransitionAssigneeSpec, cv as ManifestStateTransitionExpectedOutcomeSpec, cp as ManifestStateTransitionInputBinding, cu as ManifestStateTransitionPermissionSpec, cs as ManifestStateTransitionRelatedStateRequirementSpec, ct as ManifestStateTransitionRequirementsSpec, ck as ManifestValidationOperator, cn as ManifestValidationRuleSpec, cK as ManifestVolume, bp as ManualActionListOptions, bn as ManualActionOccurrence, bo as ManualActionRecordResult, bl as ManualActionRelatedRecord, bj as ManualActionSource, bi as ManualActionStatus, bq as ManualActionSuggestion, br as ManualActionSuggestionOptions, bk as ManualActionTarget, bJ as MarkUserEnvironmentReadOptions, x as MatchedPolicy, bT as ModelRef, N as NormalizedOpenAIUsage, i as OPENAI_MODEL_PRICING_USD_PER_MILLION, O as OpenAIModelPricing, h as OpenAITokenSpend, l as OpenAIUsageSpendEvent, H as OpenEnvironmentOptions, a7 as PermissionProfile, a9 as PermissionProfileListResponse, a6 as PermissionRules, u as PolicyOperator, v as PolicyOrigin, s as PolicyPredicateSource, w as PolicyRuleIR, q as PolicySource, ay as PublishEffectsResult, f as PublishToolsResult, a0 as QuotaLineItemFilter, Z as QuotaPeriod, Y as QuotaScopeType, _ as QuotaStatus, bN as RPCRequest, bQ as RPCRequestFromServer, bO as RPCResponse, ca as RecordImport, c9 as RecordImportItem, c7 as RecordImportItemStatus, c5 as RecordImportOptions, c8 as RecordImportStats, c6 as RecordImportStatus, c4 as RecordImportWriteMode, bm as RecordManualActionInput, bz as RecordMentionInput, bW as RecordObjectOptions, c1 as RecordObjectResult, bX as RecordObjectStateValue, c2 as RecordObjectsChunkInfo, c3 as RecordObjectsOptions, m as RecordOpenAIUsageSpendOptions, o as RecordOpenAIUsageSpendResult, by as RecordSearchOptions, bx as RecordSearchResult, B as RecordUserOptions, bU as RelationshipInfo, at as ResolvedEffectApprovalRequired, ar as ResolvedEffectDryRun, aq as ResolvedEffectPostCondition, as as ResolvedEffectReverse, cd as RunEnvironmentImporterOptions, a3 as Sandbox, a5 as SandboxListResponse, ap as SemanticVersionDiff, ao as SemanticVersionDiffEntry, bc as SessionArtifactApprovalOptions, b6 as SessionArtifactAutonomyPolicy, bb as SessionArtifactExecutionOptions, ba as SessionArtifactExecutionResult, b5 as SessionArtifactKind, b8 as SessionArtifactListOptions, b7 as SessionArtifactRecord, b4 as SessionArtifactStatus, b9 as SessionArtifactValidationResult, bB as SessionCollectionListOptions, bD as SessionCollectionListResult, a_ as SessionConversationMessage, bA as SessionDocumentResult, b1 as SessionFileKind, b3 as SessionFileRecord, b0 as SessionFileSource, b2 as SessionFileStatus, bs as SessionFileUploadOptions, bu as SessionHeapFieldType, bv as SessionHeapFieldValue, bw as SessionHeapVariable, bC as SessionJobListOptions, bt as SessionJobRecord, a$ as SessionTimelineEvent, X as SpendLineItemType, $ as SpendSummary, cP as StreamEvent, cR as StreamStats, cQ as StreamSubscription, F as Subject, bP as SyncMessage, g as ToolHandler, aA as ToolInfo, bR as ToolInvokeParams, bS as ToolResultParams, e as ToolSchema, aC as ToolsChangedEvent, U as User, bF as UserEnvironmentMessagePreview, bE as UserEnvironmentPrompt, bG as UserEnvironmentSessionState, bH as UserEnvironmentState, bI as UserEnvironmentStateOptions, am as Version, ae as VersionTag, ad as VersionTracking, bM as WSClientOptions, bK as WSDisconnectInfo, bL as WSReconnectErrorInfo, p as buildOpenAISpendEventId, k as calculateOpenAITokenSpend, j as getOpenAIModelPricing, n as normalizeOpenAIUsage, r as recordOpenAIUsageSpend, t as toGranularHttpBase } from './spend-DpRRCrAr.js';
 export { BuildGranularAgentSystemPromptInput, GeneratedJobCodeIssue, GranularAgentExecutionCheckpoint, GranularAgentHeapSummaryOptions, GranularAgentManualActionMemorySuggestion, GranularAgentPromptCapabilities, GranularAgentReferentFocus, GranularAgentSessionContext, GranularAgentToolInfo, GranularAgentWorkflowFocus, GranularReasoningTraceChunkResult, GranularReasoningTraceOptions, HarnessContinuationDecision, HarnessControllerBudgets, HarnessProjectionOptions, HarnessPromptLike, HarnessRenderedContinuation, HarnessRenderedPrompt, HarnessTemplate, HarnessTemplateManifest, HarnessTemplateSelectionOptions, HarnessTemplateStatus, HarnessVerifierSnapshot, HarnessVerifierSnapshotInput, ReviewGeneratedJobCodeOptions, buildContinuationInstruction, buildContinuationInstructionFromTemplate, buildGranularAgentCheckpointBlock, buildGranularAgentDomainBlock, buildGranularAgentFileBlock, buildGranularAgentHeapBlock, buildGranularAgentLoopBlock, buildGranularAgentManualActionBlock, buildGranularAgentManualActionMemorySummary, buildGranularAgentReferentBlock, buildGranularAgentRuntimeImportsBlock, buildGranularAgentSessionBlock, buildGranularAgentSystemPrompt, buildGranularAgentSystemPromptFromTemplate, buildGranularAgentToolBlock, buildGranularAgentWorkflowBlock, consumeGranularReasoningOnlyChunk, consumeGranularReasoningTraceChunk, createHarnessVerifierSnapshot, evaluateContinuation, getCurrentClosureId, getDefaultHarnessTemplateId, getExclusivePromptTarget, hasOpenPrompt, hashHarnessTemplateValue, listHarnessTemplates, projectConversationReferentFocus, projectConversationReferentSummary, projectHeapSummary, projectLoopSummary, projectSessionFileSummary, projectWorkflowFocus, projectWorkflowSummary, renderContinuationInstructionFromTemplate, renderGranularAgentSystemPromptFromTemplate, resolveHarnessTemplate, reviewGeneratedJobCode, stripGranularReasoningTrace, validateHarnessTemplateManifest } from './agent-harness.js';
 import '@automerge/automerge';
 import '@automerge/automerge/slim';

package/dist/index.js

@@ -14309,7 +14309,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),
@@ -15591,6 +15592,7 @@ var Environment = class _Environment {
           records: recordsToImport,
           batchSize: options.batchSize,
           setupRunId: options.setupRunId,
+          operationKey: options.operationKey,
           writeMode: options.writeMode
         })
       }
@@ -16395,6 +16397,107 @@ 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 tag = (tags.items || []).find(
+      (item) => item?.name === tagName
+    );
+    if (!tag) return null;
+    const query = new URLSearchParams({
+      tagId: tag.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 (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (message.includes("404") || message.includes("not found")) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  /**
+   * 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 tag = (tags.items || []).find(
+      (item) => item?.name === tagName
+    );
+    if (!tag) {
+      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: tag.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()`.
    *
@@ -16426,7 +16529,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
     );
@@ -16438,20 +16543,17 @@ var Granular = class _Granular {
     }
     return tag;
   }
-  buildManagedEnvironmentName(tag, versionId) {
-    return `__sdk__${tag}__${versionId}__pinned`;
+  buildManagedEnvironmentName(tag, versionId, resetKey) {
+    if (!resetKey) {
+      return `__sdk__${tag}__${versionId}__tracked`;
+    }
+    const safeResetKey = resetKey.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 80);
+    return `__sdk__${tag}__${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
@@ -16501,48 +16603,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: tag.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 (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("404") || message.includes("not found")) {
+          return null;
+        }
+        throw error;
+      }
+    };
+    const activate = async (environment2) => {
+      const payload = await this.request(
+        "/control/environment-activations",
+        {
+          method: "POST",
+          body: JSON.stringify({
+            environmentId: environment2.environmentId,
+            tagId: tag.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, tag.tagId) && environment.versionId === targetVersionId && (!this.isManagedEnvironmentName(environment, tagName) || this.isPinnedToVersion(environment, targetVersionId))
+        (environment2) => environment2.tagId === tag.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, tag.tagId)
-      )
+      userEnvironments.filter((environment2) => environment2.tagId === tag.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: tag.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: tag.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
     };
   }
   /**
@@ -16821,11 +16994,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}`,
@@ -16835,10 +17021,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));
@@ -16855,7 +17057,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 {