@granular-software/sdk 0.4.30 → 0.4.31

package/dist/index.js

@@ -4669,27 +4669,27 @@ var Session = class {
   }
   async publishTools(tools, revision = "1.0.0") {
     throw new Error(
-      "Environment-scoped effect publication was removed. Declare effects in the manifest and register live handlers with granular.registerEffects(environment.sandboxId, effects)."
+      "Environment-scoped effect publication was removed. Declare effects in the manifest and register live handlers with granular.ontology(environment.sandboxId).effects.registerMany(effects)."
     );
   }
   async publishEffect(effect) {
     throw new Error(
-      "Environment-scoped effect publication was removed. Use granular.registerEffect(environment.sandboxId, effect)."
+      "Environment-scoped effect publication was removed. Use granular.ontology(environment.sandboxId).effects.register(effect)."
     );
   }
   async publishEffects(effects) {
     throw new Error(
-      "Environment-scoped effect publication was removed. Use granular.registerEffects(environment.sandboxId, effects)."
+      "Environment-scoped effect publication was removed. Use granular.ontology(environment.sandboxId).effects.registerMany(effects)."
     );
   }
   async unpublishEffect(name) {
     throw new Error(
-      "Environment-scoped effect publication was removed. Use granular.unregisterEffect(environment.sandboxId, effectName)."
+      "Environment-scoped effect publication was removed. Use granular.ontology(environment.sandboxId).effects.unregister(effectName)."
     );
   }
   async unpublishAllEffects() {
     throw new Error(
-      "Environment-scoped effect publication was removed. Use granular.unregisterAllEffects(environment.sandboxId)."
+      "Environment-scoped effect publication was removed. Use granular.ontology(environment.sandboxId).effects.clear()."
     );
   }
   /**
@@ -11713,6 +11713,22 @@ function normalizeHeapSnapshot(raw) {
     updatedAt: typeof heap.updatedAt === "number" ? heap.updatedAt : Date.now()
   };
 }
+function deriveRuntimeBaseUrl(apiEndpoint) {
+  try {
+    const endpoint = new URL(apiEndpoint);
+    const graphqlSuffix = "/orchestrator/graphql";
+    if (endpoint.pathname.endsWith(graphqlSuffix)) {
+      endpoint.pathname = endpoint.pathname.slice(0, -graphqlSuffix.length);
+    } else if (endpoint.pathname.endsWith("/graphql")) {
+      endpoint.pathname = endpoint.pathname.slice(0, -"/graphql".length);
+    }
+    endpoint.search = "";
+    endpoint.hash = "";
+    return endpoint.toString().replace(/\/$/, "");
+  } catch {
+    return apiEndpoint.replace(/\/orchestrator\/graphql$/, "").replace(/\/$/, "");
+  }
+}
 function normalizeSubject(subject) {
   const granularId = subject.granularId || subject.subjectId;
   const userId = subject.userId || subject.identityId || granularId;
@@ -11752,12 +11768,13 @@ function normalizeEnvironmentData(environment) {
     tracking: environment.tracking || buildPolicy
   };
 }
-var Environment = class extends Session {
+var Environment = class {
+  granular;
   envData;
   _apiKey;
   _apiEndpoint;
-  constructor(client, envData, clientId, apiKey, apiEndpoint) {
-    super(client, clientId);
+  constructor(granular, envData, apiKey, apiEndpoint) {
+    this.granular = granular;
     this.envData = envData;
     this._apiKey = apiKey;
     this._apiEndpoint = apiEndpoint;
@@ -11798,35 +11815,126 @@ var Environment = class extends Session {
   get permissionProfileId() {
     return this.envData.permissionProfileId;
   }
+  /** The current build policy backing this environment */
+  get buildPolicy() {
+    return this.envData.buildPolicy;
+  }
+  /** The current update state relative to the followed tag */
+  get updateState() {
+    return this.envData.updateState;
+  }
+  /** Convenience flag for whether this environment trails the current tag target */
+  get isOutdated() {
+    return this.envData.updateState === "update_available";
+  }
+  /** The followed tag name when this environment is tag-tracked */
+  get tag() {
+    return this.envData.tag?.name || this.envData.buildPolicy.tagName || null;
+  }
   /** The GraphQL API endpoint URL */
   get apiEndpoint() {
     return this._apiEndpoint;
   }
