@granular-software/sdk 0.4.30 → 0.4.32

package/dist/agent-evals.js

@@ -4010,7 +4010,11 @@ var WSClient = class {
       return null;
     }
     try {
-      const payloadRaw = this.decodeBase64Url(parts[1]);
+      const payloadSegment = parts[1];
+      if (!payloadSegment) {
+        return null;
+      }
+      const payloadRaw = this.decodeBase64Url(payloadSegment);
       const payload = JSON.parse(payloadRaw);
       if (typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) {
         return null;
@@ -4674,27 +4678,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()."
     );
   }
   /**
@@ -5087,6 +5091,7 @@ import { ${allImports} } from "./sandbox-tools";
       this.eventListeners.set(event, []);
     }
     this.eventListeners.get(event).push(handler);
+    return () => this.off(event, handler);
   }
   /**
    * Unsubscribe from session events
@@ -5543,6 +5548,16 @@ var JobImplementation = class {
         handler(message);
       }
     }
+    return () => {
+      const handlers = this.eventListeners.get(event);
+      if (!handlers) {
+        return;
+      }
+      this.eventListeners.set(
+        event,
+        handlers.filter((current) => current !== handler)
+      );
+    };
   }
   replayAgentMessage(message) {
     this.captureAgentMessage(message);
@@ -11718,6 +11733,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;
@@ -11757,12 +11788,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;
@@ -11803,35 +11835,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(path2, options = {}) {
     const runtimeBase = this.getRuntimeBaseUrl();
@@ -11852,95 +11975,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.
@@ -12070,7 +12104,9 @@ var Environment = class extends Session {
       }
     );
     if (result.errors?.length) {
-      throw new Error(`defineRelationship failed: ${result.errors[0].message}`);
+      throw new Error(
+        `defineRelationship failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`
+      );
     }
     return result.data.at.define_relationship;
   }
@@ -12106,7 +12142,9 @@ var Environment = class extends Session {
       { path: modelPath }
     );
     if (result.errors?.length) {
-      throw new Error(`getRelationships failed: ${result.errors[0].message}`);
+      throw new Error(
+        `getRelationships failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`
+      );
     }
     return result.data?.model?.relationships || [];
   }
@@ -12145,7 +12183,7 @@ var Environment = class extends Session {
       { target: targetPath }
     );
     if (result.errors?.length) {
-      throw new Error(`attach failed: ${result.errors[0].message}`);
+      throw new Error(`attach failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`);
     }
   }
   /**
@@ -12180,7 +12218,7 @@ var Environment = class extends Session {
             }`
     );
     if (result.errors?.length) {
-      throw new Error(`detach failed: ${result.errors[0].message}`);
+      throw new Error(`detach failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`);
     }
   }
   /**
@@ -12207,7 +12245,9 @@ var Environment = class extends Session {
             }`
     );
     if (result.errors?.length) {
-      throw new Error(`listRelated failed: ${result.errors[0].message}`);
+      throw new Error(
+        `listRelated failed: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`
+      );
     }
     return result.data?.at?.at?.list_related || [];
   }
@@ -12300,7 +12340,7 @@ var Environment = class extends Session {
   async _runGraphql(query, label) {
     const result = await this.graphql(query);
     if (result.errors?.length) {
-      throw new Error(`${label}: ${result.errors[0].message}`);
+      throw new Error(`${label}: ${result.errors[0]?.message ?? "Unknown GraphQL error"}`);
     }
     return result.data;
   }
@@ -12645,7 +12685,11 @@ var Environment = class extends Session {
    */
   async recordObject(options) {
     const results = await this.recordObjects([options]);
-    return results[0];
+    const result = results[0];
+    if (!result) {
+      throw new Error("recordObject: no result returned for record");
+    }
+    return result;
   }
   /**
    * Batch version of `recordObject()`.
@@ -12697,7 +12741,13 @@ var Environment = class extends Session {
             );
           }
           for (let index = 0; index < items.length; index += 1) {
-            results[plan.offset + index] = items[index];
+            const item = items[index];
+            if (!item) {
+              throw new Error(
+                `recordObjects: chunk ${plan.chunkIndex + 1} returned an empty result at index ${index}`
+              );
+            }
+            results[plan.offset + index] = item;
           }
           if (onChunk) {
             const info = {
@@ -12801,36 +12851,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 {
@@ -12867,6 +13067,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
    *
@@ -12903,7 +13109,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 {
@@ -12940,56 +13162,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(
@@ -13002,22 +13253,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.
@@ -13080,6 +13358,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({
@@ -13088,7 +13367,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.
@@ -13100,7 +13379,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
@@ -13132,7 +13412,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,
@@ -13143,16 +13427,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`, {
@@ -15091,19 +15372,27 @@ function matchesPattern(text, matcher) {
 function assertMatches(label, text, includes = [], excludes = []) {
   for (const matcher of includes) {
     if (!matchesPattern(text, matcher)) {
-      throw new Error(`${label} did not match ${matcherToString(matcher)}:
-${text}`);
+      throw new Error(
+        `${label} did not match ${matcherToString(matcher)}:
+${text}`
+      );
     }
   }
   for (const matcher of excludes) {
     if (matchesPattern(text, matcher)) {
-      throw new Error(`${label} matched forbidden ${matcherToString(matcher)}:
-${text}`);
+      throw new Error(
+        `${label} matched forbidden ${matcherToString(matcher)}:
+${text}`
+      );
     }
   }
 }
 function buildArtifactDir(baseDir, suiteName = "granular-agent-evals") {
-  return path__default.default.join(baseDir || path__default.default.join(process.cwd(), "test-artifacts"), suiteName, timestampId());
+  return path__default.default.join(
+    baseDir || path__default.default.join(process.cwd(), "test-artifacts"),
+    suiteName,
+    timestampId()
+  );
 }
 function createTimestampedArtifactDirectory(options) {
   return buildArtifactDir(options?.baseDir, options?.suiteName);
@@ -15117,17 +15406,16 @@ function buildScenarioSteps(scenario) {
     return scenario.steps;
   }
   if (!scenario.request) {
-    throw new Error(`Scenario ${scenario.id} must provide either request or steps`);
+    throw new Error(
+      `Scenario ${scenario.id} must provide either request or steps`
+    );
   }
   const compatibilityStep = {
     id: scenario.id,
     request: scenario.request,
     human: scenario.human,
     expect: scenario.expect,
-    inspect: [
-      ...asArray2(scenario.inspect),
-      ...asArray2(scenario.verify)
-    ],
+    inspect: [...asArray2(scenario.inspect), ...asArray2(scenario.verify)],
     check: scenario.check,
     maxIterations: scenario.maxIterations,
     setup: {
@@ -15145,22 +15433,27 @@ function buildAssistantHistoryContent(entry) {
 ${entry.content}`);
   if (entry.jobStatus) parts.push(`[Job status]
 ${entry.jobStatus}`);
-  if (entry.jobResultPreview) parts.push(`[Job result]
+  if (entry.jobResultPreview)
+    parts.push(`[Job result]
 ${entry.jobResultPreview}`);
   if (entry.error) parts.push(`[Job error]
 ${entry.error}`);
   return parts.join("\n\n") || entry.content;
 }
 function buildHistory(entries) {
-  return entries.reduce((history, entry) => {
-    if (entry.role === "user") {
-      if (entry.content.trim()) history.push({ role: "user", content: entry.content });
+  return entries.reduce(
+    (history, entry) => {
+      if (entry.role === "user") {
+        if (entry.content.trim())
+          history.push({ role: "user", content: entry.content });
+        return history;
+      }
+      const content = buildAssistantHistoryContent(entry).trim();
+      if (content) history.push({ role: "assistant", content });
       return history;
-    }
-    const content = buildAssistantHistoryContent(entry).trim();
-    if (content) history.push({ role: "assistant", content });
-    return history;
-  }, []);
+    },
+    []
+  );
 }
 function getOpenPromptsFromDoc(liveDoc) {
   const jobsById = asRecord4(asRecord4(liveDoc?.jobs)?.byId) || {};
@@ -15169,7 +15462,8 @@ function getOpenPromptsFromDoc(liveDoc) {
     const promptRecords = asRecord4(asRecord4(job)?.prompts) || {};
     for (const raw of Object.values(promptRecords)) {
       const record = asRecord4(raw);
-      if (!record || record.status !== "open" || typeof record.promptId !== "string") continue;
+      if (!record || record.status !== "open" || typeof record.promptId !== "string")
+        continue;
       const prompt = normalizePrompt({
         promptId: record.promptId,
         kind: record.kind,
@@ -15213,7 +15507,9 @@ ${prompt.message || ""}`;
       return resolvePromptAnswer(prompt, rawAnswer);
     }
     if (fallback) return fallback({ prompt, history });
-    throw new Error(`No scripted prompt responder matched prompt ${prompt.id}: ${promptText}`);
+    throw new Error(
+      `No scripted prompt responder matched prompt ${prompt.id}: ${promptText}`
+    );
   };
 }
 function extractJsonObject(text) {
@@ -15237,13 +15533,19 @@ function modelOutputInstruction() {
   ].join("\n");
 }
 function createOpenAIChatTurnGenerator(options) {
-  const baseUrl = (options.baseUrl || "https://api.openai.com/v1").replace(/\/$/, "");
+  const baseUrl = (options.baseUrl || "https://api.openai.com/v1").replace(
+    /\/$/,
+    ""
+  );
   const model = options.model || "gpt-5-mini";
   return async (input) => {
     const messages = [
-      { role: "system", content: `${input.systemPrompt}
+      {
+        role: "system",
+        content: `${input.systemPrompt}
 
-${modelOutputInstruction()}` },
+${modelOutputInstruction()}`
+      },
       ...input.history,
       { role: "user", content: input.request }
     ];
@@ -15272,10 +15574,14 @@ ${modelOutputInstruction()}` },
             await sleep2(500 * attempt);
             continue;
           }
-          throw new Error(`OpenAI chat generation failed: ${response.status} ${errorText}`);
+          throw new Error(
+            `OpenAI chat generation failed: ${response.status} ${errorText}`
+          );
         }
         const raw = await response.json();
-        const content = asRecord4(asRecord4(raw.choices?.[0])?.message)?.content;
+        const content = asRecord4(
+          asRecord4(raw.choices?.[0])?.message
+        )?.content;
         const text = typeof content === "string" ? content : Array.isArray(content) ? content.map((part) => asRecord4(part)?.text || "").join("") : "";
         const parsed = extractJsonObject(text);
         if (!parsed) {
@@ -15293,7 +15599,9 @@ ${text}`);
         };
       } catch (error) {
         lastError = error instanceof Error ? error : new Error(String(error));
-        if (attempt < 3 && /socket connection was closed unexpectedly|ECONNRESET|network|timed out/i.test(lastError.message)) {
+        if (attempt < 3 && /socket connection was closed unexpectedly|ECONNRESET|network|timed out/i.test(
+          lastError.message
+        )) {
           await sleep2(500 * attempt);
           continue;
         }
@@ -15315,7 +15623,10 @@ async function withTimeout(promise, ms, label) {
     return await Promise.race([
       promise,
       new Promise((_, reject) => {
-        timeoutId = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+        timeoutId = setTimeout(
+          () => reject(new Error(`${label} timed out after ${ms}ms`)),
+          ms
+        );
       })
     ]);
   } finally {
@@ -15325,7 +15636,9 @@ async function withTimeout(promise, ms, label) {
 function getActionSummary(liveDoc, jobId) {
   const jobsById = asRecord4(asRecord4(liveDoc?.jobs)?.byId) || {};
   const job = asRecord4(jobsById[jobId]);
-  return Array.isArray(job?.actionSummary) ? job.actionSummary.filter((line) => typeof line === "string") : [];
+  return Array.isArray(job?.actionSummary) ? job.actionSummary.filter(
+    (line) => typeof line === "string"
+  ) : [];
 }
 function normalizeHeapSnapshot2(heap) {
   return {
@@ -15355,12 +15668,20 @@ async function waitForJobOutcome(input) {
   const startedAt = Date.now();
   while (Date.now() - startedAt < input.timeoutMs) {
     const liveDoc = cloneJson(input.environment.document);
-    const prompts = filterPromptsByBoundary(liveDoc, getOpenPromptsFromDoc(liveDoc), input.boundaryTimestamp);
+    const prompts = filterPromptsByBoundary(
+      liveDoc,
+      getOpenPromptsFromDoc(liveDoc),
+      input.boundaryTimestamp
+    );
     if (prompts.length > 0) {
       return { kind: "prompt", prompts, liveDoc, stdout, stderr };
     }
     try {
-      const result = await withTimeout(input.job.result, input.pollIntervalMs, `job ${input.job.id} tick`);
+      const result = await withTimeout(
+        input.job.result,
+        input.pollIntervalMs,
+        `job ${input.job.id} tick`
+      );
       return { kind: "completed", result, liveDoc, stdout, stderr };
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
@@ -15426,7 +15747,9 @@ function buildResultReport(result) {
     ...result.actionSummary.length ? result.actionSummary.map((line) => `- ${line}`) : ["- None"],
     "",
     "## Prompt Interactions",
-    ...result.promptInteractions.length ? result.promptInteractions.map((interaction) => `- [${interaction.type}] ${interaction.message || interaction.title} -> ${JSON.stringify(interaction.answer)}`) : ["- None"],
+    ...result.promptInteractions.length ? result.promptInteractions.map(
+      (interaction) => `- [${interaction.type}] ${interaction.message || interaction.title} -> ${JSON.stringify(interaction.answer)}`
+    ) : ["- None"],
     "",
     ...stepSection,
     "## Raw Files",
@@ -15441,7 +15764,9 @@ function buildSuiteIndex(results) {
   const lines = [
     "# Agent Eval Report Index",
     "",
-    ...results.map((result) => `- [${result.scenario.id}](./${result.scenario.id}/REPORT.md) - ${result.status}`)
+    ...results.map(
+      (result) => `- [${result.scenario.id}](./${result.scenario.id}/REPORT.md) - ${result.status}`
+    )
   ];
   return `${lines.join("\n")}
 `;
@@ -15455,7 +15780,7 @@ async function applySetup(setup, context) {
     await context.environment.recordObjects(setup.records);
   }
   if (setup.effects?.length) {
-    await context.environment.publishTools(setup.effects);
+    await context.granular.ontology(context.environment.sandboxId).effects.registerMany(setup.effects);
   }
   if (setup.run) {
     await setup.run(context);
@@ -15477,6 +15802,7 @@ async function runAgentEvalSuite(options) {
       );
       try {
         await applySetup(scenario.setup, {
+          granular: options.harness.granular,
           conversation,
           environment: conversation.environment,
           turnDir: conversation.artifactDir
@@ -15489,14 +15815,19 @@ async function runAgentEvalSuite(options) {
             conversation,
             request: step.request,
             prepare: async (ctx) => {
-              await applySetup(step.setup, ctx);
+              await applySetup(step.setup, {
+                granular: options.harness.granular,
+                ...ctx
+              });
             },
             human: step.human,
             maxIterations: step.maxIterations,
             autoAnswerPrompts: step.autoAnswerPrompts
           });
           if ("prompts" in completed) {
-            throw new Error(`Scenario ${scenario.id} step ${index + 1} paused for human input instead of completing automatically`);
+            throw new Error(
+              `Scenario ${scenario.id} step ${index + 1} paused for human input instead of completing automatically`
+            );
           }
           const inspectionResults = [];
           const stepChecks = asArray2(step.check);
@@ -15512,12 +15843,23 @@ async function runAgentEvalSuite(options) {
             actionSummary: completed.actionSummary,
             promptInteractions: completed.promptInteractions,
             result: completed.result,
-            heap: normalizeHeapSnapshot2(asRecord4(cloneJson(conversation.environment.document)?.heap)),
-            openPrompts: getOpenPromptsFromDoc(cloneJson(conversation.environment.document)),
+            heap: normalizeHeapSnapshot2(
+              asRecord4(
+                cloneJson(conversation.environment.document)?.heap
+              )
+            ),
+            openPrompts: getOpenPromptsFromDoc(
+              cloneJson(conversation.environment.document)
+            ),
             liveDoc: cloneJson(conversation.environment.document),
             inspect: async (code) => {
-              const job = await conversation.environment.submitJob(code);
-              return withTimeout(job.result, 9e4, `inspection job ${job.id}`);
+              const session = conversation.environment;
+              const job = await session.submitJob(code);
+              return withTimeout(
+                job.result,
+                9e4,
+                `inspection job ${job.id}`
+              );
             },
             assertMatches
           };
@@ -15575,7 +15917,9 @@ async function runAgentEvalSuite(options) {
         }
         const lastStep = stepResults[stepResults.length - 1];
         if (!lastStep) {
-          throw new Error(`Scenario ${scenario.id} produced no completed steps`);
+          throw new Error(
+            `Scenario ${scenario.id} produced no completed steps`
+          );
         }
         const result = {
           scenario,
@@ -15589,9 +15933,18 @@ async function runAgentEvalSuite(options) {
           steps: stepResults,
           turnDir: conversation.artifactDir
         };
-        await writeJson(path__default.default.join(conversation.artifactDir, "result.json"), result);
-        await writeJson(path__default.default.join(conversation.artifactDir, "report.json"), result);
-        await promises.writeFile(path__default.default.join(conversation.artifactDir, "REPORT.md"), buildResultReport(result));
+        await writeJson(
+          path__default.default.join(conversation.artifactDir, "result.json"),
+          result
+        );
+        await writeJson(
+          path__default.default.join(conversation.artifactDir, "report.json"),
+          result
+        );
+        await promises.writeFile(
+          path__default.default.join(conversation.artifactDir, "REPORT.md"),
+          buildResultReport(result)
+        );
         finalResult = result;
       } catch (error) {
         const failureMessage = error instanceof Error ? error.message : String(error);
@@ -15613,7 +15966,10 @@ async function runAgentEvalSuite(options) {
         await ensureDir(failed.turnDir);
         await writeJson(path__default.default.join(failed.turnDir, "result.json"), failed);
         await writeJson(path__default.default.join(failed.turnDir, "report.json"), failed);
-        await promises.writeFile(path__default.default.join(failed.turnDir, "REPORT.md"), buildResultReport(failed));
+        await promises.writeFile(
+          path__default.default.join(failed.turnDir, "REPORT.md"),
+          buildResultReport(failed)
+        );
         finalResult = failed;
       } finally {
         await options.harness.closeConversation(conversation);
@@ -15634,12 +15990,21 @@ async function runAgentEvalSuite(options) {
     }
     results.push(finalResult);
   }
-  await writeJson(path__default.default.join(options.harness.artifactDir, "summary.json"), results);
-  await promises.writeFile(path__default.default.join(options.harness.artifactDir, "REPORT_INDEX.md"), buildSuiteIndex(results));
+  await writeJson(
+    path__default.default.join(options.harness.artifactDir, "summary.json"),
+    results
+  );
+  await promises.writeFile(
+    path__default.default.join(options.harness.artifactDir, "REPORT_INDEX.md"),
+    buildSuiteIndex(results)
+  );
   return { artifactDir: options.harness.artifactDir, results };
 }
 function createAgentEvalHarness(options) {
-  const artifactDir = buildArtifactDir(options.artifactBaseDir, options.suiteName);
+  const artifactDir = buildArtifactDir(
+    options.artifactBaseDir,
+    options.suiteName
+  );
   const controllerBudgets = {
     ...DEFAULT_CONTROLLER_BUDGETS,
     ...options.controllerBudgets || {}
@@ -15651,7 +16016,9 @@ function createAgentEvalHarness(options) {
     await ensureDir(artifactDir);
     const clientId = `${slugify(label)}-${Date.now()}`;
     if (!options.openEnvironment && !options.environmentId) {
-      throw new Error("createAgentEvalHarness requires either environmentId or openEnvironment");
+      throw new Error(
+        "createAgentEvalHarness requires either environmentId or openEnvironment"
+      );
     }
     const environment = options.openEnvironment ? await options.openEnvironment({ label, clientId }) : await options.granular.createSession({
       environmentId: options.environmentId,
@@ -15675,12 +16042,15 @@ function createAgentEvalHarness(options) {
   }
   async function closeConversation(conversation) {
     try {
-      await options.granular.closeSession(conversation.environment.sessionId, conversation.environment);
+      await options.granular.closeSession(
+        conversation.environment.sessionId,
+        conversation.environment
+      );
     } catch {
     }
   }
-  async function runCheckJob(code, environment) {
-    const job = await environment.submitJob(code);
+  async function runCheckJob(code, session) {
+    const job = await session.submitJob(code);
     return withTimeout(job.result, jobTimeoutMs, `check job ${job.id}`);
   }
   function buildCheckContext(conversation, completed, turnDir) {
@@ -15725,8 +16095,12 @@ function createAgentEvalHarness(options) {
   async function resumePendingTurn(pending, responder) {
     const prompt = pending.prompts[0];
     if (!prompt) throw new Error("Pending turn has no prompts to answer");
-    const answer = await responder({ prompt, history: pending.promptInteractions });
-    await pending.conversation.environment.answerPrompt(prompt.id, answer);
+    const answer = await responder({
+      prompt,
+      history: pending.promptInteractions
+    });
+    const session = pending.conversation.environment;
+    await session.answerPrompt(prompt.id, answer);
     pending.promptInteractions.push({
       promptId: prompt.id,
       type: prompt.type,
@@ -15750,7 +16124,9 @@ function createAgentEvalHarness(options) {
       };
     }
     await sleep2(350);
-    const liveDoc = cloneJson(pending.conversation.environment.document);
+    const liveDoc = cloneJson(
+      pending.conversation.environment.document
+    );
     const presentation = resolveJobPresentation({
       jobId: pending.job.id,
       result: resumed.result,
@@ -15795,25 +16171,40 @@ function createAgentEvalHarness(options) {
       await conversation.environment.recordObjects(input.prepareRecords);
     }
     if (input.prepareTools?.length) {
-      await conversation.environment.publishTools(input.prepareTools);
+      await options.granular.ontology(conversation.environment.sandboxId).effects.registerMany(input.prepareTools);
     }
     if (input.prepare) {
-      await input.prepare({ conversation, environment: conversation.environment, turnDir });
+      await input.prepare({
+        conversation,
+        environment: conversation.environment,
+        turnDir
+      });
     }
     const boundaryTimestamp = Date.now();
     conversation.history.push({ role: "user", content: input.request });
-    await writeJson(path__default.default.join(turnDir, "request.json"), { request: input.request, boundaryTimestamp });
+    await writeJson(path__default.default.join(turnDir, "request.json"), {
+      request: input.request,
+      boundaryTimestamp
+    });
     let iteration = 0;
     let noProgressCount = 0;
     let previousSnapshot = null;
     let latestCheckpoint = null;
     const maxIterations = input.maxIterations || controllerBudgets.maxIterations;
     const autoAnswerPrompts = input.autoAnswerPrompts ?? true;
-    const baselineClosureId = getCurrentClosureId(cloneJson(conversation.environment.document));
+    const baselineClosureId = getCurrentClosureId(
+      cloneJson(conversation.environment.document)
+    );
     while (iteration < maxIterations) {
       const liveDoc = cloneJson(conversation.environment.document);
-      const pendingPrompts = filterPromptsByBoundary(liveDoc, getOpenPromptsFromDoc(liveDoc), boundaryTimestamp);
-      const workflowFocus = projectWorkflowFocus(liveDoc, pendingPrompts, { boundaryTimestamp });
+      const pendingPrompts = filterPromptsByBoundary(
+        liveDoc,
+        getOpenPromptsFromDoc(liveDoc),
+        boundaryTimestamp
+      );
+      const workflowFocus = projectWorkflowFocus(liveDoc, pendingPrompts, {
+        boundaryTimestamp
+      });
       const systemPrompt = buildGranularAgentSystemPrompt({
         domainDocumentation: await conversation.environment.getDomainDocumentation(),
         sessionContext: {
@@ -15824,8 +16215,12 @@ function createAgentEvalHarness(options) {
         heapSummary: projectHeapSummary(liveDoc, {
           focus: workflowFocus
         }),
-        loopSummary: projectLoopSummary(liveDoc, pendingPrompts, { boundaryTimestamp }),
-        workflowSummary: projectWorkflowSummary(liveDoc, pendingPrompts, { boundaryTimestamp }),
+        loopSummary: projectLoopSummary(liveDoc, pendingPrompts, {
+          boundaryTimestamp
+        }),
+        workflowSummary: projectWorkflowSummary(liveDoc, pendingPrompts, {
+          boundaryTimestamp
+        }),
         tools: conversation.environment.getEffects().map((tool) => ({
           name: tool.name,
           description: tool.description,
@@ -15835,14 +16230,23 @@ function createAgentEvalHarness(options) {
         })),
         checkpoint: latestCheckpoint
       });
-      const request = iteration === 0 ? input.request : buildContinuationInstruction(buildContinuationPreview(latestCheckpoint, noProgressCount));
-      const generation = await withTimeout(generateTurnWithRepair(options.generator, {
-        systemPrompt,
-        history: buildHistory(conversation.history),
-        request,
-        attempt: 1
-      }), chatTimeoutMs, `chat generation for ${conversation.label} iteration ${iteration + 1}`);
-      await writeJson(path__default.default.join(turnDir, `iteration-${iteration + 1}-generation.json`), generation);
+      const request = iteration === 0 ? input.request : buildContinuationInstruction(
+        buildContinuationPreview(latestCheckpoint, noProgressCount)
+      );
+      const generation = await withTimeout(
+        generateTurnWithRepair(options.generator, {
+          systemPrompt,
+          history: buildHistory(conversation.history),
+          request,
+          attempt: 1
+        }),
+        chatTimeoutMs,
+        `chat generation for ${conversation.label} iteration ${iteration + 1}`
+      );
+      await writeJson(
+        path__default.default.join(turnDir, `iteration-${iteration + 1}-generation.json`),
+        generation
+      );
       if (!generation.code) {
         const responseText2 = generation.reply?.trim() || "Done.";
         conversation.history.push({ role: "assistant", content: responseText2 });
@@ -15858,12 +16262,18 @@ function createAgentEvalHarness(options) {
           result: generation.reply?.trim() || responseText2
         };
         if (input.verification) {
-          completed.verification = await runInspection(conversation, input.verification, completed, turnDir);
+          completed.verification = await runInspection(
+            conversation,
+            input.verification,
+            completed,
+            turnDir
+          );
         }
         await writeJson(path__default.default.join(turnDir, "result.json"), completed);
         return completed;
       }
-      const job = await conversation.environment.submitJob(generation.code);
+      const session = conversation.environment;
+      const job = await session.submitJob(generation.code);
       const outcome = await waitForJobOutcome({
         environment: conversation.environment,
         job,
@@ -15888,7 +16298,9 @@ function createAgentEvalHarness(options) {
           };
         }
         if (!input.human) {
-          throw new Error("This turn reached a human prompt but no responder was provided");
+          throw new Error(
+            "This turn reached a human prompt but no responder was provided"
+          );
         }
         let pending = {
           conversation,
@@ -15910,16 +16322,25 @@ function createAgentEvalHarness(options) {
             continue;
           }
           if (input.verification) {
-            resumed.verification = await runInspection(conversation, input.verification, resumed, turnDir);
+            resumed.verification = await runInspection(
+              conversation,
+              input.verification,
+              resumed,
+              turnDir
+            );
           }
           return resumed;
         }
       }
       if (outcome.kind !== "completed") {
-        throw new Error("Unexpected non-completed outcome after prompt handling");
+        throw new Error(
+          "Unexpected non-completed outcome after prompt handling"
+        );
       }
       await sleep2(350);
-      const settledLiveDoc = cloneJson(conversation.environment.document);
+      const settledLiveDoc = cloneJson(
+        conversation.environment.document
+      );
       const sessionHeap = normalizeHeapSnapshot2(asRecord4(settledLiveDoc?.heap));
       const presentation = resolveJobPresentation({
         jobId: job.id,
@@ -15940,7 +16361,11 @@ function createAgentEvalHarness(options) {
         baselineClosureId,
         currentClosureId: getCurrentClosureId(settledLiveDoc),
         liveDoc: settledLiveDoc,
-        pendingPrompts: filterPromptsByBoundary(settledLiveDoc, getOpenPromptsFromDoc(settledLiveDoc), boundaryTimestamp),
+        pendingPrompts: filterPromptsByBoundary(
+          settledLiveDoc,
+          getOpenPromptsFromDoc(settledLiveDoc),
+          boundaryTimestamp
+        ),
         projectionOptions: { boundaryTimestamp },
         latestResponseText: responseText,
         previousSnapshot,
@@ -15965,12 +16390,15 @@ function createAgentEvalHarness(options) {
         jobStatus: "succeeded",
         jobResultPreview: JSON.stringify(outcome.result, null, 2)
       });
-      await writeJson(path__default.default.join(turnDir, `iteration-${iteration + 1}-result.json`), {
-        responseText,
-        continuation,
-        actionSummary: latestCheckpoint.latestActionSummary,
-        result: outcome.result
-      });
+      await writeJson(
+        path__default.default.join(turnDir, `iteration-${iteration + 1}-result.json`),
+        {
+          responseText,
+          continuation,
+          actionSummary: latestCheckpoint.latestActionSummary,
+          result: outcome.result
+        }
+      );
       if (!continuation.shouldContinue) {
         const completed = {
           conversation,
@@ -15985,17 +16413,25 @@ function createAgentEvalHarness(options) {
           result: outcome.result
         };
         if (input.verification) {
-          completed.verification = await runInspection(conversation, input.verification, completed, turnDir);
+          completed.verification = await runInspection(
+            conversation,
+            input.verification,
+            completed,
+            turnDir
+          );
         }
         await writeJson(path__default.default.join(turnDir, "result.json"), completed);
         return completed;
       }
       iteration += 1;
     }
-    throw new Error(`Turn exceeded iteration budget (${maxIterations}) for ${conversation.label}`);
+    throw new Error(
+      `Turn exceeded iteration budget (${maxIterations}) for ${conversation.label}`
+    );
   }
   return {
     artifactDir,
+    granular: options.granular,
     openConversation,
     closeConversation,
     runTurn,
@@ -16031,12 +16467,11 @@ function createAgentTester(options) {
       }
       if ("connect" in options.target && !connectSeeded) {
         connectSeeded = true;
-        const environment = await granular.connect({
-          ...options.target.connect,
-          clientId
+        const environment = await granular.openEnvironment({
+          ...options.target.connect
         });
         resolvedEnvironmentId = environment.environmentId;
-        return environment;
+        return environment.sessions.create({ clientId });
       }
       if ("createEnvironment" in options.target && !resolvedEnvironmentId) {
         const envData = await granular.environments.create(