@granular-software/sdk 0.4.65 → 0.4.67

package/dist/cli/index.js

@@ -14505,6 +14505,7 @@ function mergeClassSummaryPatch(target, patch) {
 function mergePropertySummaryPatch(target, patch) {
   pushUnique(target.notes, patch.notes || []);
   if (patch.searchable !== void 0) target.searchable = patch.searchable;
+  if (patch.format !== void 0) target.format = patch.format;
   if (patch.searchablePhonetic !== void 0) {
     target.searchablePhonetic = patch.searchablePhonetic;
   }
@@ -16246,6 +16247,91 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
   }
 });
 
+// ../metamodel-temporal/src/index.ts
+function normalizeTemporalFormat(format) {
+  return format === "date" || format === "date-time" ? format : null;
+}
+function buildTemporalFieldMutations(fieldPath, format) {
+  const normalized = normalizeTemporalFormat(format);
+  if (!normalized) return [];
+  return [
+    {
+      label: `set temporal format on ${fieldPath}`,
+      query: `mutation { at(path: ${JSON.stringify(fieldPath)}) { set_temporal_format(format: ${JSON.stringify(normalized)}) { format } } }`
+    }
+  ];
+}
+var temporalMetamodelPackage = defineMetamodelPackage({
+  id: "temporal",
+  docs: {
+    fieldRows: [
+      {
+        key: "format",
+        description: "Temporal representation for date fields. Use `date` for a civil calendar date and `date-time` when the instant and time matter."
+      }
+    ]
+  },
+  graphql: {
+    typeDefs: [
+      `
+      type TemporalFormatMetamodel {
+        model: Model!
+        format: String!
+      }
+
+      extend type Model {
+        temporal_format: TemporalFormatMetamodel
+      }
+
+      extend type ModelMutation {
+        set_temporal_format(format: String!): TemporalFormatMetamodel
+      }
+      `
+    ],
+    createResolvers({ run }) {
+      return {
+        TemporalFormatMetamodel: {
+          model: (value) => value.model,
+          format: (value) => value.format
+        },
+        Model: {
+          temporal_format: async (ant) => await run(ant.temporal_format())
+        },
+        ModelMutation: {
+          set_temporal_format: async (ant, { format }) => {
+            if (format !== "date" && format !== "date-time") {
+              throw new Error(`Unsupported temporal format: ${format}`);
+            }
+            return {
+              model: await run(ant.set_temporal_format(format)),
+              format
+            };
+          }
+        }
+      };
+    }
+  },
+  manifest: {
+    buildFieldMutations(fieldPath, spec) {
+      return buildTemporalFieldMutations(fieldPath, spec.format);
+    }
+  },
+  summary: {
+    selections: {
+      propertyFields: ["temporal_format { format }"]
+    },
+    readPropertySummary(rawProperty) {
+      const format = rawProperty.temporal_format?.format;
+      return format === "date" || format === "date-time" ? { format } : {};
+    }
+  },
+  domain: {
+    applyToPropertyIR(propertyIR, _propertySummary) {
+      return propertyIR;
+    }
+  }
+});
+
 // ../metamodel-validation-rule/src/index.ts
 function describeRule(rule) {
   if (rule.message) return rule.message;
@@ -16417,6 +16503,7 @@ var DEFAULT_METAMODEL_PACKAGES = [
   searchableMetamodelPackage,
   validationRuleMetamodelPackage,
   stateMachineMetamodelPackage,
+  temporalMetamodelPackage,
   effectBehaviorsMetamodelPackage,
   policyMetamodelPackage
 ];
@@ -16551,6 +16638,7 @@ Each key under \`has\` is a **field name** on the class. Each value is a **field
 | Property | Required? | Purpose |
 |----------|-----------|---------|
 | \`type\` | **Yes** for normal scalar fields | \`string\`, \`number\`, \`boolean\`, \`email\`, \`url\`, \`date\`, etc. |
+| \`format\` | For temporal fields | Use \`date\` for a civil calendar date; use \`date-time\` when the time and instant matter. |
 | \`description\` | Strongly recommended | Used in docs and UX. |
 | \`value\` | Optional | **Default** baked into the model (static metadata), not per-record data. Rare for entity fields. |
 | \`ref\` | Optional | Advanced reference. Prefer \`defineRelationship\` for links between entities. |
@@ -20883,7 +20971,6 @@ var DEFAULT_RPC_TIMEOUT_MS = 3e4;
 var DOMAIN_PACKAGE_RPC_TIMEOUT_MS = 12e4;
 var EFFECT_CONTROL_RPC_TIMEOUT_MS = 12e4;
 var HARNESS_RUN_RPC_TIMEOUT_MS = 6e5;
-var HEARTBEAT_RPC_TIMEOUT_MS = 15e3;
 var DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
 var DEFAULT_RECONNECT_DELAY_MS = 3e3;
 var DEFAULT_MAX_RECONNECT_ATTEMPTS = 5;
@@ -20929,8 +21016,6 @@ function rpcTimeoutMsForMethod(method) {
     case "domain.fetchPackagePart":
     case "domain.getSummary":
       return DOMAIN_PACKAGE_RPC_TIMEOUT_MS;
-    case "client.heartbeat":
-      return HEARTBEAT_RPC_TIMEOUT_MS;
     case "effects.publishCatalog":
     case "effects.resetCatalog":
     case "effects.addCatalog":
@@ -20950,6 +21035,7 @@ var WSClient = class {
   sessionId;
   token;
   messageQueue = [];
+  pendingRpcPeriodStartedAt = null;
   rpcHandlers = /* @__PURE__ */ new Map();
   eventHandlers = /* @__PURE__ */ new Map();
   canonicalDocumentQuarantineHandlers = /* @__PURE__ */ new Set();
@@ -20964,6 +21050,7 @@ var WSClient = class {
   cancelConnectAttempt = null;
   documentRepairRequired = false;
   canonicalDocumentActivated = false;
+  lastInboundActivityAt = null;
   options;
   constructor(options) {
     this.options = options;
@@ -20977,6 +21064,29 @@ var WSClient = class {
   get currentSessionId() {
     return this.sessionId;
   }
+  isTransportOpen() {
+    return this.ws?.readyState === READY_STATE_OPEN;
+  }
+  hasPendingRpcRequests() {
+    return this.messageQueue.length > 0;
+  }
+  hasRecentlyPendingRpcPeriod(maxAgeMs, now = Date.now()) {
+    return this.messageQueue.length > 0 && this.pendingRpcPeriodStartedAt !== null && now - this.pendingRpcPeriodStartedAt <= maxAgeMs;
+  }
+  removePendingRpc(id) {
+    this.messageQueue = this.messageQueue.filter(
+      (pending) => pending.id !== id
+    );
+    if (this.messageQueue.length === 0) this.pendingRpcPeriodStartedAt = null;
+  }
+  /**
+   * Whether the current socket has delivered any frame recently. SessionDO
+   * broadcasts a one-way heartbeat every five seconds, so this measures the
+   * transport without adding an RPC that can be delayed by application work.
+   */
+  hasRecentInboundActivity(maxAgeMs, now = Date.now()) {
+    return this.ws?.readyState === READY_STATE_OPEN && this.lastInboundActivityAt !== null && now - this.lastInboundActivityAt <= maxAgeMs;
+  }
   seedDocumentSnapshot(document) {
     if (!document || typeof document !== "object" || Array.isArray(document)) {
       return;
@@ -21128,6 +21238,7 @@ var WSClient = class {
     const socket = this.ws;
     this.connectionEpoch += 1;
     this.ws = null;
+    this.lastInboundActivityAt = null;
     try {
       socket?.close(4001, "Transport failure");
     } catch {
@@ -21210,12 +21321,14 @@ var WSClient = class {
           closeStaleSocket();
           return;
         }
+        this.lastInboundActivityAt = Date.now();
         this.reconnectAttempts = 0;
         this.emit("open", {});
         finish();
       };
       const handleMessage = (data) => {
         if (!isCurrent()) return;
+        this.lastInboundActivityAt = Date.now();
         try {
           const text = typeof data === "string" ? data : data && typeof data === "object" && "toString" in data ? String(data.toString()) : "";
           this.handleMessage(JSON.parse(text));
@@ -21250,9 +21363,7 @@ var WSClient = class {
         this.ws = null;
         closeStaleSocket();
         finish(
-          new Error(
-            `WebSocket connect timed out after ${connectTimeoutMs}ms`
-          )
+          new Error(`WebSocket connect timed out after ${connectTimeoutMs}ms`)
         );
       }, connectTimeoutMs);
       signal?.addEventListener("abort", handleAbort, { once: true });
@@ -21292,6 +21403,7 @@ var WSClient = class {
       pending.reject(error2);
     });
     this.messageQueue = [];
+    this.pendingRpcPeriodStartedAt = null;
   }
   emitReconnectErrorMessage(error2, terminal2 = false) {
     const reconnectInfo = {
@@ -21695,9 +21807,7 @@ var WSClient = class {
         } else {
           pending.resolve(response.result);
         }
-        this.messageQueue = this.messageQueue.filter(
-          (q) => q.id !== response.id
-        );
+        this.removePendingRpc(response.id);
       }
       return;
     }
@@ -21735,16 +21845,24 @@ var WSClient = class {
       const timeout = setTimeout(() => {
         const pending = this.messageQueue.find((q) => q.id === id);
         if (pending) {
-          this.messageQueue = this.messageQueue.filter((q) => q.id !== id);
+          this.removePendingRpc(id);
           reject(new Error(`RPC timeout: ${method}`));
         }
       }, timeoutMs);
-      this.messageQueue.push({ resolve: resolve2, reject, id, timeout });
+      if (this.messageQueue.length === 0) {
+        this.pendingRpcPeriodStartedAt = Date.now();
+      }
+      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);
+        this.removePendingRpc(id);
         reject(error2 instanceof Error ? error2 : new Error(String(error2)));
       }
     });
@@ -21849,6 +21967,7 @@ var WSClient = class {
     this.cancelConnectAttempt?.();
     this.cancelConnectAttempt = null;
     this.connectionEpoch += 1;
+    this.lastInboundActivityAt = null;
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
@@ -25001,16 +25120,100 @@ function normalizeEnvironmentData(environment) {
     setup: normalizeEnvironmentSetupSummary(environment.setup)
   };
 }
+function isGraphQLMutationDocument(query) {
+  if (typeof query !== "string") return false;
+  const tokens = [];
+  for (let index = 0; index < query.length; ) {
+    const character = query[index];
+    if (/[,\s\ufeff]/.test(character)) {
+      index += 1;
+      continue;
+    }
+    if (character === "#") {
+      while (index < query.length && !/[\r\n]/.test(query[index])) index += 1;
+      continue;
+    }
+    if (character === '"') {
+      const block = query.startsWith('"""', index);
+      let closed = false;
+      index += block ? 3 : 1;
+      while (index < query.length) {
+        if (block && query.startsWith('"""', index) && query[index - 1] !== "\\") {
+          index += 3;
+          closed = true;
+          break;
+        }
+        if (!block && query[index] === '"') {
+          index += 1;
+          closed = true;
+          break;
+        }
+        index += query[index] === "\\" && !block ? 2 : 1;
+      }
+      if (!closed) return true;
+      continue;
+    }
+    const name = query.slice(index).match(/^[_A-Za-z][_0-9A-Za-z]*/)?.[0];
+    if (name) {
+      tokens.push(name);
+      index += name.length;
+      continue;
+    }
+    if ("{}()[]".includes(character)) tokens.push(character);
+    index += 1;
+  }
+  const skipSelection = (start) => {
+    let depth = 0;
+    for (let index = start; index < tokens.length; index += 1) {
+      if (tokens[index] === "{") depth += 1;
+      if (tokens[index] === "}" && --depth === 0) return index + 1;
+    }
+    return null;
+  };
+  for (let index = 0; index < tokens.length; ) {
+    const definition = tokens[index++];
+    if (definition === "mutation") return true;
+    if (definition === "{") {
+      const nextDefinition2 = skipSelection(index - 1);
+      if (nextDefinition2 === null) return true;
+      index = nextDefinition2;
+      continue;
+    }
+    if (!["query", "subscription", "fragment"].includes(definition || "")) {
+      return true;
+    }
+    let parentheses = 0;
+    let brackets = 0;
+    while (index < tokens.length) {
+      const token = tokens[index];
+      if (token === "(") parentheses += 1;
+      else if (token === ")") parentheses -= 1;
+      else if (token === "[") brackets += 1;
+      else if (token === "]") brackets -= 1;
+      else if (token === "{" && parentheses === 0 && brackets === 0) break;
+      index += 1;
+    }
+    if (index === tokens.length) return true;
+    const nextDefinition = skipSelection(index);
+    if (nextDefinition === null) return true;
+    index = nextDefinition;
+  }
+  return false;
+}
 var Environment = class _Environment {
   granular;
   envData;
   _apiKey;
   _apiEndpoint;
-  constructor(granular, envData, apiKey, apiEndpoint) {
+  _tokenProvider;
+  _beforeMutationSend;
+  constructor(granular, envData, apiKey, apiEndpoint, tokenProvider, beforeMutationSend) {
     this.granular = granular;
     this.envData = envData;
     this._apiKey = apiKey;
     this._apiEndpoint = apiEndpoint;
+    this._tokenProvider = tokenProvider;
+    this._beforeMutationSend = beforeMutationSend;
   }
   /** The environment ID */
   get environmentId() {
@@ -25076,6 +25279,15 @@ var Environment = class _Environment {
   get authToken() {
     return this._apiKey;
   }
+  resolveAuthToken() {
+    if (!this._tokenProvider) return this._apiKey;
+    return Promise.resolve(this._tokenProvider()).then((provided) => {
+      if (typeof provided === "string" && provided.trim()) {
+        this._apiKey = provided.trim();
+      }
+      return this._apiKey;
+    });
+  }
   /** Base runtime URL derived from the GraphQL endpoint */
   get runtimeBaseUrl() {
     return this.getRuntimeBaseUrl();
@@ -25467,10 +25679,15 @@ var Environment = class _Environment {
   async controlPlaneRequest(path7, options = {}) {
     const runtimeBase = this.getRuntimeBaseUrl();
     const url = `${runtimeBase}${path7}`;
+    const authToken = await this.resolveAuthToken();
+    const method = (options.method || "GET").toUpperCase();
+    if (method !== "GET" && method !== "HEAD" && method !== "OPTIONS") {
+      this._beforeMutationSend?.();
+    }
     const response = await fetch(url, {
       ...options,
       headers: {
-        Authorization: `Bearer ${this._apiKey}`,
+        Authorization: `Bearer ${authToken}`,
         "Content-Type": "application/json",
         ...options.headers
       }
@@ -25535,11 +25752,15 @@ var Environment = class _Environment {
    * ```
    */
   async graphql(query, variables) {
+    const authToken = await this.resolveAuthToken();
+    if (this._beforeMutationSend && isGraphQLMutationDocument(query)) {
+      this._beforeMutationSend?.();
+    }
     const response = await fetch(this._apiEndpoint, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        Authorization: `Bearer ${this._apiKey}`
+        Authorization: `Bearer ${authToken}`
       },
       body: JSON.stringify({
         environmentId: this.environmentId,
@@ -26018,8 +26239,10 @@ var Environment = class _Environment {
           eventType.payloadSchema.properties
         )) {
           const schema = propSchema;
+          const format = schema.format === "date" || schema.format === "date-time" ? schema.format : void 0;
           fieldSpecs[propName] = {
             type: schema.type ?? "string",
+            ...format ? { format } : {},
             description: schema.description
           };
         }
@@ -26441,40 +26664,36 @@ var EnvironmentSession = class extends Session {
   environment;
   sessionDataRoutePrefix;
   sessionDataHeaders;
+  beforeMutationSend;
   heartbeatTimer = null;
-  heartbeatInFlight = false;
-  /** The last known graph container status, updated by checkReadiness() or on heartbeat */
+  /** The last known graph container status, updated by checkReadiness(). */
   graphContainerStatus = null;
   constructor(client, environment, clientId, options = {}) {
     super(client, clientId, { initialQuota: options.initialQuota });
     this.environment = environment;
     this.sessionDataRoutePrefix = options.sessionDataRoutePrefix || "/orchestrator/ws/sessions";
     this.sessionDataHeaders = options.sessionDataHeaders || {};
+    this.beforeMutationSend = options.beforeMutationSend;
     this.setFeedListTransport(
       (feedOptions) => this.sessionDataRequest("/feed", feedOptions)
     );
   }
   /**
    * Keep the browser session transport observable from the client side.
-   * A worker/proxy restart can leave a browser WebSocket appearing OPEN even
-   * though the server-side Durable Object has already closed its peer. The
-   * heartbeat gives the SDK a bounded failure signal so it can revoke that
-   * stale socket and use WSClient's normal reconnect path.
+   * SessionDO already broadcasts a heartbeat every five seconds. Treat that
+   * and all other inbound frames as proof of life instead of issuing an RPC:
+   * an application RPC may be delayed by Durable Object work even while the
+   * underlying WebSocket is healthy.
    */
   startHeartbeat() {
     if (this.heartbeatTimer) return;
     this.heartbeatTimer = setInterval(() => {
-      if (this.heartbeatInFlight) return;
-      this.heartbeatInFlight = true;
-      void this.client.call("client.heartbeat", {}).then((result) => {
-        if (result?.graphContainerStatus) {
-          this.graphContainerStatus = result.graphContainerStatus;
-        }
-      }).catch((error2) => {
-        this.client.reportTransportFailure(error2);
-      }).finally(() => {
-        this.heartbeatInFlight = false;
-      });
+      if (!this.client.isTransportOpen()) return;
+      if (this.client.hasRecentInboundActivity(3e4)) return;
+      if (this.client.hasRecentlyPendingRpcPeriod(6e4)) return;
+      this.client.reportTransportFailure(
+        new Error("No server activity received for 30 seconds")
+      );
     }, 5e3);
     this.heartbeatTimer.unref?.();
   }
@@ -26483,7 +26702,6 @@ var EnvironmentSession = class extends Session {
       clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = null;
     }
-    this.heartbeatInFlight = false;
   }
   async hello() {
     const result = await super.hello();
@@ -26544,7 +26762,13 @@ var EnvironmentSession = class extends Session {
     for (let attempt = 1; attempt <= SESSION_DATA_REQUEST_RETRY_COUNT; attempt += 1) {
       try {
         const headers = new Headers(init2.headers);
-        headers.set("Authorization", `Bearer ${this.environment.authToken}`);
+        const resolvedAuthToken = this.environment.resolveAuthToken();
+        const authToken = typeof resolvedAuthToken === "string" ? resolvedAuthToken : await resolvedAuthToken;
+        headers.set("Authorization", `Bearer ${authToken}`);
+        const method = (init2.method || "GET").toUpperCase();
+        if (method !== "GET" && method !== "HEAD" && method !== "OPTIONS") {
+          this.beforeMutationSend?.();
+        }
         const response = await fetch(url, {
           method: init2.method || "GET",
           headers,
@@ -27003,7 +27227,7 @@ var EnvironmentSession = class extends Session {
             method: "POST",
             headers: {
               "Content-Type": "application/json",
-              Authorization: `Bearer ${this.environment.authToken}`
+              Authorization: `Bearer ${await this.environment.resolveAuthToken()}`
             },
             body: JSON.stringify({
               reason: "sdk_disconnect_http_fallback",
@@ -27795,6 +28019,9 @@ var Granular = class _Granular {
     if (typeof options.limit === "number") {
       query.set("limit", String(options.limit));
     }
+    if (options.consistency === "refresh") {
+      query.set("consistency", "refresh");
+    }
     const state = await this.request(
       `/sdk/user-environment-state?${query.toString()}`
     );
@@ -27938,6 +28165,10 @@ var Granular = class _Granular {
     });
   }
   async recordOpenAIUsageSpend(usage, context, options) {
+    const providedToken = await this.tokenProvider?.();
+    if (typeof providedToken === "string" && providedToken.trim()) {
+      this.apiKey = providedToken.trim();
+    }
     return recordOpenAIUsageSpend({
       apiUrl: this.apiUrl,
       token: this.apiKey,
@@ -28110,7 +28341,13 @@ var Granular = class _Granular {
   }
   bindEnvironmentHandle(envData) {
     const graphqlEndpoint = `${this.httpUrl}/orchestrator/graphql`;
-    return new Environment(this, envData, this.apiKey, graphqlEndpoint);
+    return new Environment(
+      this,
+      envData,
+      this.apiKey,
+      graphqlEndpoint,
+      this.tokenProvider
+    );
   }
   async bindWebSocketEnvironmentSession(environment, clientId, session2, transportOptions = {}) {
     const client = new WSClient({
@@ -28994,6 +29231,10 @@ var Granular = class _Granular {
       console.log(`[SDK] Requesting: ${url}`);
     }
     for (let attempt = 1; attempt <= LOCAL_CONTROL_REQUEST_RETRY_COUNT; attempt += 1) {
+      const providedToken = await this.tokenProvider?.();
+      if (typeof providedToken === "string" && providedToken.trim()) {
+        this.apiKey = providedToken.trim();
+      }
       const response = await fetch(url, {
         ...options,
         headers: {

package/dist/{client-S-z8bri1.d.mts → client-BT1DJddL.d.ts}

@@ -1,4 +1,4 @@
-import { de as WSClientOptions, a5 as SessionFeedApi, b9 as GranularQuotaProgress, T as ToolWithHandler, o as PublishToolsResult, cg as Job, p as ToolHandler, I as InstanceToolHandler, cj as UserMessageInput, ck as UserMessageAppendResult, c3 as EffectInfo, l as Prompt, c2 as ToolInfo, c5 as EffectsChangedEvent, c4 as ToolsChangedEvent, D as DomainState, a8 as FeedListTransport, aR as GranularOptions, dM as EnvironmentImporter, aU as RecordUserOptions, aT as User, aW as OpenEnvironmentOptions, bm as EnvironmentData, bj as BuildPolicy, dJ as EnvironmentSetupSummary, b0 as ConversationSessionListOptions, a_ as ConversationSessionInfo, b1 as ConversationSessionListResponse, aZ as CreateSessionOptions, f as RecordObjectOptions, dv as RecordObjectResult, dx as RecordObjectsOptions, dE as RecordImport, dA as RecordImportStatus, dD as RecordImportItem, dF as EnvironmentRecordImportSummary, ce as EnvironmentFeedbackRecord, k as SessionHeapSnapshot, d2 as SessionDocumentResult, cl as AssistantReplyPublicationInput, cm as AssistantReplyPublicationResult, d3 as SessionCollectionListOptions, d5 as SessionCollectionListResult, cp as SessionTimelineEvent, d4 as SessionJobListOptions, cX as SessionJobRecord, bO as SessionMutationView, cy as SessionArtifactListOptions, cx as SessionArtifactRecord, cA as SessionArtifactRelationshipOptionsInput, cC as SessionArtifactRelationshipOptionsResult, cD as SessionArtifactRelationshipCreateInput, cz as SessionArtifactValidationResult, cF as SessionArtifactExecutionOptions, cE as SessionArtifactExecutionResult, cG as SessionArtifactApprovalOptions, cQ as RecordManualActionInput, cS as ManualActionRecordResult, cT as ManualActionListOptions, cR as ManualActionOccurrence, cV as ManualActionSuggestionOptions, cU as ManualActionSuggestion, cJ as ArtifactApprovalTaskListOptions, cI as ArtifactApprovalTask, cK as ArtifactApprovalDecisionInput, cL as ArtifactApprovalDecisionResult, ct as SessionFileRecord, cW as SessionFileUploadOptions, S as SessionHeapEntry, i as SessionHeapList, c_ as SessionHeapVariable, m as SessionTranscriptEntry, ee as GraphQLResult, d0 as RecordSearchOptions, c$ as RecordSearchResult, d1 as RecordMentionInput, dn as DefineRelationshipOptions, dm as RelationshipInfo, dl as ModelRef, g as ManifestContent, ds as EnvironmentStateUpdateInput, dq as EnvironmentStateTarget, du as EnvironmentStateProxy, dz as RecordImportOptions, da as UserEnvironmentStateOptions, d9 as UserEnvironmentState, db as MarkUserEnvironmentReadOptions, b as ProjectionMapper, bH as EffectProjectionResult, bM as ExternalCommitOptions, C as CommitReceipt, bI as TransitionProjectionResult, bN as ObservationReceipt, aX as AdoptEnvironmentOptions, aY as ConnectOptions, dH as RunEnvironmentImporterOptions, aD as OpenAIUsageSpendEvent, aC as GranularSpendContext, aF as RecordOpenAIUsageSpendResult, bc as SandboxListResponse, ba as Sandbox, bb as CreateSandboxData, eg as DeleteResponse, be as PermissionProfile, bf as CreatePermissionProfileData, bn as CreateEnvironmentData, eh as StreamEvent, ei as StreamSubscription, ej as StreamStats, aV as Subject, bi as AssignmentListResponse } from './spend-CESUvrZC.mjs';
+import { de as WSClientOptions, a5 as SessionFeedApi, b9 as GranularQuotaProgress, T as ToolWithHandler, o as PublishToolsResult, cg as Job, p as ToolHandler, I as InstanceToolHandler, cj as UserMessageInput, ck as UserMessageAppendResult, c3 as EffectInfo, l as Prompt, c2 as ToolInfo, c5 as EffectsChangedEvent, c4 as ToolsChangedEvent, D as DomainState, a8 as FeedListTransport, aR as GranularOptions, dM as EnvironmentImporter, aU as RecordUserOptions, aT as User, aW as OpenEnvironmentOptions, bm as EnvironmentData, aQ as AccessTokenProvider, bj as BuildPolicy, dJ as EnvironmentSetupSummary, b0 as ConversationSessionListOptions, a_ as ConversationSessionInfo, b1 as ConversationSessionListResponse, aZ as CreateSessionOptions, f as RecordObjectOptions, dv as RecordObjectResult, dx as RecordObjectsOptions, dE as RecordImport, dA as RecordImportStatus, dD as RecordImportItem, dF as EnvironmentRecordImportSummary, ce as EnvironmentFeedbackRecord, k as SessionHeapSnapshot, d2 as SessionDocumentResult, cl as AssistantReplyPublicationInput, cm as AssistantReplyPublicationResult, d3 as SessionCollectionListOptions, d5 as SessionCollectionListResult, cp as SessionTimelineEvent, d4 as SessionJobListOptions, cX as SessionJobRecord, bO as SessionMutationView, cy as SessionArtifactListOptions, cx as SessionArtifactRecord, cA as SessionArtifactRelationshipOptionsInput, cC as SessionArtifactRelationshipOptionsResult, cD as SessionArtifactRelationshipCreateInput, cz as SessionArtifactValidationResult, cF as SessionArtifactExecutionOptions, cE as SessionArtifactExecutionResult, cG as SessionArtifactApprovalOptions, cQ as RecordManualActionInput, cS as ManualActionRecordResult, cT as ManualActionListOptions, cR as ManualActionOccurrence, cV as ManualActionSuggestionOptions, cU as ManualActionSuggestion, cJ as ArtifactApprovalTaskListOptions, cI as ArtifactApprovalTask, cK as ArtifactApprovalDecisionInput, cL as ArtifactApprovalDecisionResult, ct as SessionFileRecord, cW as SessionFileUploadOptions, S as SessionHeapEntry, i as SessionHeapList, c_ as SessionHeapVariable, m as SessionTranscriptEntry, ee as GraphQLResult, d0 as RecordSearchOptions, c$ as RecordSearchResult, d1 as RecordMentionInput, dn as DefineRelationshipOptions, dm as RelationshipInfo, dl as ModelRef, g as ManifestContent, ds as EnvironmentStateUpdateInput, dq as EnvironmentStateTarget, du as EnvironmentStateProxy, dz as RecordImportOptions, da as UserEnvironmentStateOptions, d9 as UserEnvironmentState, db as MarkUserEnvironmentReadOptions, b as ProjectionMapper, bH as EffectProjectionResult, bM as ExternalCommitOptions, C as CommitReceipt, bI as TransitionProjectionResult, bN as ObservationReceipt, aX as AdoptEnvironmentOptions, aY as ConnectOptions, dH as RunEnvironmentImporterOptions, aD as OpenAIUsageSpendEvent, aC as GranularSpendContext, aF as RecordOpenAIUsageSpendResult, bc as SandboxListResponse, ba as Sandbox, bb as CreateSandboxData, eg as DeleteResponse, be as PermissionProfile, bf as CreatePermissionProfileData, bn as CreateEnvironmentData, eh as StreamEvent, ei as StreamSubscription, ej as StreamStats, aV as Subject, bi as AssignmentListResponse } from './spend-D4r0SA-H.js';
 import * as Automerge from '@automerge/automerge';
 import { Doc } from '@automerge/automerge/slim';
 
@@ -13,6 +13,7 @@ declare class WSClient {
     private sessionId;
     private token;
     private messageQueue;
+    private pendingRpcPeriodStartedAt;
     private rpcHandlers;
     private eventHandlers;
     private canonicalDocumentQuarantineHandlers;
@@ -27,9 +28,20 @@ declare class WSClient {
     private cancelConnectAttempt;
     private documentRepairRequired;
     private canonicalDocumentActivated;
+    private lastInboundActivityAt;
     private options;
     constructor(options: WSClientOptions);
     get currentSessionId(): string;
+    isTransportOpen(): boolean;
+    hasPendingRpcRequests(): boolean;
+    hasRecentlyPendingRpcPeriod(maxAgeMs: number, now?: number): boolean;
+    private removePendingRpc;
+    /**
+     * Whether the current socket has delivered any frame recently. SessionDO
+     * broadcasts a one-way heartbeat every five seconds, so this measures the
+     * transport without adding an RPC that can be delayed by application work.
+     */
+    hasRecentInboundActivity(maxAgeMs: number, now?: number): boolean;
     seedDocumentSnapshot(document: Record<string, unknown> | Uint8Array | null | undefined): void;
     saveDocumentSnapshot(): Uint8Array;
     private clearTokenRefreshTimer;
@@ -310,6 +322,7 @@ declare class Session {
 type SessionFileUploadBody = Blob | ArrayBuffer | Uint8Array | string;
 type SessionDataHeaders = any;
 type EnvironmentImporterHandler = (importer: EnvironmentImporter) => Promise<void> | void;
+declare function isGraphQLMutationDocument(query: unknown): boolean;
 /**
  * Environment is the sessionless handle for one resolved ontology environment.
  *
@@ -322,7 +335,9 @@ declare class Environment {
     private envData;
     private _apiKey;
     private _apiEndpoint;
-    constructor(granular: Granular, envData: EnvironmentData, apiKey: string, apiEndpoint: string);
+    private _tokenProvider?;
+    private _beforeMutationSend?;
+    constructor(granular: Granular, envData: EnvironmentData, apiKey: string, apiEndpoint: string, tokenProvider?: AccessTokenProvider, beforeMutationSend?: () => void);
     /** The environment ID */
     get environmentId(): string;
     /** The sandbox ID */
@@ -355,6 +370,7 @@ declare class Environment {
     get apiEndpoint(): string;
     /** Internal auth token used for control-plane and runtime fallback requests */
     get authToken(): string;
+    resolveAuthToken(): string | Promise<string>;
     /** Base runtime URL derived from the GraphQL endpoint */
     get runtimeBaseUrl(): string;
     syncEnvironmentData(envData: EnvironmentData): void;
@@ -776,9 +792,9 @@ declare class EnvironmentSession extends Session {
     readonly environment: Environment;
     private readonly sessionDataRoutePrefix;
     private readonly sessionDataHeaders;
+    private readonly beforeMutationSend?;
     private heartbeatTimer;
-    private heartbeatInFlight;
-    /** The last known graph container status, updated by checkReadiness() or on heartbeat */
+    /** The last known graph container status, updated by checkReadiness(). */
     graphContainerStatus: {
         lastKeepAliveAt: number;
         status: "warming" | "hot" | "unknown";
@@ -791,14 +807,16 @@ declare class EnvironmentSession extends Session {
          * that initiated a user action when multiple tabs are connected.
          */
         sessionDataHeaders?: SessionDataHeaders;
+        /** Browser-only readiness guard checked immediately before each write. */
+        beforeMutationSend?: () => void;
         initialQuota?: GranularQuotaProgress | null;
     });
     /**
      * Keep the browser session transport observable from the client side.
-     * A worker/proxy restart can leave a browser WebSocket appearing OPEN even
-     * though the server-side Durable Object has already closed its peer. The
-     * heartbeat gives the SDK a bounded failure signal so it can revoke that
-     * stale socket and use WSClient's normal reconnect path.
+     * SessionDO already broadcasts a heartbeat every five seconds. Treat that
+     * and all other inbound frames as proof of life instead of issuing an RPC:
+     * an application RPC may be delayed by Durable Object work even while the
+     * underlying WebSocket is healthy.
      */
     private startHeartbeat;
     private stopHeartbeat;
@@ -1336,4 +1354,4 @@ declare class Granular {
     private request;
 }
 
-export { Environment as E, Granular as G, OntologyHandle as O, Session as S, WSClient as W, EnvironmentSession as a };
+export { Environment as E, Granular as G, OntologyHandle as O, Session as S, WSClient as W, EnvironmentSession as a, isGraphQLMutationDocument as i };