+  /** Internal auth token used for control-plane and runtime fallback requests */
+  get authToken() {
+    return this._apiKey;
+  }
+  /** Base runtime URL derived from the GraphQL endpoint */
+  get runtimeBaseUrl() {
+    return this.getRuntimeBaseUrl();
+  }
+  get sessions() {
+    return {
+      list: async (options) => this.listSessions(options?.status || "active"),
+      create: async (options) => this.createSession(options),
+      connect: async (sessionId, options) => this.connectSession(sessionId, options),
+      reopen: async (sessionId, options) => this.reopenSession(sessionId, options),
+      close: async (sessionId, session) => this.closeSession(sessionId, session)
+    };
+  }
+  get data() {
+    return {
+      record: async (record) => this.recordObject(record),
+      recordMany: async (records, options) => this.recordObjects(records, options),
+      import: async (records, options) => this.enqueueRecordImport(records, options),
+      listImports: async (status) => this.listRecordImports(status),
+      getImport: async (importId) => this.getRecordImport(importId),
+      getImportSummary: async () => this.getRecordImportSummary(),
+      cancelImport: async (importId) => this.cancelRecordImport(importId),
+      getAwaitingCount: async () => this.getAwaitingRecordCount()
+    };
+  }
+  get feedback() {
+    return {
+      list: async () => this.listFeedback()
+    };
+  }
   /**
-   * Return a plain JS snapshot of the synced session heap.
-   *
-   * The heap lives in the Automerge document, so this method does not perform
-   * any extra network roundtrip.
+   * Sessionless environments do not own a live transport, so disconnecting the
+   * environment handle itself is a no-op. This keeps the public surface
+   * symmetric with `EnvironmentSession.disconnect()` and lets callers always
+   * clean up safely without tracking whether they currently hold an environment
+   * or a session.
    */
