@granular-software/sdk 0.4.30 → 0.4.32

package/dist/cli/index.js

@@ -6597,9 +6597,9 @@ async function main() {
   });
 
   // Connect as one app user so the SDK can create an environment for the seed run.
-  const env = await granular.connect({
+  const env = await granular.openEnvironment({
     ontology: SANDBOX_ID,
-    environment: 'dev',
+    tag: 'dev',
     userId: '${template.seedUser.userId}',
     name: '${template.seedUser.name}',
     email: '${template.seedUser.email}',
@@ -6621,7 +6621,7 @@ async function main() {
     const updatedCount = results.length - createdCount;
     console.log(\`[Seed] Created \${createdCount} records, updated \${updatedCount} records.\`);
   } finally {
-    await env.disconnect();
+    await session.disconnect();
   }
 
   console.log(\`Seeded \${records.length} records into \${SANDBOX_ID}\`);
@@ -6670,7 +6670,7 @@ async function main() {
     apiUrl: process.env.GRANULAR_API_URL ?? API_URL,
   });
 
-  await granular.registerEffects(SANDBOX_ID, [
+  await granular.ontology(SANDBOX_ID).effects.registerMany([
 ${registrations}
   ]);
 
@@ -6688,7 +6688,7 @@ ${registrations}
       shuttingDown = true;
       clearInterval(keepAliveTimer);
       console.log(\`Shutting down after \${signal}...\`);
-      await granular.disconnectEffects(SANDBOX_ID);
+      await granular.ontology(SANDBOX_ID).effects.disconnect();
       resolve();
       process.exit(0);
     };
@@ -6738,9 +6738,9 @@ test('granular connect + submitJob smoke test', {
     apiUrl: process.env.GRANULAR_API_URL ?? rc.apiUrl ?? DEFAULT_API_URL,
   });
 
-  const environment = await granular.connect({
+  const environment = await granular.openEnvironment({
     ontology: rc.sandboxId,
-    environment: 'dev',
+    tag: 'dev',
     userId: '${template.seedUser.userId}',
     name: '${template.seedUser.name}',
     email: '${template.seedUser.email}',
@@ -6751,7 +6751,8 @@ test('granular connect + submitJob smoke test', {
     assert.ok(environment.environmentId);
     assert.ok(environment.sessionId);
 
-    const job = await environment.submitJob(\`
+    const session = await environment.sessions.create();
+const job = await session.submitJob(\`
 return {
   ok: true,
   template: '${template.id}',
@@ -6762,7 +6763,7 @@ return {
     assert.equal(result.ok, true);
     assert.equal(result.template, '${template.id}');
   } finally {
-    await environment.disconnect();
+    await session.disconnect();
   }
 });
 `;
@@ -8960,7 +8961,7 @@ function manifestGuideGranularProductSection() {
 2. **Build** that declaration from \`granular.json\` so the service compiles types and tooling for a **sandbox** (a workspace identified by \`sbx_\u2026\`).
 3. **Store** **records** (instances of your classes) and **run jobs** (code executed in Granular\u2019s **sandbox runtime**) that call generated helpers and effects.
 
-**Split of responsibility:** Data and domain rules live in Granular; **secrets, payment providers, email, and arbitrary HTTP** stay in **your** server via **effect handlers** you register with \`registerEffects\`.
+**Split of responsibility:** Data and domain rules live in Granular; **secrets, payment providers, email, and arbitrary HTTP** stay in **your** server via **effect handlers** you register with \`granular.ontology(sandboxId).effects.registerMany\`.
 
 ---
 
@@ -8985,10 +8986,10 @@ The rest of this guide assumes these terms.
 | **Manifest** | \`granular.json\` (definition under \`manifest\`). **Source** in the repo until you create a new ontology **version** from it. |
 | **Version** | Immutable ontology state derived from one manifest revision. Tags like \`dev\` and \`prod\` point to versions. |
 | **Build run** | The CI-style compilation process. \`granular build\` creates or reuses the ontology version, then runs a build for it. |
-| **Environment** | Return value of \`granular.connect({ ontology, environment, \u2026 })\`. It is your **server-side** handle for \`recordObject\`, \`submitJob\`, \`graphql\`, etc., bound to one ontology environment slot. |
-| **Session** | SDK base type; \`Environment\` **extends** \`Session\`. Job/prompt APIs live on \`Session\`; you still use the **\`Environment\`** instance from \`connect()\` in normal apps. |
-| **Job** | Code string passed to \`environment.submitJob(code)\`. Runs in Granular\u2019s **sandbox runtime** with access to \`./sandbox-tools\` (generated classes + effect entrypoints). |
-| **Effect** | Declared with \`withEffect\`; **handler** registered with \`registerEffects\` in **your** process. Jobs invoke effects; handlers do IO outside Granular. |
+| **Environment** | Return value of \`granular.openEnvironment({ ontology, tag, userId, \u2026 })\`. It is your **server-side** handle for \`recordObject\`, \`recordObjects\`, \`graphql\`, and \`sessions.create()\`. |
+| **Session** | Live runtime connection opened from an environment with \`environment.sessions.create()\` or \`environment.sessions.connect()\`. Job, prompt, and streaming APIs live here. |
+| **Job** | Code string passed to \`session.submitJob(code)\`. Runs in Granular\u2019s **sandbox runtime** with access to \`./sandbox-tools\` (generated classes + effect entrypoints). |
+| **Effect** | Declared with \`withEffect\`; **handler** registered in **your** process with \`granular.ontology(sandboxId).effects.registerMany(...)\`. Jobs invoke effects; handlers do IO outside Granular. |
 | **Class** | Entity **kind** in the domain (e.g. \`book\`) with \`has\` fields in the manifest. |
 | **Record / object** | One **instance**: \`className\`, \`id\`, \`fields\`, \`relationships\`. Use \`recordObject\` for one upsert, \`recordObjects\` for several immediate upserts, and record-import APIs for async bulk loads. |
 | **Relationship** | Declared link between two classes; defines **property names** and cardinality. Keys appear in \`recordObject({ relationships })\`. |
@@ -9007,10 +9008,10 @@ function manifestGuideEndToEndSection() {
 |------|--------|---------|
 | 1 | Edit \`granular.json\` (\`manifest\` \u2192 \`volumes\` \u2192 \`operations\`) | Domain **source** in the repo |
 | 2 | \`granular build\` | Manifest **uploaded**; ontology version created or reused; build run compiles it; errors surface here |
-| 3 | (Optional) Run your **effects host** \u2014 e.g. \`npx tsx granular-effects.ts\` \u2014 calling \`registerEffects(sandboxId, \u2026)\` | Effect **handlers** attached in **your** process |
-| 4 | \`new Granular({ apiKey })\` then \`connect({ ontology, environment, userId, permissions })\` | **\`Environment\`** for that ontology environment slot |
+| 3 | (Optional) Run your **effects host** \u2014 e.g. \`npx tsx granular-effects.ts\` \u2014 calling \`granular.ontology(sandboxId).effects.registerMany(...)\` | Effect **handlers** attached in **your** process |
+| 4 | \`new Granular({ apiKey })\` then \`openEnvironment({ ontology, tag, userId, permissions })\` | **\`Environment\`** handle for that ontology/user pair |
 | 5 | \`recordObject\` / \`recordObjects\` | **Records** stored with correct fields and relationship keys. Use \`recordObject\` for one targeted write. Use \`recordObjects\` for one synchronous multi-record write with chunking (default 100 rows/request), retries, and optional \`onChunkComplete\` / \`concurrency\` progress. For async bulk loads use \`enqueueRecordImport\` + import status APIs. |
-| 6 | \`submitJob(\`\u2026\`)\` with imports from \`./sandbox-tools\` | **Jobs** run; may call **effects** \u2192 your handlers execute and return results |
+| 6 | \`const session = await environment.sessions.create();\` then \`session.submitJob(\`\u2026\`)\` | **Jobs** run; may call **effects** \u2192 your handlers execute and return results |
 
 **Accuracy tip:** After changing the manifest, always **re-build** before assuming generated types, \`./sandbox-tools\` names, or effect signatures match the file on disk.`;
 }
@@ -9024,9 +9025,9 @@ function sandboxDocMainConceptsSection() {
 | **Manifest** | \`granular.json\` \u2014 **source**; edit here, then \`granular build\`. |
 | **Version** | Immutable ontology state created from one manifest revision. |
 | **Build run** | Compilation run that validates and materializes a version. |
-| **Environment** | \`connect()\` result \u2014 **record**, **submitJob**, **graphql** for this sandbox. |
-| **Session** | Base type; \`Environment\` extends it (job APIs). |
-| **Job** | \`submitJob\` code using \`./sandbox-tools\`. |
+| **Environment** | \`openEnvironment()\` result \u2014 **record**, **recordObjects**, **graphql**, and **session lifecycle** for this sandbox. |
+| **Session** | Live runtime connection created from an environment; job and prompt APIs live here. |
+| **Job** | \`session.submitJob(...)\` code using \`./sandbox-tools\`. |
 | **Effect** | Declared in manifest; **handler** in your process. |
 
 **Full product + manifest how-to:** [docs/granular-manifest.md](docs/granular-manifest.md).`;
@@ -14860,7 +14861,7 @@ function generateManifestAgentGuide(options) {
   );
   return `# Granular manifest guide (for coding agents)
 
-This guide is for **coding agents** who may have **no prior context on Granular**. It explains the product, core terms, how to **author** \`granular.json\`, **build** the domain, and use the SDK (\`connect\` \u2192 **environment**, \`recordObject\`, \`submitJob\`, **effects**). For **this repository\u2019s** exact class names, relationship keys, and effect payloads only, see [GRANULAR_SANDBOX.md](../GRANULAR_SANDBOX.md).
+This guide is for **coding agents** who may have **no prior context on Granular**. It explains the product, core terms, how to **author** \`granular.json\`, **build** the domain, and use the SDK (\`openEnvironment\` \u2192 **environment**, \`environment.sessions.create()\` \u2192 **session**, \`recordObject\`, **effects**). For **this repository\u2019s** exact class names, relationship keys, and effect payloads only, see [GRANULAR_SANDBOX.md](../GRANULAR_SANDBOX.md).
 
 **Precedence:** User instructions in chat override this file. When in doubt, read \`granular.json\` and [AGENTS.md](../AGENTS.md).
 
@@ -15118,14 +15119,14 @@ Example:
 
 | Field | Meaning |
 |-------|---------|
-| \`name\` | Must match the \`name\` in \`registerEffects\`. |
+| \`name\` | Must match the handler name you register from your effect host. |
 | \`attachedClass\` | Omit for **global** effects. Set for class-bound effects. |
 | \`isStatic\` | \`true\` \u2192 static method; \`false\` or omit \u2192 **instance** method (handler receives the object **id** first). |
 | \`inputSchema\` / \`outputSchema\` | JSON Schema; used for codegen and validation. |
 
-**Lifecycle:** declare in manifest \u2192 \`granular build\` creates or reuses a version and runs the build \u2192 implement handlers \u2192 \`granular.registerEffects(sandboxId, [...])\` \u2192 jobs call generated methods \u2192 your handler runs and returns the result to the job.
+**Lifecycle:** declare in manifest \u2192 \`granular build\` creates or reuses a version and runs the build \u2192 implement handlers \u2192 \`granular.ontology(sandboxId).effects.registerMany([...])\` \u2192 jobs call generated methods \u2192 your handler runs and returns the result to the job.
 
-**Permissions:** \`connect({ permissions: [...] })\` assigns profiles (e.g. \`default\`) that can allow or deny which effects a user may call.
+**Permissions:** \`openEnvironment({ permissions: [...] })\` assigns profiles (e.g. \`default\`) that can allow or deny which effects a user may call.
 
 ### Effect metamodels
 
@@ -15191,30 +15192,38 @@ ${effectMetamodelTable}
 | API | Purpose |
 |-----|---------|
 | \`new Granular({ apiKey, apiUrl?, endpointMode?, token?, tokenProvider?, \u2026 })\` | Auth. Env: \`GRANULAR_API_KEY\`, \`GRANULAR_API_URL\`, \`GRANULAR_ENDPOINT_MODE\`. |
-| \`recordUser({ userId, name?, email?, permissions? })\` | Upsert user for later \`connect\`. |
-| \`connect({ ontology, environment, tagName?, userId?, granularId?, user?, permissions?, clientId?, initialHeap? })\` | Opens a session \u2192 **\`Environment\`**. \`tagName\` is an advanced override. |
-| \`registerEffects(sandboxId, effects)\` / \`registerEffect\` | Register handlers for manifest \`withEffect\` declarations. |
-| \`unregisterEffect\` / \`unregisterAllEffects\` / \`disconnectEffects\` | Stop effect handlers for a sandbox. |
+| \`recordUser({ userId, name?, email?, permissions? })\` | Upsert user for later \`openEnvironment\`. |
+| \`openEnvironment({ ontology, tag?, userId?, granularId?, user?, permissions, createFreshIfOutdated?, ... })\` | Resolves or creates an **\`Environment\`** handle. |
+| \`granular.ontology(sandboxId).effects.registerMany(effects)\` / \`.register(effect)\` | Register handlers for manifest \`withEffect\` declarations. |
+| \`granular.ontology(sandboxId).effects.unregister(name)\` / \`.clear()\` / \`.disconnect()\` | Stop effect handlers for a sandbox. |
 | \`granular.sandboxes\` | \`.list()\`, \`.get\`, \`.create\`, \`.update\`, \`.delete\` |
 | \`granular.permissionProfiles\` | Permission profiles per sandbox. |
-| \`granular.environments\` | List/create/delete environments (usually use \`connect()\`). |
+| \`granular.environments\` | List/create/delete environments (advanced control-plane API). |
 | \`granular.subjects\` | Subjects / assignments (see typings). |
 
-### \`Environment\` (connected session)
+### \`Environment\` (sessionless environment handle)
 
 | API | Purpose |
 |-----|---------|
-| \`environmentId\`, \`sandboxId\`, \`apiEndpoint\`, \u2026 | Session context. |
+| \`environmentId\`, \`sandboxId\`, \`apiEndpoint\`, \u2026 | Environment context. |
 | \`applyManifest(manifest)\` | Apply manifest operations at runtime (alternative to CLI build for dynamic ontologies). |
 | \`recordObject\` / \`recordObjects\` | Upsert instances and relationships. Use \`recordObject\` for one object or a targeted patch. Use \`recordObjects\` for synchronous multi-record ingestion with chunked HTTP writes (default 100 rows/chunk), retries, and optional \`onChunkComplete\`, \`batchSize\`, \`concurrency\`. |
 | \`enqueueRecordImport\`, \`listRecordImports\`, \`getRecordImport\`, \`getRecordImportSummary\`, \u2026 | **Async** bulk import (worker queue + aggregate progress). Prefer when loads are huge, returning an \`importId\` is enough up front, and background processing is acceptable. |
 | \`graphql(query, variables?)\` | **GraphQL** \u2014 see dedicated subsection below. |
 | \`defineRelationship\`, \`getRelationships\`, \`attach\`, \`detach\`, \`listRelated\` | Imperative relationship operations (same ideas as manifest \`defineRelationship\`). |
+| \`sessions.list()\`, \`sessions.create()\`, \`sessions.connect()\`, \`sessions.reopen()\`, \`sessions.close()\` | Session lifecycle for this environment. |
+
+### \`Session\` (live runtime connection)
+
+| API | Purpose |
+|-----|---------|
 | \`submitJob(code)\` | Run code in the sandbox; import from \`./sandbox-tools\`. |
+| \`answerPrompt(...)\`, \`appendMessage(...)\` | Human-in-the-loop and conversation APIs. |
 | \`getDomain()\`, \`getDomainTypes()\`, \`getDomainDocs()\`, \`getDomainDocumentation()\` | Domain summary and generated TypeScript / docs. |
-| \`getEffects()\` / \`getTools()\`, \`onEffectsChanged()\` | Effect catalog and updates. |
-| \`checkReadiness()\`, \`on('readiness', \u2026)\` | Environment readiness. |
+| \`getEffects()\` / \`getTools()\`, \`session.on("effects:changed", ...)\` | Effect catalog and live updates. |
+| \`checkReadiness()\`, \`on('readiness', ...)\` | Runtime readiness. |
 | \`getHeap()\` | Session state snapshot (advanced). |
+| \`disconnect()\` | Close the live runtime session. |
 | \`rpc(method, params)\` | Low-level session RPC (advanced). |
 | \`disconnect()\` | End the session. |
 
@@ -15414,9 +15423,9 @@ function generateSandboxAgentDoc(manifest, meta) {
   lines.push(`  // apiUrl: process.env.GRANULAR_API_URL, // optional`);
   lines.push(`});`);
   lines.push("");
-  lines.push(`const env = await granular.connect({`);
+  lines.push(`const env = await granular.openEnvironment({`);
   lines.push(`  ontology: '${meta.sandboxId}',`);
-  lines.push(`  environment: 'dev',`);
+  lines.push(`  tag: 'dev',`);
   lines.push(`  userId: 'your_app_user_id',`);
   lines.push(`  permissions: ['default'],`);
   lines.push(`});`);
@@ -15535,7 +15544,7 @@ function generateSandboxAgentDoc(manifest, meta) {
     "1. **Build** the manifest so the domain package includes the effect (`granular build`)."
   );
   lines.push(
-    "2. **Register** a handler whose `name` (and `className` / `static` when applicable) matches \u2014 use `granular.registerEffects('" + meta.sandboxId + "', [...])` in your host process (see `granular-effects.ts` in starter projects)."
+    "2. **Register** a handler whose `name` (and `className` / `static` when applicable) matches \u2014 use `granular.ontology('" + meta.sandboxId + "').effects.registerMany([...])` in your host process (see `granular-effects.ts` in starter projects)."
   );
   lines.push(
     "3. **Invoke** from sandbox code via `./sandbox-tools` inside `submitJob`; the handler you registered runs in your process and the result returns to the job."
@@ -15603,7 +15612,8 @@ function generateSandboxAgentDoc(manifest, meta) {
   const globalEffects = effects2.filter((e) => !e.attachedClass);
   const firstGlobal = globalEffects[0]?.name;
   lines.push("```typescript");
-  lines.push(`const job = await env.submitJob(\``);
+  lines.push(`const session = await env.sessions.create();
+const job = await session.submitJob(\``);
   const importList = [...pascalImports, ...effectNames].filter(
     (v, i, a) => a.indexOf(v) === i
   );
@@ -15682,7 +15692,7 @@ function generateSandboxAgentDoc(manifest, meta) {
     "| Domain | `getDomain`, `getDomainTypes`, `getDomainDocumentation` |"
   );
   lines.push(
-    "| Effects | `registerEffects`, `getEffects`, `onEffectsChanged` |"
+    '| Effects | `granular.ontology(...).effects.registerMany`, `session.getEffects()`, `session.on("effects:changed", ...)` |'
   );
   lines.push("| Ops | `checkReadiness`, `getHeap`, `rpc` |");
   lines.push("");
@@ -17769,7 +17779,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;
@@ -18433,27 +18447,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(effects2) {
     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()."
     );
   }
   /**
@@ -18846,6 +18860,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
@@ -19302,6 +19317,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);
@@ -19634,6 +19659,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;
@@ -19673,12 +19714,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;
@@ -19719,35 +19761,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, session2) => this.closeSession(sessionId, session2)
+    };
+  }
+  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 session2 = await this.granular["connectSession"]({
+      sessionId,
+      clientId: options?.clientId
+    });
+    if (session2.environmentId !== this.environmentId) {
+      await session2.disconnect().catch(() => {
+        session2.disconnectTransport();
+      });
+      throw new Error(
+        `Session ${sessionId} belongs to environment ${session2.environmentId}, not ${this.environmentId}.`
+      );
     }
+    return session2;
+  }
+  async reopenSession(sessionId, options) {
+    const session2 = await this.granular.reopenSession(sessionId, {
+      clientId: options?.clientId
+    });
+    if (session2.environmentId !== this.environmentId) {
+      await session2.disconnect().catch(() => {
+        session2.disconnectTransport();
+      });
+      throw new Error(
+        `Session ${sessionId} belongs to environment ${session2.environmentId}, not ${this.environmentId}.`
+      );
+    }
+    return session2;
+  }
+  async closeSession(sessionId, session2) {
+    await this.granular.closeSession(sessionId, session2);
+  }
+  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(path6, options = {}) {
     const runtimeBase = this.getRuntimeBaseUrl();
@@ -19768,95 +19901,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.
@@ -19986,7 +20030,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;
   }
@@ -20022,7 +20068,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 || [];
   }
@@ -20061,7 +20109,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"}`);
     }
   }
   /**
@@ -20096,7 +20144,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"}`);
     }
   }
   /**
@@ -20123,7 +20171,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 || [];
   }
@@ -20216,7 +20266,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;
   }
@@ -20561,7 +20611,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()`.
@@ -20613,7 +20667,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 info2 = {
@@ -20717,36 +20777,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(effects2) {
-    return super.publishEffects(effects2);
+  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 (effects2) => this.granular.registerEffects(this.ontologyNameOrId, effects2),
+      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 {
@@ -20783,6 +20993,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
    *
@@ -20819,7 +21035,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 {
@@ -20856,56 +21088,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 tag2 = options.tag?.trim() || options.tagName?.trim() || options.environment?.trim();
+    if (!tag2) {
+      throw new Error(`${methodName}() requires \`tag\`.`);
+    }
+    return tag2;
+  }
+  buildManagedEnvironmentName(tag2, versionId) {
+    return `__sdk__${tag2}__${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(
@@ -20918,22 +21179,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 tag2 = (tags.items || []).find(
+      (candidate) => Boolean(candidate?.name === tagName)
+    );
+    if (!tag2) {
+      throw new Error(
+        `Tag "${tagName}" was not found for ontology ${sandbox.sandboxId}.`
+      );
+    }
+    const targetVersionId = tag2.targetVersionId || tag2.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, tag2.tagId) && environment.versionId === targetVersionId
+      )
+    );
+    if (currentMatches.length > 0) {
+      return currentMatches[0];
+    }
+    const outdatedMatches = this.sortEnvironmentsByRecency(
+      userEnvironments.filter(
+        (environment) => this.matchesTagTrackedEnvironment(environment, tagName, tag2.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: tag2.tagId,
       permissionProfileId: null
     });
-    await this.activateEnvironment(envData.environmentId);
-    const session2 = await this.request("/ws/sessions", {
-      method: "POST",
-      body: JSON.stringify({
-        environmentId: envData.environmentId,
-        clientId,
-        initialHeap: options.initialHeap
-      })
-    });
-    return this.bindWebSocketEnvironment(envData, clientId, session2);
   }
   /**
    * List active (open) sessions for an environment — each session is one agent conversation thread.
@@ -20996,6 +21284,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 session2 = await this.request("/ws/sessions", {
       method: "POST",
       body: JSON.stringify({
@@ -21004,7 +21293,7 @@ var Granular = class _Granular {
         initialHeap: options.initialHeap
       })
     });
-    return this.bindWebSocketEnvironment(envData, clientId, session2);
+    return this.bindWebSocketEnvironmentSession(environment, clientId, session2);
   }
   /**
    * Connect to an existing open session (same conversation thread) using a freshly minted WebSocket token.
@@ -21016,7 +21305,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
@@ -21048,7 +21338,11 @@ var Granular = class _Granular {
     });
     return this.connectSession({ sessionId, clientId: options?.clientId });
   }
-  async bindWebSocketEnvironment(envData, clientId, session2) {
+  bindEnvironmentHandle(envData) {
+    const graphqlEndpoint = `${this.httpUrl}/orchestrator/graphql`;
+    return new Environment(this, envData, this.apiKey, graphqlEndpoint);
+  }
+  async bindWebSocketEnvironmentSession(environment, clientId, session2) {
     const client = new WSClient({
       url: session2.wsUrl,
       sessionId: session2.sessionId,
@@ -21059,16 +21353,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`, {
@@ -21801,15 +22092,7 @@ async function resolveEnvironmentData(granular, options) {
     userId: options.userId ?? "granular-cli",
     permissions: options.permissions ?? ["default"]
   });
-  try {
-    return await granular.environments.get(connection.environmentId);
-  } finally {
-    try {
-      await connection.disconnect();
-    } catch {
-      connection?.client?.disconnect?.();
-    }
-  }
+  return await granular.environments.get(connection.environmentId);
 }
 async function listSessionsForEnvironment(granular, environmentId, status) {
   if (status === "all") {
@@ -21830,6 +22113,7 @@ async function connectRuntime(options) {
     return {
       granular: granular2,
       environment: environment2,
+      session: environment2,
       ontologyId: environment2.ontologyId || environment2.sandboxId
     };
   }
@@ -21838,15 +22122,17 @@ async function connectRuntime(options) {
   if (!ontologyId) {
     throw new Error("No ontology configured. Run `granular init` first or pass `--ontology`.");
   }
-  const environment = await granular.connect({
+  const environmentHandle = await granular.connect({
     ontology: ontologyId,
     environment: options.environment ?? "dev",
     userId: options.userId ?? "granular-cli",
     permissions: options.permissions ?? ["default"]
   });
+  const environment = await environmentHandle.createSession();
   return {
     granular,
     environment,
+    session: environment,
     ontologyId
   };
 }
@@ -21901,7 +22187,7 @@ async function connectTestCommand(options) {
         ontologyId,
         sandboxId: environment.sandboxId,
         environmentId: environment.environmentId,
-        environment: environment.environment,
+        environment: environment.envName,
         sessionId: environment.sessionId,
         subjectId: environment.subjectId,
         versionId: environment.versionId
@@ -22014,7 +22300,7 @@ async function sessionCreateCommand(options) {
       ok: true,
       ontologyId: envData.sandboxId,
       environmentId: environment.environmentId,
-      environment: environment.environment,
+      environment: environment.envName,
       sessionId: environment.sessionId,
       subjectId: environment.subjectId,
       versionId: environment.versionId
@@ -22116,13 +22402,13 @@ async function graphqlCommand(options) {
       permissions: normalizePermissions(options.permissions),
       sessionId: options.session
     },
-    async ({ environment, ontologyId }) => {
+    async ({ environment, session: session2, ontologyId }) => {
       const result = await environment.graphql(options.query, variables);
       const payload = {
         ok: !result.errors || result.errors.length === 0,
         ontologyId,
         environmentId: environment.environmentId,
-        sessionId: environment.sessionId,
+        sessionId: session2.sessionId,
         query: options.query,
         variables: variables ?? null,
         result
@@ -22271,8 +22557,8 @@ async function jobRunCommand(options) {
       permissions: normalizePermissions(options.permissions),
       sessionId: options.session
     },
-    async ({ environment, ontologyId }) => {
-      const job2 = await environment.submitJob(code);
+    async ({ environment, session: session2, ontologyId }) => {
+      const job2 = await session2.submitJob(code);
       const stdout = [];
       const stderr = [];
       job2.on("stdout", (line) => {
@@ -22296,7 +22582,7 @@ async function jobRunCommand(options) {
         ok: true,
         ontologyId,
         environmentId: environment.environmentId,
-        sessionId: environment.sessionId,
+        sessionId: session2.sessionId,
         jobId: job2.id,
         status: job2.status,
         stdout,