@granular-software/sdk 0.4.50 → 0.4.52

package/dist/index.mjs

@@ -22,11 +22,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;
 };
@@ -4043,16 +4043,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.load(document) : Automerge.from(document);
+      this.syncState = Automerge.initSyncState();
+      this.emit("sync", this.doc);
+    } catch (error) {
+      console.warn("[Granular] Failed to seed cached session document", error);
+    }
+  }
+  saveDocumentSnapshot() {
+    return Automerge.save(this.doc);
+  }
   clearTokenRefreshTimer() {
     if (this.tokenRefreshTimer) {
       clearTimeout(this.tokenRefreshTimer);
@@ -4162,8 +4183,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) {
@@ -4175,7 +4211,7 @@ var WSClient = class {
       try {
         const wsModule = await Promise.resolve().then(() => (init_wrapper(), wrapper_exports));
         WebSocketClass = wsModule.default || wsModule;
-      } catch (e) {
+      } catch {
       }
     }
     if (!WebSocketClass) {
@@ -4183,83 +4219,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((resolve, 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", {});
-            resolve();
-          });
-          socket.on("message", (data) => {
-            try {
-              const message = JSON.parse(data.toString());
-              this.handleMessage(message);
-            } catch (error) {
-              console.error("[Granular] Failed to parse message:", error);
-            }
-          });
-          socket.on("error", (error) => {
-            this.emit("error", error);
-            if (socket.readyState !== READY_STATE_OPEN) {
-              reject(error);
-            }
-          });
-          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 = (error) => {
+        if (settled) return;
+        settled = true;
+        if (this.cancelConnectAttempt === handleAbort) {
+          this.cancelConnectAttempt = null;
+        }
+        signal?.removeEventListener("abort", handleAbort);
+        if (error) {
+          reject(error instanceof Error ? error : new Error(String(error)));
         } else {
-          this.ws.onopen = () => {
-            if (this.reconnectTimer) {
-              clearTimeout(this.reconnectTimer);
-              this.reconnectTimer = null;
-            }
-            this.reconnectAttempts = 0;
-            this.emit("open", {});
-            resolve();
-          };
-          this.ws.onmessage = (event) => {
-            try {
-              const data = event.data;
-              const message = JSON.parse(data.toString());
-              this.handleMessage(message);
-            } catch (error) {
-              console.error("[Granular] Failed to parse message:", error);
-            }
-          };
-          this.ws.onerror = (event) => {
-            const error = new Error("WebSocket error");
-            error.event = event;
-            this.emit("error", error);
-            if (this.ws?.readyState !== READY_STATE_OPEN) {
-              reject(error);
-            }
-          };
-          this.ws.onclose = (event) => {
-            this.handleDisconnect({
-              code: event.code,
-              reason: event.reason,
-              wasClean: event.wasClean
-            });
-          };
+          resolve();
         }
-      } catch (error) {
-        reject(error);
+      };
+      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 (error) {
+          console.error("[Granular] Failed to parse message:", error);
+        }
+      };
+      const handleError = (error) => {
+        if (!isCurrent()) return;
+        const typedError = error instanceof Error ? error : 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);
       }
     });
   }
@@ -4277,9 +4327,58 @@ var WSClient = class {
     return void 0;
   }
   rejectPending(error) {
-    this.messageQueue.forEach((pending) => pending.reject(error));
+    this.messageQueue.forEach((pending) => {
+      clearTimeout(pending.timeout);
+      pending.reject(error);
+    });
     this.messageQueue = [];
   }