-  getHeap() {
-    const doc = this.document;
-    return normalizeHeapSnapshot(doc?.heap);
+  async disconnect() {
   }
-  getRuntimeBaseUrl() {
-    try {
-      const endpoint = new URL(this._apiEndpoint);
-      const graphqlSuffix = "/orchestrator/graphql";
-      if (endpoint.pathname.endsWith(graphqlSuffix)) {
-        endpoint.pathname = endpoint.pathname.slice(0, -graphqlSuffix.length);
-      } else if (endpoint.pathname.endsWith("/graphql")) {
-        endpoint.pathname = endpoint.pathname.slice(0, -"/graphql".length);
-      }
-      endpoint.search = "";
-      endpoint.hash = "";
-      return endpoint.toString().replace(/\/$/, "");
-    } catch {
-      return this._apiEndpoint.replace(/\/orchestrator\/graphql$/, "").replace(/\/$/, "");
+  async listSessions(status = "active") {
+    if (status === "all") {
+      const [active, closed] = await Promise.all([
+        this.granular.listOpenSessions({ environmentId: this.environmentId }),
+        this.granular.listClosedSessions({ environmentId: this.environmentId })
+      ]);
+      return [...active, ...closed].sort(
+        (left, right) => Date.parse(right.lastSeenAt) - Date.parse(left.lastSeenAt)
+      );
     }
+    return status === "closed" ? this.granular.listClosedSessions({ environmentId: this.environmentId }) : this.granular.listOpenSessions({ environmentId: this.environmentId });
+  }
+  async createSession(options) {
+    return this.granular.createSession({
+      environmentId: this.environmentId,
+      clientId: options?.clientId,
+      initialHeap: options?.initialHeap
+    });
+  }
+  async connectSession(sessionId, options) {
+    const session = await this.granular["connectSession"]({
+      sessionId,
+      clientId: options?.clientId
+    });
+    if (session.environmentId !== this.environmentId) {
+      await session.disconnect().catch(() => {
+        session.disconnectTransport();
+      });
+      throw new Error(
+        `Session ${sessionId} belongs to environment ${session.environmentId}, not ${this.environmentId}.`
+      );
+    }
+    return session;
+  }
+  async reopenSession(sessionId, options) {
+    const session = await this.granular.reopenSession(sessionId, {
+      clientId: options?.clientId
+    });
+    if (session.environmentId !== this.environmentId) {
+      await session.disconnect().catch(() => {
+        session.disconnectTransport();
+      });
+      throw new Error(
+        `Session ${sessionId} belongs to environment ${session.environmentId}, not ${this.environmentId}.`
+      );
+    }
+    return session;
+  }
+  async closeSession(sessionId, session) {
+    await this.granular.closeSession(sessionId, session);
+  }
+  async listFeedback() {
+    const response = await this.controlPlaneRequest(`/control/environments/${this.environmentId}/feedback`);
+    return Array.isArray(response.items) ? response.items : [];
+  }
+  getRuntimeBaseUrl() {
+    return deriveRuntimeBaseUrl(this._apiEndpoint);
   }
   async controlPlaneRequest(path, options = {}) {
     const runtimeBase = this.getRuntimeBaseUrl();
@@ -11847,95 +11955,6 @@ var Environment = class extends Session {
     }
     return response.json();
   }
-  /**
-   * Close the session and disconnect from the sandbox.
-   *
-   * Sends `client.goodbye` over WebSocket first, then issues an HTTP fallback
-   * to the runtime goodbye endpoint if no definitive WS-side runtime notify
-   * acknowledgement was observed.
-   */
-  async disconnect() {
-    let wsNotifiedRuntime = false;
-    try {
-      const goodbye = await this.rpc(
-        "client.goodbye",
-        {
-          timestamp: Date.now()
-        }
-      );
-      wsNotifiedRuntime = Boolean(goodbye?.ok && goodbye?.via);
-    } catch {
-      wsNotifiedRuntime = false;
-    }
-    if (!wsNotifiedRuntime) {
-      try {
-        const runtimeBase = this.getRuntimeBaseUrl();
-        await fetch(
-          `${runtimeBase}/orchestrator/runtime/environments/${this.environmentId}/session-goodbye`,
-          {
-            method: "POST",
-            headers: {
-              "Content-Type": "application/json",
-              Authorization: `Bearer ${this._apiKey}`,
-              Connection: "close"
-            },
-            body: JSON.stringify({
-              reason: "sdk_disconnect_http_fallback",
-              sessionId: this.client.currentSessionId
-            })
-          }
-        );
-      } catch {
-      }
-    }
-    this.client.disconnect();
-  }
-  /**
-   * Close only the socket transport without sending `client.goodbye`.
-   *
-   * Use this when the caller intends to immediately reattach to the same
-   * session after an unexpected disconnect.
-   */
-  disconnectTransport() {
-    this.client.disconnect();
-  }
-  // ==================== GRAPH CONTAINER READINESS ====================
-  /** The last known graph container status, updated by checkReadiness() or on heartbeat */
-  graphContainerStatus = null;
-  /**
-   * Check if the graph container is ready and warm.
-   *
-   * Sends a lightweight heartbeat RPC to the Session DO which internally
-   * pings the FalkorDB container. The response includes `graphContainerStatus`,
-   * which is stored locally and emitted as a `readiness` event.
-   *
-   * Use this method to proactively warm the graph container before any
-   * GraphQL query that requires it, or to poll the container's state in
-   * the background.
-   *
-   * @returns The current graph container status object
-   *
-   * @example
-   * ```typescript
-   * const status = await env.checkReadiness();
-   * console.log(status.status); // 'hot' | 'warming' | 'unknown'
-   *
-   * // Or listen for live updates
-   * env.on('readiness', (status) => {
-   *   console.log('Graph is now:', status.status);
-   * });
-   * ```
-   */
-  async checkReadiness() {
-    const result = await this.client.call("client.heartbeat", {});
-    const containerStatus = result?.graphContainerStatus ?? {
-      lastKeepAliveAt: Date.now(),
-      status: "unknown"
-    };
-    this.graphContainerStatus = containerStatus;
-    this.emit("readiness", containerStatus);
-    return containerStatus;
-  }
   // ==================== ID ↔ GRAPH PATH MAPPING ====================
   /**
    * Convert a class name + real-world ID into a unique graph path.
@@ -12796,36 +12815,186 @@ var Environment = class extends Session {
       }
     );
   }
-  // ==================== PUBLISH TOOLS ====================
+};
+var EnvironmentSession = class extends Session {
+  environment;
+  /** The last known graph container status, updated by checkReadiness() or on heartbeat */
+  graphContainerStatus = null;
+  constructor(client, environment, clientId) {
+    super(client, clientId);
+    this.environment = environment;
+  }
+  get environmentId() {
+    return this.environment.environmentId;
+  }
+  get sandboxId() {
+    return this.environment.sandboxId;
+  }
+  get ontologyId() {
+    return this.environment.ontologyId;
+  }
+  get subjectId() {
+    return this.environment.subjectId;
+  }
+  get envName() {
+    return this.environment.envName;
+  }
+  get versionId() {
+    return this.environment.versionId;
+  }
+  get granularId() {
+    return this.environment.granularId;
+  }
+  get permissionProfileId() {
+    return this.environment.permissionProfileId;
+  }
+  get apiEndpoint() {
+    return this.environment.apiEndpoint;
+  }
+  get data() {
+    return this.environment.data;
+  }
+  get feedback() {
+    return this.environment.feedback;
+  }
   /**
-   * Removed: environment-scoped effect publication is no longer supported.
+   * Return a plain JS snapshot of the synced session heap.
    */
-  async publishTools(tools, revision = "1.0.0") {
-    return super.publishTools(tools, revision);
+  getHeap() {
+    const doc = this.document;
+    return normalizeHeapSnapshot(doc?.heap);
+  }
+  async graphql(query, variables) {
+    return this.environment.graphql(query, variables);
+  }
+  async defineRelationship(options) {
+    return this.environment.defineRelationship(options);
+  }
+  async getRelationships(modelPath) {
+    return this.environment.getRelationships(modelPath);
+  }
+  async attach(modelPath, submodelPath, targetPath) {
+    return this.environment.attach(modelPath, submodelPath, targetPath);
+  }
+  async detach(modelPath, submodelPath, targetPath) {
+    return this.environment.detach(modelPath, submodelPath, targetPath);
+  }
+  async listRelated(modelPath, submodelPath) {
+    return this.environment.listRelated(modelPath, submodelPath);
+  }
+  async applyManifest(manifest) {
+    return this.environment.applyManifest(manifest);
+  }
+  async recordObject(options) {
+    return this.environment.recordObject(options);
+  }
+  async recordObjects(records, options) {
+    return this.environment.recordObjects(records, options);
+  }
+  async enqueueRecordImport(records, options = {}) {
+    return this.environment.enqueueRecordImport(records, options);
+  }
+  async listRecordImports(status) {
+    return this.environment.listRecordImports(status);
+  }
+  async getRecordImportSummary() {
+    return this.environment.getRecordImportSummary();
+  }
+  async getAwaitingRecordCount() {
+    return this.environment.getAwaitingRecordCount();
+  }
+  async getRecordImport(importId) {
+    return this.environment.getRecordImport(importId);
+  }
+  async cancelRecordImport(importId) {
+    return this.environment.cancelRecordImport(importId);
+  }
+  async listFeedback() {
+    return this.environment.listFeedback();
   }
   /**
-   * Removed: environment-scoped effect publication is no longer supported.
+   * Close the session and disconnect from the sandbox.
+   *
+   * Sends `client.goodbye` over WebSocket first, then issues an HTTP fallback
+   * to the runtime goodbye endpoint if no definitive WS-side runtime notify
+   * acknowledgement was observed.
    */
-  async publishEffect(effect) {
-    return super.publishEffect(effect);
+  async disconnect() {
+    let wsNotifiedRuntime = false;
+    try {
+      const goodbye = await this.rpc(
+        "client.goodbye",
+        {
+          timestamp: Date.now()
+        }
+      );
+      wsNotifiedRuntime = Boolean(goodbye?.ok && goodbye?.via);
+    } catch {
+      wsNotifiedRuntime = false;
+    }
+    if (!wsNotifiedRuntime) {
+      try {
+        await fetch(
+          `${this.environment.runtimeBaseUrl}/orchestrator/runtime/environments/${this.environmentId}/session-goodbye`,
+          {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              Authorization: `Bearer ${this.environment.authToken}`,
+              Connection: "close"
+            },
+            body: JSON.stringify({
+              reason: "sdk_disconnect_http_fallback",
+              sessionId: this.client.currentSessionId
+            })
+          }
+        );
+      } catch {
+      }
+    }
+    this.client.disconnect();
   }
   /**
-   * Removed: environment-scoped effect publication is no longer supported.
+   * Close only the socket transport without sending `client.goodbye`.
    */
-  async publishEffects(effects) {
-    return super.publishEffects(effects);
+  disconnectTransport() {
+    this.client.disconnect();
   }
   /**
-   * Removed: environment-scoped effect publication is no longer supported.
+   * Backwards-compatible alias for `disconnect()`.
    */
-  async unpublishEffect(name) {
-    return super.unpublishEffect(name);
+  async close() {
+    await this.disconnect();
   }
   /**
-   * Removed: environment-scoped effect publication is no longer supported.
+   * Check if the graph container is ready and warm.
    */
-  async unpublishAllEffects() {
-    return super.unpublishAllEffects();
+  async checkReadiness() {
+    const result = await this.client.call("client.heartbeat", {});
+    const containerStatus = result?.graphContainerStatus ?? {
+      lastKeepAliveAt: Date.now(),
+      status: "unknown"
+    };
+    this.graphContainerStatus = containerStatus;
+    this.emit("readiness", containerStatus);
+    return containerStatus;
+  }
+};
+var OntologyHandle = class {
+  granular;
+  ontologyNameOrId;
+  constructor(granular, ontologyNameOrId) {
+    this.granular = granular;
+    this.ontologyNameOrId = ontologyNameOrId;
+  }
+  get effects() {
+    return {
+      register: async (effect) => this.granular.registerEffect(this.ontologyNameOrId, effect),
+      registerMany: async (effects) => this.granular.registerEffects(this.ontologyNameOrId, effects),
+      unregister: async (name) => this.granular.unregisterEffect(this.ontologyNameOrId, name),
+      clear: async () => this.granular.unregisterAllEffects(this.ontologyNameOrId),
+      disconnect: async () => this.granular.disconnectEffects(this.ontologyNameOrId)
+    };
   }
 };
 var Granular = class _Granular {
@@ -12862,6 +13031,12 @@ var Granular = class _Granular {
     this.onReconnectError = options.onReconnectError;
     this.httpUrl = this.apiUrl.replace(/^wss:\/\//, "https://").replace(/^ws:\/\//, "http://").replace(/\/ws$/, "");
   }
+  /**
+   * Return an ontology-scoped handle for effects and other ontology-level APIs.
+   */
+  ontology(ontologyNameOrId) {
+    return new OntologyHandle(this, ontologyNameOrId);
+  }
   /**
    * Records/upserts a user and prepares them for sandbox connections
    *
@@ -12898,7 +13073,23 @@ var Granular = class _Granular {
       permissions: options.permissions || []
     });
   }
+  /**
+   * Alias for `recordUser()` with user-facing naming that matches upsert semantics.
+   */
+  async upsertUser(options) {
+    return this.recordUser(options);
+  }
   async resolveConnectUser(options) {
+    const providedIdentityCount = [
+      Boolean(options.user),
+      Boolean(options.userId),
+      Boolean(options.granularId)
+    ].filter(Boolean).length;
+    if (providedIdentityCount !== 1) {
+      throw new Error(
+        "openEnvironment() requires exactly one of userId, granularId, or a user object returned by recordUser()."
+      );
+    }
     if (options.user) {
       const user = normalizeUser(options.user);
       return {
@@ -12935,56 +13126,85 @@ var Granular = class _Granular {
       };
     }
     throw new Error(
-      "connect() requires either userId, granularId, or a user object returned by recordUser()."
+      "openEnvironment() requires either userId, granularId, or a user object returned by recordUser()."
     );
   }
   /**
-   * Connect to an ontology environment and establish a real-time session.
-   *
-   * Effects are registered at the sandbox level via `granular.registerEffect()`
-   * or `granular.registerEffects()`. Sessions pick up live availability from
-   * the sandbox registry automatically.
-   *
-   * @param options - Connection options
-   * @returns An active environment session
+   * Open or resolve an ontology environment for one user without opening a session.
    *
    * @example
    * ```typescript
-   * const environment = await granular.connect({
+   * const environment = await granular.openEnvironment({
    *   ontology: 'my-ontology',
-   *   environment: 'dev',
+   *   tag: 'dev',
    *   userId: 'user_123',
    *   permissions: ['agent'],
    * });
    *
-   * await granular.registerEffect('my-sandbox', {
-   *   name: 'greet',
-   *   description: 'Say hello',
-   *   inputSchema: { type: 'object', properties: {} },
-   *   handler: async () => 'Hello!',
+   * await environment.data.record({
+   *   className: 'customer',
+   *   id: 'acme',
+   *   fields: { name: 'Acme' },
    * });
    *
-   * // Submit job
-   * const job = await environment.submitJob(`
-   *   import { tools } from './sandbox-tools';
-   *   return await tools.greet({});
-   * `);
-   *
-   * console.log(await job.result); // 'Hello!'
+   * const session = await environment.sessions.create();
+   * const job = await session.submitJob(`return "hello";`);
+   * console.log(await job.result);
    * ```
    */
+  async openEnvironment(options) {
+    const envData = await this.resolveOpenEnvironmentData(
+      options,
+      "openEnvironment"
+    );
+    return this.bindEnvironmentHandle(envData);
+  }
+  /**
+   * Deprecated compatibility alias for `openEnvironment()`.
+   *
+   * `connect()` no longer opens a runtime session automatically.
+   */
   async connect(options) {
-    const clientId = options.clientId || `client_${Date.now()}`;
+    return this.openEnvironment({
+      ...options,
+      tag: this.resolveRequestedTag(options, "connect"),
+      permissions: options.permissions || options.user?.permissions || []
+    });
+  }
+  resolveRequestedTag(options, methodName) {
+    const tag = options.tag?.trim() || options.tagName?.trim() || options.environment?.trim();
+    if (!tag) {
+      throw new Error(`${methodName}() requires \`tag\`.`);
+    }
+    return tag;
+  }
+  buildManagedEnvironmentName(tag, versionId) {
+    return `__sdk__${tag}__${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
+    );
+  }
+  async resolveOpenEnvironmentData(options, methodName) {
     const ontology = options.ontology;
     if (!ontology) {
-      throw new Error("connect() requires `ontology`.");
+      throw new Error(`${methodName}() requires \`ontology\`.`);
     }
-    const environmentName = options.environment;
-    if (!environmentName) {
-      throw new Error("connect() requires `environment`.");
+    const tagName = options.tag?.trim();
+    if (!tagName) {
+      throw new Error(`${methodName}() requires \`tag\`.`);
     }
-    const tagName = options.tagName?.trim() || void 0;
     const user = await this.resolveConnectUser(options);
+    if (!Array.isArray(user.permissions) || user.permissions.length === 0) {
+      throw new Error(
+        `${methodName}() requires at least one permission so the SDK can ensure assignments for new users.`
+      );
+    }
     const sandbox = await this.findOrCreateSandbox(ontology);
     for (const profileName of user.permissions) {
       const profileId = await this.ensurePermissionProfile(
@@ -12997,22 +13217,49 @@ var Granular = class _Granular {
         profileId
       );
     }
-    const envData = await this.environments.create(sandbox.sandboxId, {
+    const tags = await this.request(
+      `/control/sandboxes/${sandbox.sandboxId}/tags`
+    );
+    const tag = (tags.items || []).find(
+      (candidate) => Boolean(candidate?.name === tagName)
+    );
+    if (!tag) {
+      throw new Error(
+        `Tag "${tagName}" was not found for ontology ${sandbox.sandboxId}.`
+      );
+    }
+    const targetVersionId = tag.targetVersionId || tag.targetBuildId;
+    if (!targetVersionId) {
+      throw new Error(
+        `Tag "${tagName}" does not currently point to a build/version.`
+      );
+    }
+    const allEnvironments = await this.environments.list(sandbox.sandboxId);
+    const userEnvironments = allEnvironments.filter(
+      (environment) => environment.subjectId === user.granularId
+    );
+    const currentMatches = this.sortEnvironmentsByRecency(
+      userEnvironments.filter(
+        (environment) => this.matchesTagTrackedEnvironment(environment, tagName, tag.tagId) && environment.versionId === targetVersionId
+      )
+    );
+    if (currentMatches.length > 0) {
+      return currentMatches[0];
+    }
+    const outdatedMatches = this.sortEnvironmentsByRecency(
+      userEnvironments.filter(
+        (environment) => this.matchesTagTrackedEnvironment(environment, tagName, tag.tagId)
+      )
+    );
+    if (outdatedMatches.length > 0 && options.createFreshIfOutdated !== true) {
+      return outdatedMatches[0];
+    }
+    return this.environments.create(sandbox.sandboxId, {
       subjectId: user.granularId,
-      environment: environmentName,
-      tagName,
+      environment: this.buildManagedEnvironmentName(tagName, targetVersionId),
+      tagId: tag.tagId,
       permissionProfileId: null
     });
-    await this.activateEnvironment(envData.environmentId);
-    const session = await this.request("/ws/sessions", {
-      method: "POST",
-      body: JSON.stringify({
-        environmentId: envData.environmentId,
-        clientId,
-        initialHeap: options.initialHeap
-      })
-    });
-    return this.bindWebSocketEnvironment(envData, clientId, session);
   }
   /**
    * List active (open) sessions for an environment — each session is one agent conversation thread.
@@ -13075,6 +13322,7 @@ var Granular = class _Granular {
     const clientId = options.clientId || `client_${Date.now()}`;
     await this.activateEnvironment(options.environmentId);
     const envData = await this.environments.get(options.environmentId);
+    const environment = this.bindEnvironmentHandle(envData);
     const session = await this.request("/ws/sessions", {
       method: "POST",
       body: JSON.stringify({
@@ -13083,7 +13331,7 @@ var Granular = class _Granular {
         initialHeap: options.initialHeap
       })
     });
-    return this.bindWebSocketEnvironment(envData, clientId, session);
+    return this.bindWebSocketEnvironmentSession(environment, clientId, session);
   }
   /**
    * Connect to an existing open session (same conversation thread) using a freshly minted WebSocket token.
@@ -13095,7 +13343,8 @@ var Granular = class _Granular {
       body: JSON.stringify({})
     });
     const envData = await this.environments.get(minted.environmentId);
-    return this.bindWebSocketEnvironment(envData, clientId, minted);
+    const environment = this.bindEnvironmentHandle(envData);
+    return this.bindWebSocketEnvironmentSession(environment, clientId, minted);
   }
   /**
    * Mark a session closed in the control plane. If `environment` is the connected handle for that
@@ -13127,7 +13376,11 @@ var Granular = class _Granular {
     });
     return this.connectSession({ sessionId, clientId: options?.clientId });
   }
-  async bindWebSocketEnvironment(envData, clientId, session) {
+  bindEnvironmentHandle(envData) {
+    const graphqlEndpoint = `${this.httpUrl}/orchestrator/graphql`;
+    return new Environment(this, envData, this.apiKey, graphqlEndpoint);
+  }
+  async bindWebSocketEnvironmentSession(environment, clientId, session) {
     const client = new WSClient({
       url: session.wsUrl,
       sessionId: session.sessionId,
@@ -13138,16 +13391,13 @@ var Granular = class _Granular {
       onReconnectError: this.onReconnectError
     });
     await client.connect();
-    const graphqlEndpoint = `${this.httpUrl}/orchestrator/graphql`;
-    const environment = new Environment(
+    const environmentSession = new EnvironmentSession(
       client,
-      envData,
-      clientId,
-      this.apiKey,
-      graphqlEndpoint
+      environment,
+      clientId
     );
-    await environment.hello();
-    return environment;
+    await environmentSession.hello();
+    return environmentSession;
   }
   async activateEnvironment(environmentId) {
     await this.request(`/orchestrator/runtime/environments/${environmentId}/activate`, {
@@ -15539,7 +15789,9 @@ function buildSessionTranscript(input) {
 }
 
 exports.Environment = Environment;
+exports.EnvironmentSession = EnvironmentSession;
 exports.Granular = Granular;
+exports.OntologyHandle = OntologyHandle;
 exports.Session = Session;
 exports.WSClient = WSClient;
 exports.buildContinuationInstruction = buildContinuationInstruction;