@granular-software/sdk 0.4.50 → 0.4.51

package/dist/cli/index.js

@@ -60,11 +60,11 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
+var __copyProps = (to, from2, except, desc) => {
+  if (from2 && typeof from2 === "object" || typeof from2 === "function") {
+    for (let key of __getOwnPropNames(from2))
       if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+        __defProp(to, key, { get: () => from2[key], enumerable: !(desc = __getOwnPropDesc(from2, key)) || desc.enumerable });
   }
   return to;
 };
@@ -8889,7 +8889,7 @@ createChalk({ level: stderrColor ? stderrColor.level : 0 });
 var source_default = chalk;
 
 // ../../node_modules/mimic-function/index.js
-var copyProperty = (to, from, property, ignoreNonConfigurable) => {
+var copyProperty = (to, from2, property, ignoreNonConfigurable) => {
   if (property === "length" || property === "prototype") {
     return;
   }
@@ -8897,7 +8897,7 @@ var copyProperty = (to, from, property, ignoreNonConfigurable) => {
     return;
   }
   const toDescriptor = Object.getOwnPropertyDescriptor(to, property);
-  const fromDescriptor = Object.getOwnPropertyDescriptor(from, property);
+  const fromDescriptor = Object.getOwnPropertyDescriptor(from2, property);
   if (!canCopyProperty(toDescriptor, fromDescriptor) && ignoreNonConfigurable) {
     return;
   }
@@ -8906,8 +8906,8 @@ var copyProperty = (to, from, property, ignoreNonConfigurable) => {
 var canCopyProperty = function(toDescriptor, fromDescriptor) {
   return toDescriptor === void 0 || toDescriptor.configurable || toDescriptor.writable === fromDescriptor.writable && toDescriptor.enumerable === fromDescriptor.enumerable && toDescriptor.configurable === fromDescriptor.configurable && (toDescriptor.writable || toDescriptor.value === fromDescriptor.value);
 };
-var changePrototype = (to, from) => {
-  const fromPrototype = Object.getPrototypeOf(from);
+var changePrototype = (to, from2) => {
+  const fromPrototype = Object.getPrototypeOf(from2);
   if (fromPrototype === Object.getPrototypeOf(to)) {
     return;
   }
@@ -8917,20 +8917,20 @@ var wrappedToString = (withName, fromBody) => `/* Wrapped ${withName}*/
 ${fromBody}`;
 var toStringDescriptor = Object.getOwnPropertyDescriptor(Function.prototype, "toString");
 var toStringName = Object.getOwnPropertyDescriptor(Function.prototype.toString, "name");
-var changeToString = (to, from, name) => {
+var changeToString = (to, from2, name) => {
   const withName = name === "" ? "" : `with ${name.trim()}() `;
-  const newToString = wrappedToString.bind(null, withName, from.toString());
+  const newToString = wrappedToString.bind(null, withName, from2.toString());
   Object.defineProperty(newToString, "name", toStringName);
   const { writable, enumerable, configurable } = toStringDescriptor;
   Object.defineProperty(to, "toString", { value: newToString, writable, enumerable, configurable });
 };
-function mimicFunction(to, from, { ignoreNonConfigurable = false } = {}) {
+function mimicFunction(to, from2, { ignoreNonConfigurable = false } = {}) {
   const { name } = to;
-  for (const property of Reflect.ownKeys(from)) {
-    copyProperty(to, from, property, ignoreNonConfigurable);
+  for (const property of Reflect.ownKeys(from2)) {
+    copyProperty(to, from2, property, ignoreNonConfigurable);
   }
-  changePrototype(to, from);
-  changeToString(to, from, name);
+  changePrototype(to, from2);
+  changeToString(to, from2, name);
   return to;
 }
 
@@ -15624,11 +15624,20 @@ function buildStateMachineModelMutations(modelPath, machines) {
   return mutations;
 }
 function buildMachineTypes(classSummary, machine) {
+  const stateGlossary = machine.states.map((state) => {
+    const label = state.label && state.label !== state.name ? state.label : null;
+    const meaning = [label, state.description].filter(Boolean).join(" \u2014 ");
+    const finalMarker = state.isFinal ? " Final state." : "";
+    return `${state.name}${meaning ? `: ${meaning}` : "."}${finalMarker}`;
+  });
   return [
     {
       kind: "union",
       name: stateTypeName(classSummary.name, machine.name),
-      docs: [`Allowed states for ${classSummary.name}.${machine.name}.`],
+      docs: [
+        `Allowed states for ${classSummary.name}.${machine.name}.`,
+        ...stateGlossary
+      ],
       members: machine.states.map((state) => state.name)
     },
     {
@@ -15976,7 +15985,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
           },
           add_transition: async (value, {
             name,
-            from,
+            from: from2,
             to,
             label,
             description,
@@ -15991,7 +16000,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
               value.target.add_state_machine_transition(
                 value.name,
                 name,
-                from,
+                from2,
                 to,
                 {
                   label,
@@ -16814,7 +16823,7 @@ ${effectMetamodelTable}
 | \`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. |
+| \`sessions.list({ status?, sessionScope?, limit?, offset? })\`, \`sessions.create({ sessionScope? })\`, \`sessions.connect()\`, \`sessions.reopen()\`, \`sessions.close()\` | Scoped, bounded session history and lifecycle for this environment. |
 
 ### \`Session\` (live runtime connection)
 
@@ -16862,7 +16871,7 @@ Use \`environment.graphql(query, variables?)\` when you need **query/mutation ac
 | \`granular simulate\` | Open simulator in browser. |
 | \`granular simulate --print-url\` | Print a deep-linkable simulator URL without opening the browser. |
 | \`granular connect test --json\` | Verify auth and environment connectivity with a real session. |
-| \`granular session create/list/heap/doc --json\` | Create, enumerate, and inspect real session state. |
+| \`granular session create/list/heap/doc --json\` | Create, enumerate, and inspect real session state. \`session list\` defaults to 25 rows; use \`--session-scope\`, \`--subject-id\`, \`--limit\`, and \`--offset\` for deterministic paging. |
 | \`granular graphql --query '...' --json\` | Run a GraphQL query or mutation against the live graph. |
 | \`granular effects list/diff --json\` | Inspect declared versus live ready effects. |
 | \`granular job run --file ./job.ts --json\` | Execute a real runtime job from the terminal or CI. |
@@ -17542,8 +17551,8 @@ Use this for command execution, environment setup, and shipping flows.
 | \`granular graphql --query '...' --json\` | Query the live graph through the environment GraphQL API |
 | \`granular effects list --json\` | Inspect declared and live effects for an environment |
 | \`granular effects diff --json\` | Compare declared effects to live ready handlers |
-| \`granular session create --json\` | Create a fresh session for an environment |
-| \`granular session list --json\` | List indexed sessions for an environment |
+| \`granular session create --session-scope <scope> --json\` | Create a fresh, application-scoped session for an environment |
+| \`granular session list --session-scope <scope> --limit 25 --offset 0 --json\` | List one bounded page of indexed sessions |
 | \`granular session heap --json\` | Inspect session heap |
 | \`granular session doc --json\` | Inspect the Automerge-backed session document |
 | \`granular job run --file ./job.ts\` | Execute a real job against the ontology runtime |
@@ -17626,8 +17635,8 @@ Use this for runtime debugging after the ontology builds but behavior does not m
 
 | Goal | Preferred path |
 | --- | --- |
-| Create or rotate a session | \`granular session create --json\` |
-| List known sessions | \`granular session list --json\` |
+| Create or rotate a session | \`granular session create --session-scope <scope> --json\` |
+| List known sessions | \`granular session list --session-scope <scope> --limit 25 --offset 0 --json\` |
 | Inspect heap | \`granular session heap --json\` |
 | Inspect full document | \`granular session doc --json\` |
 | Verify connectivity | \`granular connect test\` |
@@ -19560,16 +19569,37 @@ var WSClient = class {
   tokenRefreshTimer = null;
   isExplicitlyDisconnected = false;
   reconnectAttempts = 0;
+  connectPromise = null;
+  connectionEpoch = 0;
+  cancelConnectAttempt = null;
   options;
   constructor(options) {
     this.options = options;
     this.url = options.url;
     this.sessionId = options.sessionId;
     this.token = options.token;
+    if (options.initialDocumentSnapshot) {
+      this.seedDocumentSnapshot(options.initialDocumentSnapshot);
+    }
   }
   get currentSessionId() {
     return this.sessionId;
   }
+  seedDocumentSnapshot(document) {
+    if (!document || typeof document !== "object" || Array.isArray(document)) {
+      return;
+    }
+    try {
+      this.doc = document instanceof Uint8Array ? Automerge__namespace.load(document) : Automerge__namespace.from(document);
+      this.syncState = Automerge__namespace.initSyncState();
+      this.emit("sync", this.doc);
+    } catch (error2) {
+      console.warn("[Granular] Failed to seed cached session document", error2);
+    }
+  }
+  saveDocumentSnapshot() {
+    return Automerge__namespace.save(this.doc);
+  }
   clearTokenRefreshTimer() {
     if (this.tokenRefreshTimer) {
       clearTimeout(this.tokenRefreshTimer);
@@ -19679,8 +19709,23 @@ var WSClient = class {
    * Connect to the WebSocket server
    * @returns {Promise<void>} Resolves when connection is open
    */
-  async connect() {
+  async connect(options = {}) {
+    if (this.ws?.readyState === READY_STATE_OPEN) return;
+    if (this.connectPromise) return this.connectPromise;
+    const connectPromise = this.connectAttempt(options.signal);
+    this.connectPromise = connectPromise;
+    try {
+      await connectPromise;
+    } finally {
+      if (this.connectPromise === connectPromise) {
+        this.connectPromise = null;
+      }
+    }
+  }
+  async connectAttempt(signal) {
+    if (signal?.aborted) throw new Error("WebSocket connect aborted");
     const token = await this.resolveTokenForConnect();
+    if (signal?.aborted) throw new Error("WebSocket connect aborted");
     this.isExplicitlyDisconnected = false;
     this.scheduleTokenRefresh();
     if (this.reconnectTimer) {
@@ -19692,7 +19737,7 @@ var WSClient = class {
       try {
         const wsModule = await import('ws');
         WebSocketClass = wsModule.default || wsModule;
-      } catch (e) {
+      } catch {
       }
     }
     if (!WebSocketClass) {
@@ -19700,83 +19745,97 @@ var WSClient = class {
         'No WebSocket implementation found. If using Node.js, please install "ws" and pass the constructor to the SDK options: { WebSocketCtor: WebSocket }.'
       );
     }
+    const epoch = ++this.connectionEpoch;
+    const wsUrl = new URL(this.url);
+    wsUrl.searchParams.set("sessionId", this.sessionId);
+    wsUrl.searchParams.set("token", token);
+    const socket = new WebSocketClass(wsUrl.toString());
+    this.ws = socket;
     return new Promise((resolve2, reject) => {
-      try {
-        const wsUrl = new URL(this.url);
-        wsUrl.searchParams.set("sessionId", this.sessionId);
-        wsUrl.searchParams.set("token", token);
-        this.ws = new WebSocketClass(wsUrl.toString());
-        if (!this.ws) throw new Error("Failed to create WebSocket");
-        const socket = this.ws;
-        if (typeof socket.on === "function") {
-          socket.on("open", () => {
-            if (this.reconnectTimer) {
-              clearTimeout(this.reconnectTimer);
-              this.reconnectTimer = null;
-            }
-            this.reconnectAttempts = 0;
-            this.emit("open", {});
-            resolve2();
-          });
-          socket.on("message", (data) => {
-            try {
-              const message = JSON.parse(data.toString());
-              this.handleMessage(message);
-            } catch (error2) {
-              console.error("[Granular] Failed to parse message:", error2);
-            }
-          });
-          socket.on("error", (error2) => {
-            this.emit("error", error2);
-            if (socket.readyState !== READY_STATE_OPEN) {
-              reject(error2);
-            }
-          });
-          socket.on("close", (code, reason) => {
-            this.handleDisconnect({
-              code,
-              reason: this.normalizeReason(reason),
-              // ws does not provide wasClean on Node-style close callback
-              wasClean: code === 1e3
-            });
-          });
+      let settled = false;
+      const isCurrent = () => this.connectionEpoch === epoch && this.ws === socket;
+      const finish = (error2) => {
+        if (settled) return;
+        settled = true;
+        if (this.cancelConnectAttempt === handleAbort) {
+          this.cancelConnectAttempt = null;
+        }
+        signal?.removeEventListener("abort", handleAbort);
+        if (error2) {
+          reject(error2 instanceof Error ? error2 : new Error(String(error2)));
         } else {
-          this.ws.onopen = () => {
-            if (this.reconnectTimer) {
-              clearTimeout(this.reconnectTimer);
-              this.reconnectTimer = null;
-            }
-            this.reconnectAttempts = 0;
-            this.emit("open", {});
-            resolve2();
-          };
-          this.ws.onmessage = (event) => {
-            try {
-              const data = event.data;
-              const message = JSON.parse(data.toString());
-              this.handleMessage(message);
-            } catch (error2) {
-              console.error("[Granular] Failed to parse message:", error2);
-            }
-          };
-          this.ws.onerror = (event) => {
-            const error2 = new Error("WebSocket error");
-            error2.event = event;
-            this.emit("error", error2);
-            if (this.ws?.readyState !== READY_STATE_OPEN) {
-              reject(error2);
-            }
-          };
-          this.ws.onclose = (event) => {
-            this.handleDisconnect({
-              code: event.code,
-              reason: event.reason,
-              wasClean: event.wasClean
-            });
-          };
+          resolve2();
         }
-      } catch (error2) {
-        reject(error2);
+      };
+      const closeStaleSocket = () => {
+        try {
+          socket.close(1e3, "Stale connection attempt");
+        } catch {
+        }
+      };
+      const handleAbort = () => {
+        if (isCurrent()) {
+          this.connectionEpoch += 1;
+          this.ws = null;
+        }
+        closeStaleSocket();
+        finish(new Error("WebSocket connect aborted"));
+      };
+      this.cancelConnectAttempt = handleAbort;
+      const handleOpen = () => {
+        if (!isCurrent()) {
+          closeStaleSocket();
+          return;
+        }
+        this.reconnectAttempts = 0;
+        this.emit("open", {});
+        finish();
+      };
+      const handleMessage = (data) => {
+        if (!isCurrent()) return;
+        try {
+          const text = typeof data === "string" ? data : data && typeof data === "object" && "toString" in data ? String(data.toString()) : "";
+          this.handleMessage(JSON.parse(text));
+        } catch (error2) {
+          console.error("[Granular] Failed to parse message:", error2);
+        }
+      };
+      const handleError = (error2) => {
+        if (!isCurrent()) return;
+        const typedError = error2 instanceof Error ? error2 : new Error("WebSocket error");
+        this.emit("error", typedError);
+        if (socket.readyState !== READY_STATE_OPEN) finish(typedError);
+      };
+      const handleClose = (close) => {
+        if (!isCurrent()) return;
+        if (!settled) {
+          finish(
+            new Error(
+              `WebSocket closed before ready${close.code ? ` (code=${close.code})` : ""}`
+            )
+          );
+        }
+        this.handleDisconnect({
+          code: close.code,
+          reason: this.normalizeReason(close.reason),
+          wasClean: close.wasClean
+        });
+      };
+      signal?.addEventListener("abort", handleAbort, { once: true });
+      const nodeSocket = socket;
+      if (typeof nodeSocket.on === "function") {
+        nodeSocket.on("open", handleOpen);
+        nodeSocket.on("message", handleMessage);
+        nodeSocket.on("error", handleError);
+        nodeSocket.on(
+          "close",
+          (code, reason) => handleClose({ code, reason, wasClean: code === 1e3 })
+        );
+      } else {
+        socket.onopen = handleOpen;
+        socket.onmessage = (event) => handleMessage(event.data);
+        socket.onerror = handleError;
+        socket.onclose = (event) => handleClose(event);
       }
     });
   }
@@ -19794,9 +19853,58 @@ var WSClient = class {
     return void 0;
   }
   rejectPending(error2) {
-    this.messageQueue.forEach((pending) => pending.reject(error2));
+    this.messageQueue.forEach((pending) => {
+      clearTimeout(pending.timeout);
+      pending.reject(error2);
+    });
     this.messageQueue = [];
   }
+  emitReconnectErrorMessage(error2) {
+    const reconnectInfo = {
+      error: error2,
+      sessionId: this.sessionId,
+      timestamp: Date.now()
+    };
+    this.emit("reconnect_error", reconnectInfo);
+    if (this.options.onReconnectError) {
+      try {
+        this.options.onReconnectError(reconnectInfo);
+      } catch (callbackError) {
+        console.error(
+          "[Granular] onReconnectError callback failed:",
+          callbackError
+        );
+      }
+    }
+  }
+  scheduleReconnectAttempt() {
+    if (this.isExplicitlyDisconnected || this.reconnectTimer) return null;
+    const baseReconnectDelayMs = typeof this.options.reconnectDelayMs === "number" && Number.isFinite(this.options.reconnectDelayMs) && this.options.reconnectDelayMs > 0 ? this.options.reconnectDelayMs : DEFAULT_RECONNECT_DELAY_MS;
+    const maxReconnectAttempts = typeof this.options.maxReconnectAttempts === "number" && Number.isFinite(this.options.maxReconnectAttempts) && this.options.maxReconnectAttempts >= 0 ? Math.floor(this.options.maxReconnectAttempts) : DEFAULT_MAX_RECONNECT_ATTEMPTS;
+    if (this.reconnectAttempts >= maxReconnectAttempts) {
+      this.emitReconnectErrorMessage(
+        `WebSocket reconnect attempts exhausted after ${maxReconnectAttempts} attempt(s).`
+      );
+      return null;
+    }
+    this.reconnectAttempts += 1;
+    const reconnectDelayMs = Math.min(
+      3e4,
+      baseReconnectDelayMs * 2 ** Math.max(0, this.reconnectAttempts - 1)
+    );
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      console.log("[Granular] Attempting reconnect...");
+      this.connect().catch((error2) => {
+        console.error("[Granular] Reconnect failed:", error2);
+        this.emitReconnectErrorMessage(
+          error2 instanceof Error ? error2.message : String(error2)
+        );
+        this.scheduleReconnectAttempt();
+      });
+    }, reconnectDelayMs);
+    return reconnectDelayMs;
+  }
   buildDisconnectError(info2) {
     const details = [
       info2.code !== void 0 ? `code=${info2.code}` : void 0,
@@ -19806,8 +19914,6 @@ var WSClient = class {
     return new Error(`WebSocket disconnected${suffix}`);
   }
   handleDisconnect(close = {}) {
-    const baseReconnectDelayMs = typeof this.options.reconnectDelayMs === "number" && Number.isFinite(this.options.reconnectDelayMs) && this.options.reconnectDelayMs > 0 ? this.options.reconnectDelayMs : DEFAULT_RECONNECT_DELAY_MS;
-    const maxReconnectAttempts = typeof this.options.maxReconnectAttempts === "number" && Number.isFinite(this.options.maxReconnectAttempts) && this.options.maxReconnectAttempts >= 0 ? Math.floor(this.options.maxReconnectAttempts) : DEFAULT_MAX_RECONNECT_ATTEMPTS;
     const unexpected = !this.isExplicitlyDisconnected;
     const info2 = {
       code: close.code,
@@ -19827,32 +19933,9 @@ var WSClient = class {
       const disconnectError = this.buildDisconnectError(info2);
       this.rejectPending(disconnectError);
       this.emit("disconnect", info2);
-      if (this.reconnectAttempts >= maxReconnectAttempts) {
-        const reconnectInfo = {
-          error: `WebSocket reconnect attempts exhausted after ${maxReconnectAttempts} attempt(s).`,
-          sessionId: this.sessionId,
-          timestamp: Date.now()
-        };
-        this.emit("reconnect_error", reconnectInfo);
-        if (this.options.onReconnectError) {
-          try {
-            this.options.onReconnectError(reconnectInfo);
-          } catch (callbackError) {
-            console.error(
-              "[Granular] onReconnectError callback failed:",
-              callbackError
-            );
-          }
-        }
-        return;
-      }
-      this.reconnectAttempts += 1;
-      const reconnectDelayMs = Math.min(
-        3e4,
-        baseReconnectDelayMs * 2 ** Math.max(0, this.reconnectAttempts - 1)
-      );
-      info2.reconnectScheduled = true;
-      info2.reconnectDelayMs = reconnectDelayMs;
+      const reconnectDelayMs = this.scheduleReconnectAttempt();
+      info2.reconnectScheduled = reconnectDelayMs !== null;
+      if (reconnectDelayMs !== null) info2.reconnectDelayMs = reconnectDelayMs;
       if (this.options.onUnexpectedClose) {
         try {
           this.options.onUnexpectedClose(info2);
@@ -19863,28 +19946,6 @@ var WSClient = class {
           );
         }
       }
-      this.reconnectTimer = setTimeout(() => {
-        console.log("[Granular] Attempting reconnect...");
-        this.connect().catch((error2) => {
-          console.error("[Granular] Reconnect failed:", error2);
-          const reconnectInfo = {
-            error: error2 instanceof Error ? error2.message : String(error2),
-            sessionId: this.sessionId,
-            timestamp: Date.now()
-          };
-          this.emit("reconnect_error", reconnectInfo);
-          if (this.options.onReconnectError) {
-            try {
-              this.options.onReconnectError(reconnectInfo);
-            } catch (callbackError) {
-              console.error(
-                "[Granular] onReconnectError callback failed:",
-                callbackError
-              );
-            }
-          }
-        });
-      }, reconnectDelayMs);
     }
   }
   handleMessage(message) {
@@ -19995,6 +20056,7 @@ var WSClient = class {
       const response = message;
       const pending = this.messageQueue.find((q) => q.id === response.id);
       if (pending) {
+        clearTimeout(pending.timeout);
         if (response.type === "rpc_error") {
           pending.reject(
             new Error(
@@ -20040,16 +20102,22 @@ var WSClient = class {
       id
     };
     return new Promise((resolve2, reject) => {
-      this.messageQueue.push({ resolve: resolve2, reject, id });
-      this.ws.send(JSON.stringify(request));
       const timeoutMs = rpcTimeoutMsForMethod(method);
-      setTimeout(() => {
+      const timeout = setTimeout(() => {
         const pending = this.messageQueue.find((q) => q.id === id);
         if (pending) {
           this.messageQueue = this.messageQueue.filter((q) => q.id !== id);
           reject(new Error(`RPC timeout: ${method}`));
         }
       }, timeoutMs);
+      this.messageQueue.push({ resolve: resolve2, reject, id, timeout });
+      try {
+        this.ws.send(JSON.stringify(request));
+      } catch (error2) {
+        clearTimeout(timeout);
+        this.messageQueue = this.messageQueue.filter((q) => q.id !== id);
+        reject(error2 instanceof Error ? error2 : new Error(String(error2)));
+      }
     });
   }
   async handleIncomingRpc(request) {
@@ -20135,15 +20203,18 @@ var WSClient = class {
   /**
    * Disconnect the WebSocket and clear state
    */
-  disconnect() {
+  disconnect(options = {}) {
     this.isExplicitlyDisconnected = true;
+    this.cancelConnectAttempt?.();
+    this.cancelConnectAttempt = null;
+    this.connectionEpoch += 1;
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
     this.clearTokenRefreshTimer();
     if (this.ws) {
-      this.ws.close(1e3, "Client disconnect");
+      this.ws.close(1e3, options.reason || "Client disconnect");
       this.ws = null;
     }
     this.rejectPending(new Error("Client explicitly disconnected"));
@@ -20239,8 +20310,12 @@ function normalizePrompt(rawValue) {
   const source = promptRecord || raw;
   const id = typeof source.id === "string" ? source.id : typeof raw.id === "string" ? raw.id : typeof raw.promptId === "string" ? raw.promptId : "";
   if (!id) return null;
+  const jobId = typeof source.jobId === "string" && source.jobId.trim() ? source.jobId.trim() : typeof raw.jobId === "string" && raw.jobId.trim() ? raw.jobId.trim() : void 0;
+  const turnId = typeof source.turnId === "string" && source.turnId.trim() ? source.turnId.trim() : typeof raw.turnId === "string" && raw.turnId.trim() ? raw.turnId.trim() : void 0;
   return {
     id,
+    ...jobId ? { jobId } : {},
+    ...turnId ? { turnId } : {},
     type: normalizePromptType(source === raw ? raw : { ...raw, ...source }),
     title: typeof source.title === "string" ? source.title : "Input required",
     message: typeof source.message === "string" ? source.message : "",
@@ -20327,6 +20402,9 @@ var Session = class {
     this.initialQuota = options.initialQuota || null;
     this.setupEventHandlers();
     this.setupToolInvokeHandler();
+    this.currentDomainRevision = this.extractDomainRevisionFromDoc(
+      this.client.doc
+    );
   }
   extractDomainRevisionFromDoc(doc) {
     const domain = doc?.domain;
@@ -21232,6 +21310,7 @@ function normalizeJobAgentMessageEnvelope(data) {
   }
   return {
     jobId: d.jobId,
+    ...typeof d.turnId === "string" && d.turnId.trim() ? { turnId: d.turnId.trim() } : {},
     message: {
       messageId: d.messageId,
       kind: d.kind === "artifacts" ? "artifacts" : "text",
@@ -21890,9 +21969,14 @@ function normalizeShowRefs(value) {
     variableNames: normalizeRefs(record.variableNames),
     fileIds: normalizeRefs(record.fileIds),
     sessionArtifactIds: normalizeRefs(record.sessionArtifactIds),
-    actionSuggestions: normalizeActionSuggestions(record.actionSuggestions)
+    actionSuggestions: normalizeActionSuggestions(record.actionSuggestions),
+    tables: Array.isArray(record.tables) ? record.tables.filter(
+      (table2) => Boolean(
+        table2 && typeof table2 === "object" && !Array.isArray(table2) && Array.isArray(table2.columns) && Array.isArray(table2.rows)
+      )
+    ) : void 0
   };
-  return show.entryPaths || show.listNames || show.variableNames || show.fileIds || show.sessionArtifactIds || show.actionSuggestions ? show : void 0;
+  return show.entryPaths || show.listNames || show.variableNames || show.fileIds || show.sessionArtifactIds || show.actionSuggestions || show.tables ? show : void 0;
 }
 function normalizeActionSuggestions(value) {
   if (!Array.isArray(value)) return void 0;
@@ -21914,6 +21998,76 @@ function normalizeActionSuggestions(value) {
   }
   return suggestions.length ? suggestions : void 0;
 }
+var TRANSCRIPT_MESSAGE_PART_LIMIT = 128;
+var TRANSCRIPT_MESSAGE_PART_TEXT_LIMIT = 2e5;
+var TRANSCRIPT_MESSAGE_PART_ACTION_LABEL_LIMIT = 1e3;
+var TRANSCRIPT_MESSAGE_ACTION_LIMIT = 64;
+function normalizeConversationMessageActions(value) {
+  if (!Array.isArray(value) || value.length === 0) return void 0;
+  const actions = [];
+  for (const item of value.slice(0, TRANSCRIPT_MESSAGE_ACTION_LIMIT)) {
+    const record = asRecord3(item);
+    const kind = record?.kind;
+    const label = trimString(record?.label ?? record?.title);
+    const status = record?.status;
+    if (kind !== "frontend" && kind !== "backend" && kind !== "system" || !label || label.length > TRANSCRIPT_MESSAGE_PART_ACTION_LABEL_LIMIT) {
+      continue;
+    }
+    actions.push({
+      kind,
+      label,
+      ...status === "done" || status === "queued" || status === "failed" ? { status } : {}
+    });
+  }
+  return actions.length ? actions : void 0;
+}
+function normalizeConversationMessageParts(value, canonicalContent, canonicalActions) {
+  if (!Array.isArray(value) || value.length === 0 || value.length > TRANSCRIPT_MESSAGE_PART_LIMIT) {
+    return void 0;
+  }
+  const parts = [];
+  const canonicalActionsById = new Map(
+    (canonicalActions || []).map((action) => [
+      `${action.kind}:${action.label}`,
+      action
+    ])
+  );
+  const seenActionIds = /* @__PURE__ */ new Set();
+  let textLength = 0;
+  for (const item of value) {
+    const record = asRecord3(item);
+    if (!record) return void 0;
+    if (record.type === "text") {
+      if (typeof record.text !== "string" || record.text.length === 0) {
+        return void 0;
+      }
+      textLength += record.text.length;
+      if (textLength > TRANSCRIPT_MESSAGE_PART_TEXT_LIMIT) return void 0;
+      parts.push({ type: "text", text: record.text });
+      continue;
+    }
+    if (record.type !== "action") return void 0;
+    const action = asRecord3(record.action);
+    const kind = action?.kind;
+    const label = trimString(action?.label);
+    if (kind !== "frontend" && kind !== "backend" && kind !== "system" || !label || label.length > TRANSCRIPT_MESSAGE_PART_ACTION_LABEL_LIMIT) {
+      return void 0;
+    }
+    const actionId = `${kind}:${label}`;
+    const canonicalAction = canonicalActionsById.get(actionId);
+    if (!canonicalAction) return void 0;
+    if (seenActionIds.has(actionId)) continue;
+    seenActionIds.add(actionId);
+    parts.push({
+      type: "action",
+      action: canonicalAction
+    });
+  }
+  const orderedText = parts.filter(
+    (part) => part.type === "text"
+  ).map((part) => part.text).join("");
+  return orderedText === canonicalContent ? parts : void 0;
+}
 function stringifyTranscriptValue(value, fallback2 = "") {
   if (typeof value === "string") {
     return value.trim() || fallback2;
@@ -22072,10 +22226,12 @@ function normalizeConversationMessage(raw, artifactsById) {
   const content = trimString(
     record.content ?? record.reply ?? record.message ?? record.text
   );
+  const actions = role === "assistant" ? normalizeConversationMessageActions(record.actions) : void 0;
+  const parts = role === "assistant" ? normalizeConversationMessageParts(record.parts, content, actions) : void 0;
   const show = normalizeShowRefs(record.show);
   const id = asString(record.id) || crypto.randomUUID();
   const timestamp = asNumber(record.timestamp) || asNumber(record.ts) || 0;
-  if (!content && !show) return null;
+  if (!content && !show && !actions?.length) return null;
   const artifactHistory = buildArtifactHistory(show, artifactsById);
   const historyContent = role === "assistant" ? content && artifactHistory ? `[Assistant reply]
 ${content}
@@ -22090,6 +22246,8 @@ ${content}` : artifactHistory : void 0;
     jobId: asString(record.jobId),
     promptId: asString(record.promptId),
     show,
+    actions,
+    parts,
     historyContent,
     source: "conversation"
   };
@@ -22738,7 +22896,12 @@ async function recordOpenAIUsageSpend(options) {
   const metadata = {
     ...options.metadata || {},
     ...options.usage.rawUsage !== void 0 ? { openaiUsage: options.usage.rawUsage } : {},
-    usageContext: context
+    usageContext: context,
+    pricingContextTier: options.usage.pricingContextTier,
+    cacheWritePricePerMillionMicros: options.usage.cacheWritePricePerMillionMicros,
+    cacheWriteTokens: options.usage.cacheWriteTokens,
+    cacheWriteCostMicros: options.usage.cacheWriteCostMicros,
+    longContextThresholdTokens: options.usage.longContextThresholdTokens
   };
   const response = await fetch(
     `${toGranularHttpBase(options.apiUrl)}/control/spend/events`,
@@ -22809,6 +22972,18 @@ function buildEffectMetamodelMutations(toolPath, spec) {
 }
 
 // src/client.ts
+var DEFAULT_CONVERSATION_SESSION_LIST_LIMIT = 100;
+var MAX_CONVERSATION_SESSION_LIST_LIMIT = 500;
+var MAX_CONVERSATION_SESSION_LIST_OFFSET = 1e5;
+function boundedSessionListInteger(value, name, fallback2, minimum, maximum) {
+  if (value === void 0) return fallback2;
+  if (!Number.isInteger(value) || value < minimum || value > maximum) {
+    throw new RangeError(
+      `Session list ${name} must be an integer between ${minimum} and ${maximum}.`
+    );
+  }
+  return value;
+}
 var STANDARD_MODULES_OPERATIONS = [
   {
     create: "entity",
@@ -23147,7 +23322,7 @@ var Environment = class _Environment {
   }
   get sessions() {
     return {
-      list: async (options) => this.listSessions(options?.status || "active"),
+      list: async (options = {}) => this.listSessions(options),
       create: async (options) => this.createSession(options),
       connect: async (sessionId, options) => this.connectSession(sessionId, options),
       reopen: async (sessionId, options) => this.reopenSession(sessionId, options),
@@ -23282,17 +23457,12 @@ var Environment = class _Environment {
    */
   async disconnect() {
   }
-  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 listSessions(optionsOrStatus = {}) {
+    const options = typeof optionsOrStatus === "string" ? { status: optionsOrStatus } : optionsOrStatus;
+    return this.granular.listSessions({
+      ...options,
+      environmentId: this.environmentId
+    });
   }
   async getUserEnvironmentState(options = {}) {
     return this.granular.getUserEnvironmentState({
@@ -23310,6 +23480,7 @@ var Environment = class _Environment {
     return this.granular.createSession({
       environmentId: this.environmentId,
       clientId: options?.clientId,
+      sessionScope: options?.sessionScope,
       initialHeap: options?.initialHeap
     });
   }
@@ -24872,7 +25043,7 @@ var EnvironmentSession = class extends Session {
    * Close only the socket transport without sending `client.goodbye`.
    */
   disconnectTransport() {
-    this.client.disconnect();
+    this.client.disconnect({ reason: "Transport detach" });
   }
   /**
    * Backwards-compatible alias for `disconnect()`.
@@ -25267,16 +25438,71 @@ var Granular = class _Granular {
     };
   }
   /**
-   * List active (open) sessions for an environment — each session is one agent conversation thread.
+   * List indexed sessions using ownership filters and bounded pagination.
+   */
+  async listSessions(options) {
+    const environmentId = options.environmentId?.trim();
+    const sandboxId = options.sandboxId?.trim();
+    const subjectId = options.subjectId?.trim();
+    if (!environmentId && !sandboxId && !subjectId) {
+      throw new Error(
+        "listSessions() requires environmentId, sandboxId, or subjectId so history cannot be scanned accidentally."
+      );
+    }
+    const status = options.status || "active";
+    const allowedStatuses = /* @__PURE__ */ new Set([
+      "active",
+      "closed",
+      "expired",
+      "failed",
+      "timeout",
+      "all"
+    ]);
+    if (!allowedStatuses.has(status)) {
+      throw new Error(`Unsupported session status: ${String(status)}`);
+    }
+    const limit = boundedSessionListInteger(
+      options.limit,
+      "limit",
+      DEFAULT_CONVERSATION_SESSION_LIST_LIMIT,
+      1,
+      MAX_CONVERSATION_SESSION_LIST_LIMIT
+    );
+    const offset = boundedSessionListInteger(
+      options.offset,
+      "offset",
+      0,
+      0,
+      MAX_CONVERSATION_SESSION_LIST_OFFSET
+    );
+    const query = new URLSearchParams({
+      limit: String(limit),
+      offset: String(offset)
+    });
+    if (environmentId) query.set("environmentId", environmentId);
+    if (sandboxId) query.set("sandboxId", sandboxId);
+    if (subjectId) query.set("userId", subjectId);
+    if (options.sessionScope?.trim()) {
+      query.set("sessionScope", options.sessionScope.trim());
+    }
+    if (status !== "all") query.set("status", status);
+    const res = await this.request(
+      `/control/sessions?${query.toString()}`
+    );
+    const items = Array.isArray(res.items) ? res.items : [];
+    return items.map((row) => this.normalizeConversationSession(row));
+  }
+  /**
+   * List active (open) sessions for an environment.
    */
   async listOpenSessions(filters) {
-    return this.listSessionsForEnvironment(filters.environmentId, "active");
+    return this.listSessions({ ...filters, status: "active" });
   }
   /**
    * List closed sessions for an environment (conversations that have disconnected).
    */
   async listClosedSessions(filters) {
-    return this.listSessionsForEnvironment(filters.environmentId, "closed");
+    return this.listSessions({ ...filters, status: "closed" });
   }
   async getUserEnvironmentState(options) {
     const query = new URLSearchParams({
@@ -25311,14 +25537,6 @@ var Granular = class _Granular {
     });
     return result.readAtBySessionId || {};
   }
-  async listSessionsForEnvironment(environmentId, status) {
-    const query = new URLSearchParams({ environmentId, status });
-    const res = await this.request(
-      `/control/sessions?${query.toString()}`
-    );
-    const items = Array.isArray(res.items) ? res.items : [];
-    return items.map((row) => this.normalizeConversationSession(row));
-  }
   normalizeConversationSession(row) {
     const sessionId = String(row.sessionId ?? row.session_id ?? "");
     const environmentId = String(row.environmentId ?? row.environment_id ?? "");
@@ -25377,6 +25595,7 @@ var Granular = class _Granular {
    */
   async createSession(options) {
     const clientId = options.clientId || `client_${Date.now()}`;
+    const sessionScope = options.sessionScope?.trim() || void 0;
     await this.activateEnvironment(options.environmentId);
     const envData = await this.environments.get(options.environmentId);
     const environment = this.bindEnvironmentHandle(envData);
@@ -25385,6 +25604,8 @@ var Granular = class _Granular {
       body: JSON.stringify({
         environmentId: options.environmentId,
         clientId,
+        sessionScope,
+        capabilities: sessionScope ? { sessionScope } : void 0,
         initialHeap: options.initialHeap
       })
     });
@@ -26706,15 +26927,22 @@ async function resolveEnvironmentData(granular, options) {
   const ontologyId = await resolveOntologyId(granular, options.ontology);
   const environmentName = options.environment ?? "dev";
   const environments = await granular.environments.list(ontologyId);
-  const existing = environments.find(
-    (environment) => matchesEnvironmentName(environment, environmentName)
+  const matchingEnvironments = environments.filter(
+    (environment) => matchesEnvironmentName(environment, environmentName) && (!options.subjectId || environment.subjectId === options.subjectId)
   );
+  if (matchingEnvironments.length > 1) {
+    throw new Error(
+      `Environment slot \`${environmentName}\` matches ${matchingEnvironments.length} subject environments. Pass --environment-id or --subject-id so session history cannot resolve to an arbitrary user.`
+    );
+  }
+  const existing = matchingEnvironments[0];
   if (existing) {
     return existing;
   }
   if (!options.createIfMissing) {
+    const subjectSuffix = options.subjectId ? ` for subject \`${options.subjectId}\`` : "";
     throw new Error(
-      `No environment named \`${environmentName}\` found for ontology \`${ontologyId}\`. Run \`granular connect test\` or \`granular session create\` first, or pass \`--environment-id\`.`
+      `No environment named \`${environmentName}\`${subjectSuffix} found for ontology \`${ontologyId}\`. Run \`granular connect test\` or \`granular session create\` first, or pass \`--environment-id\`.`
     );
   }
   const connection = await granular.connect({
@@ -26725,17 +26953,15 @@ async function resolveEnvironmentData(granular, options) {
   });
   return await granular.environments.get(connection.environmentId);
 }
-async function listSessionsForEnvironment(granular, environmentId, status) {
-  if (status === "all") {
-    const [active, closed] = await Promise.all([
-      granular.listOpenSessions({ environmentId }),
-      granular.listClosedSessions({ environmentId })
-    ]);
-    return [...active, ...closed].sort((left, right) => {
-      return Date.parse(right.lastSeenAt) - Date.parse(left.lastSeenAt);
-    });
-  }
-  return status === "closed" ? granular.listClosedSessions({ environmentId }) : granular.listOpenSessions({ environmentId });
+async function listSessionsForEnvironment(granular, environmentId, options) {
+  return granular.listSessions({
+    environmentId,
+    status: options.status,
+    sessionScope: options.sessionScope,
+    subjectId: options.subjectId,
+    limit: options.limit,
+    offset: options.offset
+  });
 }
 async function connectRuntime(options) {
   if (options.sessionId) {
@@ -26848,6 +27074,19 @@ async function connectTestCommand(options) {
 }
 
 // src/cli/commands/session.ts
+function parseSessionListInteger(value, name) {
+  const fallback2 = name === "limit" ? 25 : 0;
+  const minimum = name === "limit" ? 1 : 0;
+  const maximum = name === "limit" ? 500 : 1e5;
+  if (value === void 0 || value === "") return fallback2;
+  const parsed = typeof value === "number" ? value : Number.parseInt(value.trim(), 10);
+  if (!Number.isInteger(parsed) || String(parsed) !== String(value).trim() || parsed < minimum || parsed > maximum) {
+    throw new Error(
+      `--${name} must be an integer between ${minimum} and ${maximum}.`
+    );
+  }
+  return parsed;
+}
 function printValue(value, emitJson) {
   const json = JSON.stringify(value, null, 2);
   if (emitJson) {
@@ -26932,7 +27171,8 @@ async function sessionCreateCommand(options) {
     createIfMissing: true
   });
   const environment = await granular.createSession({
-    environmentId: envData.environmentId
+    environmentId: envData.environmentId,
+    sessionScope: options.sessionScope
   });
   try {
     const payload = {
@@ -26941,6 +27181,7 @@ async function sessionCreateCommand(options) {
       environmentId: environment.environmentId,
       environment: environment.tag || envData.tag?.name || envData.buildPolicy.tagName || requestedEnvironment,
       sessionId: environment.sessionId,
+      sessionScope: options.sessionScope?.trim() || null,
       subjectId: environment.subjectId,
       versionId: environment.versionId
     };
@@ -26955,6 +27196,7 @@ async function sessionCreateCommand(options) {
       Environment: payload.environment,
       "Environment ID": payload.environmentId,
       "Session ID": payload.sessionId,
+      "Session scope": payload.sessionScope || "unscoped",
       "Subject ID": payload.subjectId,
       "Version ID": payload.versionId
     });
@@ -26970,6 +27212,21 @@ async function sessionCreateCommand(options) {
 async function sessionListCommand(options) {
   const emitJson = options.json === true;
   const status = options.status ?? "active";
+  const allowedStatuses = /* @__PURE__ */ new Set([
+    "active",
+    "closed",
+    "expired",
+    "failed",
+    "timeout",
+    "all"
+  ]);
+  if (!allowedStatuses.has(status)) {
+    throw new Error(
+      "--status must be one of active, closed, expired, failed, timeout, or all."
+    );
+  }
+  const limit = parseSessionListInteger(options.limit, "limit");
+  const offset = parseSessionListInteger(options.offset, "offset");
   const requestedEnvironment = options.environment ?? "dev";
   if (!emitJson) {
     printHeader();
@@ -26979,18 +27236,33 @@ async function sessionListCommand(options) {
     ontology: options.ontology,
     environment: requestedEnvironment,
     environmentId: options.environmentId,
+    subjectId: options.subjectId,
     createIfMissing: false
   });
   const items = await listSessionsForEnvironment(
     granular,
     environmentData.environmentId,
-    status
+    {
+      status,
+      sessionScope: options.sessionScope?.trim() || void 0,
+      subjectId: options.subjectId?.trim() || void 0,
+      limit,
+      offset
+    }
   );
   const payload = {
     ontologyId: environmentData.sandboxId,
     environmentId: environmentData.environmentId,
     environment: environmentData.tag?.name || environmentData.buildPolicy.tagName || requestedEnvironment,
     status,
+    sessionScope: options.sessionScope?.trim() || null,
+    page: {
+      limit,
+      offset,
+      returned: items.length,
+      mayHaveMore: items.length === limit,
+      nextOffset: items.length === limit ? offset + items.length : null
+    },
     items
   };
   if (emitJson) {
@@ -27013,6 +27285,9 @@ async function sessionListCommand(options) {
       item.lastSeenAt
     ])
   );
+  info(
+    `Showing ${items.length} session${items.length === 1 ? "" : "s"} from offset ${offset}.` + (items.length === limit ? ` Use --offset ${offset + items.length} for the next page.` : "")
+  );
   console.log();
 }
 
@@ -27919,6 +28194,9 @@ session.command("create").description(
   "--permissions <list>",
   "Comma-separated permission profile to ensure when a named environment needs to be created",
   "allow-all"
+).option(
+  "--session-scope <scope>",
+  "Application-owned history scope to persist on the new session"
 ).option("--json", "Print machine-readable JSON").action(
   async (options) => {
     try {
@@ -27929,7 +28207,7 @@ session.command("create").description(
     }
   }
 );
-session.command("list").description("List indexed sessions for an environment").option(
+session.command("list").description("List one bounded page of indexed sessions for an environment").option(
   "--ontology <ontologyId>",
   "Override the ontology id from .granularrc"
 ).option(
@@ -27939,11 +28217,17 @@ session.command("list").description("List indexed sessions for an environment").
 ).option(
   "--environment-id <environmentId>",
   "List sessions for this exact environment id"
+).option(
+  "--subject-id <subjectId>",
+  "Resolve and constrain history to this internal Granular subject id"
+).option(
+  "--session-scope <scope>",
+  "Return only sessions owned by this application history scope"
 ).option(
   "--status <status>",
-  "Session status filter: active|closed|all",
+  "Session status: active|closed|expired|failed|timeout|all",
   "active"
-).option("--json", "Print machine-readable JSON").action(
+).option("--limit <count>", "Rows to return (1-500)", "25").option("--offset <count>", "Rows to skip (0-100000)", "0").option("--json", "Print machine-readable JSON").action(
   async (options) => {
     try {
       await sessionListCommand(options);