@granular-software/sdk 0.4.65 → 0.4.67

package/dist/index.js

@@ -5303,7 +5303,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;
@@ -5349,8 +5348,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":
@@ -5370,6 +5367,7 @@ var WSClient = class {
   sessionId;
   token;
   messageQueue = [];
+  pendingRpcPeriodStartedAt = null;
   rpcHandlers = /* @__PURE__ */ new Map();
   eventHandlers = /* @__PURE__ */ new Map();
   canonicalDocumentQuarantineHandlers = /* @__PURE__ */ new Set();
@@ -5384,6 +5382,7 @@ var WSClient = class {
   cancelConnectAttempt = null;
   documentRepairRequired = false;
   canonicalDocumentActivated = false;
+  lastInboundActivityAt = null;
   options;
   constructor(options) {
     this.options = options;
@@ -5397,6 +5396,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;
@@ -5548,6 +5570,7 @@ var WSClient = class {
     const socket = this.ws;
     this.connectionEpoch += 1;
     this.ws = null;
+    this.lastInboundActivityAt = null;
     try {
       socket?.close(4001, "Transport failure");
     } catch {
@@ -5630,12 +5653,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));
@@ -5670,9 +5695,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 });
@@ -5712,6 +5735,7 @@ var WSClient = class {
       pending.reject(error);
     });
     this.messageQueue = [];
+    this.pendingRpcPeriodStartedAt = null;
   }
   emitReconnectErrorMessage(error, terminal = false) {
     const reconnectInfo = {
@@ -6115,9 +6139,7 @@ var WSClient = class {
         } else {
           pending.resolve(response.result);
         }
-        this.messageQueue = this.messageQueue.filter(
-          (q) => q.id !== response.id
-        );
+        this.removePendingRpc(response.id);
       }
       return;
     }
@@ -6155,16 +6177,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, reject, id, timeout });
+      if (this.messageQueue.length === 0) {
+        this.pendingRpcPeriodStartedAt = Date.now();
+      }
+      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);
+        this.removePendingRpc(id);
         reject(error instanceof Error ? error : new Error(String(error)));
       }
     });
@@ -6269,6 +6299,7 @@ var WSClient = class {
     this.cancelConnectAttempt?.();
     this.cancelConnectAttempt = null;
     this.connectionEpoch += 1;
+    this.lastInboundActivityAt = null;
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
@@ -12685,6 +12716,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;
   }
@@ -15572,6 +15604,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;
@@ -15841,6 +15958,7 @@ var DEFAULT_METAMODEL_PACKAGES = [
   searchableMetamodelPackage,
   validationRuleMetamodelPackage,
   stateMachineMetamodelPackage,
+  temporalMetamodelPackage,
   effectBehaviorsMetamodelPackage,
   policyMetamodelPackage
 ];
@@ -16163,16 +16281,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() {
@@ -16238,6 +16440,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();
@@ -16629,10 +16840,15 @@ var Environment = class _Environment {
   async controlPlaneRequest(path, options = {}) {
     const runtimeBase = this.getRuntimeBaseUrl();
     const url = `${runtimeBase}${path}`;
+    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
       }
@@ -16697,11 +16913,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,
@@ -17180,8 +17400,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
           };
         }
@@ -17603,40 +17825,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((error) => {
-        this.client.reportTransportFailure(error);
-      }).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?.();
   }
@@ -17645,7 +17863,6 @@ var EnvironmentSession = class extends Session {
       clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = null;
     }
-    this.heartbeatInFlight = false;
   }
   async hello() {
     const result = await super.hello();
@@ -17706,7 +17923,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,
@@ -18165,7 +18388,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",
@@ -18957,6 +19180,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()}`
     );
@@ -19100,6 +19326,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,
@@ -19272,7 +19502,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, session, transportOptions = {}) {
     const client = new WSClient({
@@ -20156,6 +20392,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: {
@@ -22367,6 +22607,10 @@ function jsonSchemaTypeName(schema) {
   const record = normalizeJsonSchema(schema);
   if (!record) return "unknown";
   const type = record.type;
+  if (record.format === "date-time") return "date-time";
+  if (record.format === "date" || type === "date" || Array.isArray(type) && type.includes("date")) {
+    return "date";
+  }
   if (typeof type === "string") {
     if (type === "array") return "array";
     if (type === "object") return "object";
@@ -22868,6 +23112,8 @@ ${actionIndex}
 - 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.
 - 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.
+- For creation inputs, use the declared action schema and its field descriptions as the mapping authority. Copy every compatible value explicitly present in the current request, conversation, selected/saved object, file, fresh read, or declared ontology default, including values for fields with arbitrary names. Omit only values for which that context provides no evidence.
+- Never fill an input because of its field name, a regular expression or other string pattern, its primitive type, a schema minimum, an example value, or the first enum option. If the evidence is ambiguous, leave the field unresolved or ask the user.
 - 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.
@@ -23521,6 +23767,7 @@ exports.hasOpenPrompt = hasOpenPrompt;
 exports.hashHarnessTemplateValue = hashHarnessTemplateValue;
 exports.invokeRegisteredEffect = invokeRegisteredEffect;
 exports.isCanonicalSessionFeedDocument = isCanonicalSessionFeedDocument;
+exports.isGraphQLMutationDocument = isGraphQLMutationDocument;
 exports.isLocalApiUrl = isLocalApiUrl;
 exports.listHarnessTemplates = listHarnessTemplates;
 exports.mergeFeedItemsBySequence = mergeFeedItemsBySequence;