+  emitReconnectErrorMessage(error) {
+    const reconnectInfo = {
+      error,
+      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((error) => {
+        console.error("[Granular] Reconnect failed:", error);
+        this.emitReconnectErrorMessage(
+          error instanceof Error ? error.message : String(error)
+        );
+        this.scheduleReconnectAttempt();
+      });
+    }, reconnectDelayMs);
+    return reconnectDelayMs;
+  }
   buildDisconnectError(info) {
     const details = [
       info.code !== void 0 ? `code=${info.code}` : void 0,
@@ -4289,8 +4388,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 info = {
       code: close.code,
@@ -4310,32 +4407,9 @@ var WSClient = class {
       const disconnectError = this.buildDisconnectError(info);
       this.rejectPending(disconnectError);
       this.emit("disconnect", info);
-      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)
-      );
-      info.reconnectScheduled = true;
-      info.reconnectDelayMs = reconnectDelayMs;
+      const reconnectDelayMs = this.scheduleReconnectAttempt();
+      info.reconnectScheduled = reconnectDelayMs !== null;
+      if (reconnectDelayMs !== null) info.reconnectDelayMs = reconnectDelayMs;
       if (this.options.onUnexpectedClose) {
         try {
           this.options.onUnexpectedClose(info);
@@ -4346,28 +4420,6 @@ var WSClient = class {
           );
         }
       }
-      this.reconnectTimer = setTimeout(() => {
-        console.log("[Granular] Attempting reconnect...");
-        this.connect().catch((error) => {
-          console.error("[Granular] Reconnect failed:", error);
-          const reconnectInfo = {
-            error: error instanceof Error ? error.message : String(error),
-            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) {
@@ -4478,6 +4530,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(
@@ -4523,16 +4576,22 @@ var WSClient = class {
       id
     };
     return new Promise((resolve, reject) => {
-      this.messageQueue.push({ resolve, 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, reject, id, timeout });
+      try {
+        this.ws.send(JSON.stringify(request));
+      } catch (error) {
+        clearTimeout(timeout);
+        this.messageQueue = this.messageQueue.filter((q) => q.id !== id);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
     });
   }
   async handleIncomingRpc(request) {
@@ -4618,15 +4677,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"));
@@ -4722,8 +4784,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 : "",
@@ -4810,6 +4876,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;
@@ -5715,6 +5784,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",
@@ -6373,9 +6443,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(
+      (table) => Boolean(
+        table && typeof table === "object" && !Array.isArray(table) && Array.isArray(table.columns) && Array.isArray(table.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;
@@ -6397,6 +6472,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, fallback = "") {
   if (typeof value === "string") {
     return value.trim() || fallback;
@@ -6555,10 +6700,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}
@@ -6573,6 +6720,8 @@ ${content}` : artifactHistory : void 0;
     jobId: asString(record.jobId),
     promptId: asString(record.promptId),
     show,
+    actions,
+    parts,
     historyContent,
     source: "conversation"
   };
@@ -12150,7 +12299,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`,
@@ -13078,11 +13232,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)
     },
     {
@@ -13430,7 +13593,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
           },
           add_transition: async (value, {
             name,
-            from,
+            from: from2,
             to,
             label,
             description,
@@ -13445,7 +13608,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
               value.target.add_state_machine_transition(
                 value.name,
                 name,
-                from,
+                from2,
                 to,
                 {
                   label,
@@ -13895,6 +14058,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, fallback, minimum, maximum) {
+  if (value === void 0) return fallback;
+  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",
@@ -14112,7 +14287,8 @@ function normalizeEnvironmentSetupSummary(setup) {
     environmentId: String(setup.environmentId || ""),
     sandboxId: String(setup.sandboxId || ""),
     subjectId: String(setup.subjectId || ""),
-    triggerReason: setup.triggerReason === "fresh_after_version_update" ? "fresh_after_version_update" : "new_environment",
+    triggerReason: setup.triggerReason === "fresh_after_version_update" ? "fresh_after_version_update" : setup.triggerReason === "explicit_reset" ? "explicit_reset" : "new_environment",
+    operationKey: typeof setup.operationKey === "string" ? setup.operationKey : null,
     lifecycleStatus: setup.lifecycleStatus === "completed" || setup.lifecycleStatus === "failed" ? setup.lifecycleStatus : "running",
     stage: typeof setup.stage === "string" ? setup.stage : null,
     totalObjectsToImport: Number(setup.totalObjectsToImport || 0),
@@ -14233,7 +14409,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),
@@ -14368,17 +14544,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({
@@ -14396,6 +14567,7 @@ var Environment = class _Environment {
     return this.granular.createSession({
       environmentId: this.environmentId,
       clientId: options?.clientId,
+      sessionScope: options?.sessionScope,
       initialHeap: options?.initialHeap
     });
   }
@@ -15398,6 +15570,7 @@ var Environment = class _Environment {
           records: recordsToImport,
           batchSize: options.batchSize,
           setupRunId: options.setupRunId,
+          operationKey: options.operationKey,
           writeMode: options.writeMode
         })
       }
@@ -15958,7 +16131,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()`.
@@ -16202,6 +16375,107 @@ var Granular = class _Granular {
     await this.maybeRunEnvironmentImporter(resolved, environment);
     return environment;
   }
+  /**
+   * Read the active environment selected by Granular for an already-recorded
+   * external user. This is intentionally read-only: browser/login code must
+   * not create subjects or environments as a side effect.
+   */
+  async getActiveEnvironmentForUser(options) {
+    const sandboxId = options.sandboxId.trim();
+    const tagName = options.tag.trim();
+    const userId = options.userId.trim();
+    if (!sandboxId || !tagName || !userId) {
+      throw new Error(
+        "getActiveEnvironmentForUser() requires sandboxId, tag, and userId."
+      );
+    }
+    const subjects = await this.request(
+      `/control/subjects?identityId=${encodeURIComponent(userId)}`
+    );
+    const subject = (subjects.items || []).find(
+      (item) => item.identityId === userId || item.userId === userId
+    );
+    if (!subject?.subjectId && !subject?.granularId) {
+      return null;
+    }
+    const subjectId = subject.subjectId || subject.granularId;
+    const tags = await this.request(
+      `/control/sandboxes/${encodeURIComponent(sandboxId)}/tags`
+    );
+    const tag = (tags.items || []).find(
+      (item) => item?.name === tagName
+    );
+    if (!tag) return null;
+    const query = new URLSearchParams({
+      tagId: tag.tagId,
+      slot: options.slot?.trim() || "default"
+    });
+    try {
+      const payload = await this.request(
+        `/control/sandboxes/${encodeURIComponent(sandboxId)}/subjects/${encodeURIComponent(subjectId)}/active-environment?${query.toString()}`
+      );
+      return payload.environment ? this.bindEnvironmentHandle(
+        normalizeEnvironmentData(payload.environment)
+      ) : null;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (message.includes("404") || message.includes("not found")) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  /**
+   * Register one reviewed, pre-existing environment as the active workspace
+   * for an external user. This is for a controlled migration only: it does
+   * not create an environment and it does not run an importer.
+   */
+  async adoptEnvironmentForUser(options) {
+    const sandboxId = options.sandboxId.trim();
+    const tagName = options.tag.trim();
+    const userId = options.userId.trim();
+    const environmentId = options.environmentId.trim();
+    if (!sandboxId || !tagName || !userId || !environmentId) {
+      throw new Error(
+        "adoptEnvironmentForUser() requires sandboxId, tag, userId, and environmentId."
+      );
+    }
+    const subjects = await this.request(
+      `/control/subjects?identityId=${encodeURIComponent(userId)}`
+    );
+    const subject = (subjects.items || []).find(
+      (item) => item.identityId === userId || item.userId === userId
+    );
+    if (!subject?.subjectId && !subject?.granularId) {
+      throw new Error(`No Granular subject exists for user ${userId}.`);
+    }
+    const tags = await this.request(`/control/sandboxes/${encodeURIComponent(sandboxId)}/tags`);
+    const tag = (tags.items || []).find(
+      (item) => item?.name === tagName
+    );
+    if (!tag) {
+      throw new Error(`Tag ${tagName} was not found in sandbox ${sandboxId}.`);
+    }
+    const payload = await this.request(
+      "/control/environment-activations/adopt",
+      {
+        method: "POST",
+        body: JSON.stringify({
+          environmentId,
+          subjectId: subject.subjectId || subject.granularId,
+          tagId: tag.tagId,
+          slot: options.slot?.trim() || "default",
+          confirmExistingData: true
+        })
+      }
+    );
+    if (!payload.environment) {
+      throw new Error("Granular did not return the adopted environment.");
+    }
+    return this.bindEnvironmentHandle(
+      normalizeEnvironmentData(payload.environment)
+    );
+  }
   /**
    * Deprecated compatibility alias for `openEnvironment()`.
    *
@@ -16233,7 +16507,9 @@ var Granular = class _Granular {
         requestedOntology,
         sandboxId: environmentData.sandboxId,
         subjectId: environmentData.subjectId,
-        setupTriggerReason: options.reason || "new_environment"
+        externalUserId: environmentData.subjectId,
+        setupTriggerReason: options.reason || "new_environment",
+        setupOperationKey: options.operationKey
       },
       environment
     );
@@ -16245,20 +16521,17 @@ var Granular = class _Granular {
     }
     return tag;
   }
-  buildManagedEnvironmentName(tag, versionId) {
-    return `__sdk__${tag}__${versionId}__pinned`;
+  buildManagedEnvironmentName(tag, versionId, resetKey) {
+    if (!resetKey) {
+      return `__sdk__${tag}__${versionId}__tracked`;
+    }
+    const safeResetKey = resetKey.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 80);
+    return `__sdk__${tag}__${versionId}__reset__${safeResetKey}`;
   }
   isManagedEnvironmentName(environment, tagName) {
     const name = environment.environment || environment.envName || "";
     return name.startsWith(`__sdk__${tagName}__`);
   }
-  isPinnedToVersion(environment, versionId) {
-    return environment.buildPolicy.mode === "pinned" && (environment.versionId === versionId || environment.buildPolicy.versionId === versionId || environment.buildPolicy.buildId === versionId);
-  }
-  matchesTagTrackedEnvironment(environment, tagName, tagId) {
-    const environmentTagName = environment.tag?.name || environment.buildPolicy.tagName || null;
-    return environment.tagId === tagId || environmentTagName === tagName || environment.environment === tagName || environment.envName === tagName || environment.environment === this.buildManagedEnvironmentName(tagName, environment.versionId) || environment.envName === this.buildManagedEnvironmentName(tagName, environment.versionId);
-  }
   sortEnvironmentsByRecency(environments) {
     return [...environments].sort(
       (left, right) => right.updatedAt - left.updatedAt
@@ -16308,61 +16581,187 @@ var Granular = class _Granular {
         `Tag "${tagName}" does not currently point to a build/version.`
       );
     }
+    const slot = options.slot?.trim() || "default";
+    const resetKey = options.resetKey?.trim() || void 0;
+    const resolveActive = async (operationKey) => {
+      const query = new URLSearchParams({ tagId: tag.tagId, slot });
+      if (operationKey) query.set("operationKey", operationKey);
+      try {
+        const payload = await this.request(
+          `/control/sandboxes/${encodeURIComponent(sandbox.sandboxId)}/subjects/${encodeURIComponent(user.granularId)}/active-environment?${query.toString()}`
+        );
+        return payload.environment ? normalizeEnvironmentData(payload.environment) : null;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("404") || message.includes("not found")) {
+          return null;
+        }
+        throw error;
+      }
+    };
+    const activate = async (environment2) => {
+      const payload = await this.request(
+        "/control/environment-activations",
+        {
+          method: "POST",
+          body: JSON.stringify({
+            environmentId: environment2.environmentId,
+            tagId: tag.tagId,
+            slot,
+            operationKey: resetKey,
+            operation: resetKey ? "explicit_reset" : void 0
+          })
+        }
+      );
+      return normalizeEnvironmentData(payload.environment);
+    };
+    if (resetKey) {
+      const resetEnvironment = await resolveActive(resetKey);
+      if (resetEnvironment) {
+        return {
+          environment: resetEnvironment,
+          requestedOntology: ontology,
+          sandboxId: sandbox.sandboxId,
+          subjectId: user.granularId,
+          externalUserId: user.userId,
+          // Retrying an explicit reset must also resume its durable setup run.
+          // Otherwise a Container crash after queue submission would leave a
+          // valid environment permanently marked as "running".
+          setupTriggerReason: "explicit_reset",
+          setupOperationKey: resetKey
+        };
+      }
+    } else {
+      const active = await resolveActive();
+      if (active && (active.versionId === targetVersionId || options.createFreshIfOutdated !== true)) {
+        return {
+          environment: active,
+          requestedOntology: ontology,
+          sandboxId: sandbox.sandboxId,
+          subjectId: user.granularId,
+          externalUserId: user.userId
+        };
+      }
+    }
     const allEnvironments = await this.environments.list(sandbox.sandboxId);
     const userEnvironments = allEnvironments.filter(
-      (environment) => environment.subjectId === user.granularId
+      (environment2) => environment2.subjectId === user.granularId
     );
     const currentMatches = this.sortEnvironmentsByRecency(
       userEnvironments.filter(
-        (environment) => this.matchesTagTrackedEnvironment(environment, tagName, tag.tagId) && environment.versionId === targetVersionId && (!this.isManagedEnvironmentName(environment, tagName) || this.isPinnedToVersion(environment, targetVersionId))
+        (environment2) => environment2.tagId === tag.tagId && environment2.versionId === targetVersionId
       )
     );
-    if (currentMatches.length > 0) {
+    if (!resetKey && currentMatches.length > 0) {
+      const environment2 = await activate(currentMatches[0]);
       return {
-        environment: currentMatches[0],
+        environment: environment2,
         requestedOntology: ontology,
         sandboxId: sandbox.sandboxId,
-        subjectId: user.granularId
+        subjectId: user.granularId,
+        externalUserId: user.userId
       };
     }
     const outdatedMatches = this.sortEnvironmentsByRecency(
-      userEnvironments.filter(
-        (environment) => this.matchesTagTrackedEnvironment(environment, tagName, tag.tagId)
-      )
+      userEnvironments.filter((environment2) => environment2.tagId === tag.tagId)
     );
     if (outdatedMatches.length > 0 && options.createFreshIfOutdated !== true) {
+      const environment2 = await activate(outdatedMatches[0]);
       return {
-        environment: outdatedMatches[0],
+        environment: environment2,
         requestedOntology: ontology,
         sandboxId: sandbox.sandboxId,
-        subjectId: user.granularId
+        subjectId: user.granularId,
+        externalUserId: user.userId
       };
     }
+    const created = await this.environments.create(sandbox.sandboxId, {
+      subjectId: user.granularId,
+      environment: this.buildManagedEnvironmentName(
+        tagName,
+        targetVersionId,
+        resetKey
+      ),
+      tagId: tag.tagId,
+      permissionProfileId: null
+    });
+    const environment = await activate(created);
     return {
-      environment: await this.environments.create(sandbox.sandboxId, {
-        subjectId: user.granularId,
-        environment: this.buildManagedEnvironmentName(tagName, targetVersionId),
-        tagId: tag.tagId,
-        versionId: targetVersionId,
-        permissionProfileId: null
-      }),
+      environment,
       requestedOntology: ontology,
       sandboxId: sandbox.sandboxId,
       subjectId: user.granularId,
-      setupTriggerReason: outdatedMatches.length > 0 ? "fresh_after_version_update" : "new_environment"
+      externalUserId: user.userId,
+      setupTriggerReason: resetKey ? "explicit_reset" : outdatedMatches.length > 0 ? "fresh_after_version_update" : "new_environment",
+      setupOperationKey: resetKey
     };
   }
   /**
-   * 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({
@@ -16397,14 +16796,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 ?? "");
@@ -16463,6 +16854,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);
@@ -16471,6 +16863,8 @@ var Granular = class _Granular {
       body: JSON.stringify({
         environmentId: options.environmentId,
         clientId,
+        sessionScope,
+        capabilities: sessionScope ? { sessionScope } : void 0,
         initialHeap: options.initialHeap
       })
     });
@@ -16578,11 +16972,24 @@ var Granular = class _Granular {
       {
         method: "POST",
         body: JSON.stringify({
-          triggerReason: resolved.setupTriggerReason
+          triggerReason: resolved.setupTriggerReason,
+          operationKey: resolved.setupOperationKey
         })
       }
     );
     const setupRunId = setupRun.setupRunId;
+    let claim = null;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      claim = await this.request(
+        `/control/environment-setup-runs/${setupRunId}/importer-claim`,
+        { method: "POST", body: JSON.stringify({}) }
+      );
+      if (claim.action !== "busy") break;
+      await sleep(Math.min(3e4, Math.max(250, claim.retryAfterMs || 1e3)));
+    }
+    if (!claim) {
+      throw new Error(`Unable to claim environment setup run ${setupRunId}.`);
+    }
     const updateSetupRun = async (patch) => {
       await this.request(
         `/control/environment-setup-runs/${setupRunId}`,
@@ -16592,10 +16999,26 @@ var Granular = class _Granular {
         }
       );
     };
+    if (claim.action === "submitted") {
+      const completedSetupRun = await this.request(
+        `/control/environment-setup-runs/${setupRunId}`,
+        { method: "PATCH", body: JSON.stringify({ markHookCompleted: true }) }
+      );
+      const refreshedEnvironment = await this.environments.get(
+        environment.environmentId
+      );
+      environment.syncEnvironmentData(refreshedEnvironment);
+      return completedSetupRun;
+    }
+    if (claim.action === "busy" || claim.action === "terminal") {
+      return claim.summary;
+    }
+    let importSequence = 0;
     const importerContext = {
       environmentId: environment.environmentId,
       sandboxId: environment.sandboxId,
       subjectId: environment.subjectId,
+      externalUserId: resolved.externalUserId,
       reason: resolved.setupTriggerReason,
       incrementTotalObjectsToImportCount: async (n) => {
         const safeIncrement = Math.max(0, Math.trunc(n));
@@ -16612,7 +17035,10 @@ var Granular = class _Granular {
       importRecords: async (records, options) => environment.enqueueRecordImport(records, {
         batchSize: options?.batchSize,
         writeMode: options?.writeMode,
-        setupRunId
+        setupRunId,
+        // Sequence is deterministic for a retry of one importer hook. It
+        // prevents a Container restart from creating a second queue import.
+        operationKey: `${setupRunId}:import:${importSequence++}`
       })
     };
     try {
@@ -19662,6 +20088,7 @@ function buildGranularAgentSystemPrompt(input) {
   - \`groundedObjects.save(...)\` only accepts scalar values, session files, runtime records/sandbox instances, or arrays of runtime records/sandbox instances from one class. Do not save plain action/effect result objects; fetch affected records first or answer from summaries with \`replyToUser(...)\`.
   - Do not use \`showObjects({ entries: [...] })\` or \`showObjects({ saveAs, entries })\`. Save ordered pages, queues, search results, or ranked lists with \`groundedObjects.save(...)\`, then call \`showObjects({ variableNames: [...] })\` once.
   - Use \`showAgentResponse({ reply, show: [record, action] })\` when one assistant message should combine text, grounded records, files, prepared actions, or action suggestions. The \`action\` can be a state handle such as \`record.lifecycle.approved\` or an action handle such as \`record.lifecycle.approved.reach()\`.
+  - Pass grounded records directly in \`show\` when the default record presentation answers the request. When the user asks for particular columns, comparisons, or computed values, import \`table\` (and \`relativeTime\` when useful) from \`@granular/agent\` and call \`showAgentResponse({ reply, show: table(records, [{ label: "Object", value: record => record.label }, { label: "When", value: record => relativeTime(record.timestamp) }]) })\`. Column callbacks must be synchronous and return a scalar, \`Date\`, or \`relativeTime(...)\`; they run inside the job and only resolved cells are persisted.
   - Do not use deprecated side-channel helpers such as \`agent_text_message(...)\`, \`agent_heap_objects(...)\`, or \`agent_message(...)\` unless the generated types expose no Harness v3 helper alternative.
   - When the user asks to show, list, display, open, or "show them" for records you found, call \`showObjects(...)\`; do not answer only with a count or text summary.
   - For count-only questions such as "how many", "how many X do I have", or "what is the total number of X", call the entity \`.count(...)\` or use page \`totalCount\` only when a page is already needed for other reasons. Answer with \`replyToUser(...)\` only. Do not call \`showObjects(...)\`, \`saveAs\`, or \`groundedObjects.save(...)\` unless the user also asked to see records or a later requested action needs a reusable record selection.
@@ -19932,11 +20359,12 @@ ${actionIndex}
 - Use typed plan fields and helpers directly. For visible blocker text, use the declared blocker-formatting helper when available instead of hand-written object casts.
 - A suggestion is a recommendation button: \`await stateHandle.suggest(message)\`. A prepared action is the editable form the user can review/run: \`const action = stateHandle.reach(); const prepared = await action.open()\`.
 - Use suggestions when the user asks "what can I do next?", asks for options, or gives an unclear intent. Prefer 2 to 5 concrete suggestions and keep text short.
-- Open a prepared action when the user asks for one clear action. Prefill only values grounded in the user request, conversation, files, selected records, or fresh reads. Leave unknown fields empty; do not invent them.
+- Opening a prepared action does not execute the underlying mutation. Use \`.open()\` only when the user asks to prepare, review, show, or edit an action before running it, when a new record must be prepared, or when a reviewable form must collect missing editable inputs. Prefill only grounded values and leave unknown fields empty.
+- When the user explicitly commands an existing-record mutation such as approve, reject, block, route, send, or update, and one visible domain action uniquely matches, call that domain action directly. Do not substitute a state-handle \`.open()\` artifact for execution. If runtime policy requires confirmation, invoke the action once and let the runtime pause and resume that same invocation.
 - When a grounded related/context record can satisfy the prepared action through declared relationships, use those relationships to fill required relationship inputs before opening or updating the action. If a required relationship remains empty, continue through declared relationship chains from the grounded object when the next hop can fill that slot. Do not only save the context record in memory while leaving derivable relationship slots blank.
 - A derived intermediate relationship is not enough when another required relationship is still reachable from it. For example, if a team gives a cost center and the action also requires a budget, traverse the cost center's declared budget relationship before opening the action.
 - If the user says they have a document/work item/event but no matching record is found, check for a declared class-level new-record state/action handle or importable backend create/preparation action for that named class before giving up. Use grounded required fields to open the prepared action or call the create/preparation action; if required values are still missing and no prepared action can collect them, ask only for those values. Do not claim the record already exists.
-- Do not ask for confirmation before opening a prepared action. The prepared action is itself reviewable. Use \`userInteraction.askConfirmation\` only when the user explicitly asks for yes/no approval, the selected action is ambiguous after grounding, or the domain/runtime asks for confirmation.
+- Do not ask for confirmation before opening a prepared action requested for review; the artifact is itself reviewable. For a direct mutation command, do not open an artifact merely to obtain confirmation. Use \`userInteraction.askConfirmation\` only when the user explicitly asks for a separate yes/no step, material ambiguity remains after grounding, or policy requires confirmation outside the invoked action runtime.
 - If the action cannot continue because of missing input, stale state, missing relationships, related-state requirements, or permissions, keep/show the prepared action at that blocker and explain the next needed person, record, or value. Do not skip workflow steps or target a later state.
 - Reuse an already-open prepared action for the same target/action when available: update it, show it again, or explain what is still needed instead of creating a duplicate.
 - If an open prepared action needs edits, prefer the returned record helper: \`const prepared = await action.open(); await prepared.updateInputs({ inputValues, relationships });\`. Use \`artifacts.updateInputs(id, patch)\` only when you only have an id.
@@ -20166,8 +20594,9 @@ function buildContinuationInstructionFromTemplate(resultPreview, options) {
 }
 
 // src/openai-usage.ts
-var OPENAI_PRICING_SOURCE_URL = "https://developers.openai.com/api/docs/models/gpt-5.4/";
-var OPENAI_PRICING_EFFECTIVE_DATE = "2026-05-19";
+var OPENAI_GPT_5_4_PRICING_SOURCE_URL = "https://developers.openai.com/api/docs/models/gpt-5.4/";
+var OPENAI_GPT_5_6_PRICING_SOURCE_URL = "https://developers.openai.com/api/docs/pricing";
+var OPENAI_LONG_CONTEXT_THRESHOLD_TOKENS = 272e3;
 var OPENAI_MODEL_PRICING_USD_PER_MILLION = {
   "gpt-5.4": {
     provider: "openai",
@@ -20176,8 +20605,26 @@ var OPENAI_MODEL_PRICING_USD_PER_MILLION = {
     inputUsdPerMillion: 2.5,
     cachedInputUsdPerMillion: 0.25,
     outputUsdPerMillion: 15,
-    sourceUrl: OPENAI_PRICING_SOURCE_URL,
-    effectiveDate: OPENAI_PRICING_EFFECTIVE_DATE
+    sourceUrl: OPENAI_GPT_5_4_PRICING_SOURCE_URL,
+    effectiveDate: "2026-05-19"
+  },
+  "gpt-5.6-luna": {
+    provider: "openai",
+    model: "gpt-5.6-luna",
+    currency: "USD",
+    inputUsdPerMillion: 1,
+    cachedInputUsdPerMillion: 0.1,
+    cacheWriteUsdPerMillion: 1.25,
+    outputUsdPerMillion: 6,
+    sourceUrl: OPENAI_GPT_5_6_PRICING_SOURCE_URL,
+    effectiveDate: "2026-07-11",
+    longContextThresholdTokens: OPENAI_LONG_CONTEXT_THRESHOLD_TOKENS,
+    longContextPricing: {
+      inputUsdPerMillion: 2,
+      cachedInputUsdPerMillion: 0.2,
+      cacheWriteUsdPerMillion: 2.5,
+      outputUsdPerMillion: 9
+    }
   }
 };
 function asRecord5(value) {
@@ -20190,8 +20637,18 @@ function numberField(record, key) {
 function microsPerMillion(usdPerMillion) {
   return Math.round(usdPerMillion * 1e6);
 }
-function getOpenAIModelPricing(model) {
-  return OPENAI_MODEL_PRICING_USD_PER_MILLION[model] || null;
+function getOpenAIModelPricing(model, inputTokens = 0) {
+  const pricing = OPENAI_MODEL_PRICING_USD_PER_MILLION[model];
+  if (!pricing) return null;
+  const threshold = pricing.longContextThresholdTokens ?? null;
+  if (pricing.longContextPricing && typeof threshold === "number" && inputTokens > threshold) {
+    return {
+      ...pricing,
+      ...pricing.longContextPricing,
+      contextTier: "long"
+    };
+  }
+  return { ...pricing, contextTier: "short" };
 }
 function normalizeOpenAIUsage(rawUsage) {
   const usage = asRecord5(rawUsage);
@@ -20199,6 +20656,7 @@ function normalizeOpenAIUsage(rawUsage) {
     return {
       inputTokens: 0,
       cachedInputTokens: 0,
+      cacheWriteTokens: 0,
       uncachedInputTokens: 0,
       outputTokens: 0,
       reasoningTokens: 0,
@@ -20214,20 +20672,28 @@ function normalizeOpenAIUsage(rawUsage) {
     inputTokens,
     numberField(inputDetails, "cached_tokens") || numberField(inputDetails, "cached_input_tokens")
   );
+  const cacheWriteTokens = Math.min(
+    Math.max(inputTokens - cachedInputTokens, 0),
+    numberField(inputDetails, "cache_write_tokens")
+  );
   const reasoningTokens = numberField(outputDetails, "reasoning_tokens") || numberField(outputDetails, "reasoning_output_tokens");
   return {
     inputTokens,
     cachedInputTokens,
-    uncachedInputTokens: Math.max(inputTokens - cachedInputTokens, 0),
+    cacheWriteTokens,
+    uncachedInputTokens: Math.max(
+      inputTokens - cachedInputTokens - cacheWriteTokens,
+      0
+    ),
     outputTokens,
     reasoningTokens,
     totalTokens
   };
 }
 function calculateOpenAITokenSpend(model, rawUsage) {
-  const pricing = getOpenAIModelPricing(model);
-  if (!pricing) return null;
   const usage = normalizeOpenAIUsage(rawUsage);
+  const pricing = getOpenAIModelPricing(model, usage.inputTokens);
+  if (!pricing) return null;
   const inputPricePerMillionMicros = microsPerMillion(
     pricing.inputUsdPerMillion
   );
@@ -20237,14 +20703,19 @@ function calculateOpenAITokenSpend(model, rawUsage) {
   const outputPricePerMillionMicros = microsPerMillion(
     pricing.outputUsdPerMillion
   );
+  const cacheWritePricePerMillionMicros = typeof pricing.cacheWriteUsdPerMillion === "number" ? microsPerMillion(pricing.cacheWriteUsdPerMillion) : null;
+  const cacheWriteCostMicros = Math.round(
+    usage.cacheWriteTokens * (cacheWritePricePerMillionMicros ?? inputPricePerMillionMicros) / 1e6
+  );
   const amountMicros = Math.round(
-    (usage.uncachedInputTokens * inputPricePerMillionMicros + usage.cachedInputTokens * cachedInputPricePerMillionMicros + usage.outputTokens * outputPricePerMillionMicros) / 1e6
+    (usage.uncachedInputTokens * inputPricePerMillionMicros + usage.cachedInputTokens * cachedInputPricePerMillionMicros + usage.cacheWriteTokens * (cacheWritePricePerMillionMicros ?? inputPricePerMillionMicros) + usage.outputTokens * outputPricePerMillionMicros) / 1e6
   );
   return {
     provider: "openai",
     model,
     inputTokens: usage.inputTokens,
     cachedInputTokens: usage.cachedInputTokens,
+    cacheWriteTokens: usage.cacheWriteTokens,
     uncachedInputTokens: usage.uncachedInputTokens,
     outputTokens: usage.outputTokens,
     reasoningTokens: usage.reasoningTokens,
@@ -20253,7 +20724,11 @@ function calculateOpenAITokenSpend(model, rawUsage) {
     currency: "USD",
     inputPricePerMillionMicros,
     cachedInputPricePerMillionMicros,
+    cacheWritePricePerMillionMicros,
+    cacheWriteCostMicros,
     outputPricePerMillionMicros,
+    pricingContextTier: pricing.contextTier || "short",
+    longContextThresholdTokens: pricing.longContextThresholdTokens ?? null,
     pricingSource: pricing.sourceUrl,
     pricingEffectiveAt: pricing.effectiveDate,
     usage