@granular-software/sdk 0.4.69 → 0.4.71

package/dist/cli/index.js

@@ -14179,6 +14179,7 @@ var StateMachineTransitionSchema = external_exports.object({
   to: external_exports.string().min(1),
   label: external_exports.string().optional(),
   description: external_exports.string().optional(),
+  userVisible: external_exports.boolean().optional(),
   action: StateTransitionActionSchema.optional(),
   assignee: StateTransitionAssigneeSchema.optional(),
   requirements: StateTransitionRequirementsSchema.optional(),
@@ -14263,6 +14264,7 @@ var CreatesSchema = external_exports.union([
     idPath: external_exports.string().min(1).optional(),
     pathPath: external_exports.string().min(1).optional(),
     statePath: external_exports.string().min(1).optional(),
+    completionState: external_exports.string().min(1).optional(),
     classStateHandle: external_exports.boolean().optional()
   }).strict()
 ]);
@@ -14612,6 +14614,7 @@ function normalizeCreationSummary(metamodels) {
     ...typeof raw.idPath === "string" && raw.idPath.trim() ? { idPath: raw.idPath.trim() } : {},
     ...typeof raw.pathPath === "string" && raw.pathPath.trim() ? { pathPath: raw.pathPath.trim() } : {},
     ...typeof raw.statePath === "string" && raw.statePath.trim() ? { statePath: raw.statePath.trim() } : {},
+    ...typeof raw.completionState === "string" && raw.completionState.trim() ? { completionState: raw.completionState.trim() } : {},
     ...typeof raw.classStateHandle === "boolean" ? { classStateHandle: raw.classStateHandle } : {}
   };
 }
@@ -14737,7 +14740,7 @@ var effectBehaviorsMetamodelPackage = defineMetamodelPackage({
       },
       {
         key: "creates",
-        description: 'Marks a static method as an allowed creator for a class. Use `creates: "class_name"` or `{ className, idPath, pathPath, statePath, classStateHandle }`.'
+        description: 'Marks a static method as an allowed creator for a class. Use `creates: "class_name"` or `{ className, idPath, pathPath, statePath, completionState, classStateHandle }`.'
       }
     ]
   },
@@ -15532,6 +15535,7 @@ function normalizeStateMachines(values) {
       to: String(transition?.to?.name || ""),
       label: typeof transition?.label === "string" ? transition.label : null,
       description: typeof transition?.description === "string" ? transition.description : null,
+      userVisible: typeof transition?.user_visible === "boolean" ? transition.user_visible : typeof transition?.userVisible === "boolean" ? transition.userVisible : null,
       action: parseJsonRecord(transition?.action) || parseJsonRecord(transition?.action_json),
       assignee: parseJsonRecord(transition?.assignee) || parseJsonRecord(transition?.assignee_json),
       requirements: parseJsonRecord(transition?.requirements) || parseJsonRecord(transition?.requirements_json),
@@ -15603,6 +15607,9 @@ function transitionMetadataGraphqlArgs(transition) {
   if (typeof transition.description === "string") {
     args.push(`description: ${JSON.stringify(transition.description)}`);
   }
+  if (typeof transition.userVisible === "boolean") {
+    args.push(`user_visible: ${transition.userVisible}`);
+  }
   if (transition.action) {
     args.push(
       `action_json: ${JSON.stringify(JSON.stringify(transition.action))}`
@@ -15914,7 +15921,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
         name: String!
         state_machine: StateMachine!
         add_state(name: String!, is_final: Boolean, label: String, description: String): StateMachineMutation!
-        add_transition(name: String!, from: String!, to: String!, label: String, description: String, action_json: String, assignee_json: String, requirements_json: String, permission_json: String, risk: String, expected_outcome_json: String, outcomes_json: String): StateMachineMutation!
+        add_transition(name: String!, from: String!, to: String!, label: String, description: String, user_visible: Boolean, action_json: String, assignee_json: String, requirements_json: String, permission_json: String, risk: String, expected_outcome_json: String, outcomes_json: String): StateMachineMutation!
         activate_transition(name: String!): StateMachineMutation!
       }
 
@@ -15972,6 +15979,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
         to: StateMachineState!
         label: String
         description: String
+        user_visible: Boolean
         action_json: String
         assignee_json: String
         requirements_json: String
@@ -16053,6 +16061,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
             to,
             label,
             description,
+            user_visible,
             action_json,
             assignee_json,
             requirements_json,
@@ -16070,6 +16079,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
                 {
                   label,
                   description,
+                  userVisible: user_visible,
                   actionJson: action_json,
                   assigneeJson: assignee_json,
                   requirementsJson: requirements_json,
@@ -16134,6 +16144,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
           to: (value) => value.to_state || { name: value.to, is_final: false },
           label: (value) => value.label || null,
           description: (value) => value.description || null,
+          user_visible: (value) => value.user_visible ?? null,
           action_json: (value) => value.action_json || null,
           assignee_json: (value) => value.assignee_json || null,
           requirements_json: (value) => value.requirements_json || null,
@@ -16220,6 +16231,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
             to { name }
             label
             description
+            user_visible
             action_json
             assignee_json
             requirements_json
@@ -21006,6 +21018,38 @@ function stableDocumentFingerprint(value) {
     (key) => `${JSON.stringify(key)}:${stableDocumentFingerprint(record[key])}`
   ).join(",")}}`;
 }
+function canonicalDocumentFingerprint(value) {
+  const stripPresentation = (input, path7) => {
+    if (input === null || typeof input !== "object") return input;
+    if (input instanceof Date || input instanceof Uint8Array) return input;
+    if (Array.isArray(input)) {
+      return input.map((entry) => stripPresentation(entry, path7));
+    }
+    const record = input;
+    const output = {};
+    for (const [key, entry] of Object.entries(record)) {
+      if (path7.length === 1 && path7[0] === "feed" && [
+        "transientById",
+        "feedbackUsageByJob",
+        "revision",
+        "lastTransientOrdinal"
+      ].includes(key)) {
+        continue;
+      }
+      if (path7.length === 3 && path7[0] === "jobs" && path7[1] === "byId" && [
+        "actionTrace",
+        "actionSummary",
+        "actionSummaryText",
+        "lastActionAt"
+      ].includes(key)) {
+        continue;
+      }
+      output[key] = stripPresentation(entry, [...path7, key]);
+    }
+    return output;
+  };
+  return stableDocumentFingerprint(stripPresentation(value, []));
+}
 function debugWs(...args) {
   if (DEBUG_WS) {
     console.log(...args);
@@ -21323,6 +21367,7 @@ var WSClient = class {
         }
         this.lastInboundActivityAt = Date.now();
         this.reconnectAttempts = 0;
+        this.connectPromise = null;
         this.emit("open", {});
         finish();
       };
@@ -21485,7 +21530,7 @@ var WSClient = class {
       this.canonicalDocumentActivated = true;
     }
   }
-  canAcceptDocumentReplacement(replacement, strictlyNewer) {
+  canAcceptDocumentReplacement(replacement, strictlyNewer, options = {}) {
     const replacementCanonical = isCanonicalSessionFeedDocument(replacement);
     const currentCanonical = isCanonicalSessionFeedDocument(this.doc);
     if (replacementCanonical) {
@@ -21534,7 +21579,7 @@ var WSClient = class {
       debugWs(`[Granular DEBUG] Rejected session snapshot: ${canonicalError}`);
       return false;
     }
-    if (this.canonicalDocumentActivated && incoming.epoch === current.epoch && incoming.revision === current.revision && !readSessionFeedSnapshot(this.doc).error && stableDocumentFingerprint(Automerge__namespace.toJS(replacement)) !== stableDocumentFingerprint(Automerge__namespace.toJS(this.doc))) {
+    if (this.canonicalDocumentActivated && incoming.epoch === current.epoch && incoming.revision === current.revision && !readSessionFeedSnapshot(this.doc).error && (options.allowEqualRevisionPresentation ? canonicalDocumentFingerprint(Automerge__namespace.toJS(replacement)) : stableDocumentFingerprint(Automerge__namespace.toJS(replacement))) !== (options.allowEqualRevisionPresentation ? canonicalDocumentFingerprint(Automerge__namespace.toJS(this.doc)) : stableDocumentFingerprint(Automerge__namespace.toJS(this.doc)))) {
       debugWs(
         "[Granular DEBUG] Rejected divergent canonical snapshot at the accepted document version."
       );
@@ -21656,6 +21701,7 @@ var WSClient = class {
       reconnectScheduled: false
     };
     this.ws = null;
+    this.connectPromise = null;
     this.emit("close", info2);
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
@@ -21693,13 +21739,89 @@ var WSClient = class {
       );
       return;
     }
+    if ("type" in message && message.type === "job_action_trace") {
+      const update = message;
+      if (typeof update.jobId !== "string" || update.jobId.length === 0 || !Number.isSafeInteger(update.documentEpoch) || update.documentEpoch < 0 || !Number.isSafeInteger(update.documentRevision) || update.documentRevision < 0 || !Array.isArray(update.actionTrace) || update.actionTrace.length > 128 || !update.actionTrace.every(
+        (event) => event && typeof event === "object" && typeof event.id === "string" && typeof event.timestamp === "number" && Number.isFinite(event.timestamp)
+      ) || !Array.isArray(update.actionSummary) || update.actionSummary.length > 16 || !update.actionSummary.every((line) => typeof line === "string") || typeof update.actionSummaryText !== "string" || update.actionSummaryText.length > 8e3) {
+        console.warn("[Granular] Ignoring invalid job_action_trace message");
+        return;
+      }
+      const currentVersion = documentVersion(this.doc);
+      if (update.documentEpoch < currentVersion.epoch || update.documentEpoch === currentVersion.epoch && update.documentRevision < currentVersion.revision) {
+        return;
+      }
+      if (update.documentEpoch > currentVersion.epoch || update.documentEpoch === currentVersion.epoch && update.documentRevision > currentVersion.revision) {
+        return;
+      }
+      const current = Automerge__namespace.toJS(this.doc);
+      const job2 = current.jobs?.byId?.[update.jobId];
+      if (job2 && typeof job2 === "object" && !Array.isArray(job2)) {
+        job2.actionTrace = update.actionTrace;
+        job2.actionSummary = update.actionSummary;
+        job2.actionSummaryText = update.actionSummaryText;
+        const lastEvent = update.actionTrace[update.actionTrace.length - 1];
+        if (lastEvent && typeof lastEvent.timestamp === "number") {
+          job2.lastActionAt = lastEvent.timestamp;
+        }
+        this.doc = Automerge__namespace.from(current);
+        this.emit("job_action_trace", update);
+        this.emit("sync", this.doc);
+      }
+      return;
+    }
+    if ("type" in message && message.type === "feed_transient_patch") {
+      const update = message;
+      if (!Number.isSafeInteger(update.documentEpoch) || update.documentEpoch < 0 || !Number.isSafeInteger(update.documentRevision) || update.documentRevision < 0 || !Number.isSafeInteger(update.feedRevision) || update.feedRevision < 0 || !Number.isSafeInteger(update.lastTransientOrdinal) || update.lastTransientOrdinal < 0 || !Array.isArray(update.changes) || update.changes.length > 128 || !update.changes.every((change) => {
+        if (!change || typeof change !== "object" || typeof change.transientId !== "string" || change.transientId.length === 0) {
+          return false;
+        }
+        if (change.removed === true) return change.item === void 0;
+        const item = change.item;
+        return Boolean(
+          item && typeof item === "object" && !Array.isArray(item) && item.id === change.transientId
+        );
+      })) {
+        console.warn("[Granular] Ignoring invalid feed_transient_patch");
+        return;
+      }
+      const currentVersion = documentVersion(this.doc);
+      if (update.documentEpoch > currentVersion.epoch || update.documentEpoch === currentVersion.epoch && update.documentRevision > currentVersion.revision || update.documentEpoch < currentVersion.epoch || update.documentEpoch === currentVersion.epoch && update.documentRevision < currentVersion.revision) {
+        return;
+      }
+      const current = Automerge__namespace.toJS(this.doc);
+      const feed = current.feed;
+      if (!feed || typeof feed !== "object" || Array.isArray(feed)) return;
+      if (Number.isSafeInteger(feed.revision) && feed.revision > update.feedRevision) {
+        return;
+      }
+      if (Number.isSafeInteger(feed.lastTransientOrdinal) && feed.lastTransientOrdinal > update.lastTransientOrdinal) {
+        return;
+      }
+      if (!feed.transientById || typeof feed.transientById !== "object") {
+        feed.transientById = {};
+      }
+      for (const change of update.changes) {
+        if (change.removed === true) {
+          delete feed.transientById[change.transientId];
+        } else {
+          feed.transientById[change.transientId] = change.item;
+        }
+      }
+      feed.revision = update.feedRevision;
+      feed.lastTransientOrdinal = update.lastTransientOrdinal;
+      this.doc = Automerge__namespace.from(current);
+      this.emit("feed_transient_patch", update);
+      this.emit("sync", this.doc);
+      return;
+    }
     if ("type" in message && message.type === "snapshot_reset") {
       const resetMessage = message;
       try {
-        if (!Number.isSafeInteger(resetMessage.documentEpoch) || resetMessage.documentEpoch <= 0 || !Number.isSafeInteger(resetMessage.documentRevision) || resetMessage.documentRevision < 0 || !Array.isArray(resetMessage.data)) {
+        if (!Number.isSafeInteger(resetMessage.documentEpoch) || resetMessage.documentEpoch <= 0 || !Number.isSafeInteger(resetMessage.documentRevision) || resetMessage.documentRevision < 0 || !Array.isArray(resetMessage.data) && (!resetMessage.document || typeof resetMessage.document !== "object" || Array.isArray(resetMessage.document))) {
           throw new Error("snapshot_reset metadata is invalid");
         }
-        const replacement = Automerge__namespace.load(
+        const replacement = resetMessage.document ? Automerge__namespace.from(resetMessage.document) : Automerge__namespace.load(
           this.decodeDocumentBytes(
             resetMessage.data,
             "Automerge snapshot_reset"
@@ -21713,7 +21835,10 @@ var WSClient = class {
             "snapshot_reset metadata does not match the saved document"
           );
         }
-        if (!this.canAcceptDocumentReplacement(replacement, true)) {
+        const isJsonReplacement = Boolean(resetMessage.document);
+        if (!this.canAcceptDocumentReplacement(replacement, !isJsonReplacement, {
+          allowEqualRevisionPresentation: isJsonReplacement
+        })) {
           if (this.documentRepairRequired) {
             this.requireDocumentResync(
               "Stale Automerge snapshot_reset during document repair",
@@ -23907,6 +24032,11 @@ function validateProjectionResult(declaration, projection) {
       "projection.source.version"
     );
   }
+  if (projection.source.versionScope !== void 0 && projection.source.versionScope !== "global" && projection.source.versionScope !== "target") {
+    throw new Error(
+      "projection.source.versionScope must be 'global' or 'target'"
+    );
+  }
   if (!Array.isArray(projection.changes)) {
     throw new Error("projection.changes must be an array");
   }
@@ -24823,6 +24953,104 @@ function buildEffectMetamodelMutations(toolPath, spec) {
   );
 }
 
+// src/artifact-workflow.ts
+var TERMINAL_WORKFLOW_STEP_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "skipped",
+  "canceled"
+]);
+function isArtifactWorkflowNodeTerminal(nodeOrStatus) {
+  const status = typeof nodeOrStatus === "string" ? nodeOrStatus : nodeOrStatus.status;
+  return TERMINAL_WORKFLOW_STEP_STATUSES.has(status);
+}
+function isNavigationOnlyOperation(workflow, node) {
+  const hasExplicitTransitionLeaf = getArtifactWorkflowNodes(workflow).some(
+    (candidate) => candidate.childIds.length === 0 && candidate.kind === "transition"
+  );
+  return hasExplicitTransitionLeaf && node.childIds.length === 0 && node.kind === "operation" && // A terminal operation is redundant once authored state-path leaves are
+  // available. While it is still delivering/synchronizing, however, it is
+  // the only honest representation of the work still in progress.
+  isArtifactWorkflowNodeTerminal(node);
+}
+function isArtifactWorkflowNodeNavigableLeaf(workflow, node) {
+  return node.childIds.length === 0 && !isNavigationOnlyOperation(workflow, node);
+}
+function isArtifactWorkflowNodeActionable(node) {
+  return node.availability === "available" && ["current", "needs_input", "working", "blocked", "failed"].includes(
+    node.status
+  );
+}
+function getArtifactWorkflowNodes(workflow) {
+  const visit = (id) => {
+    const node = workflow.nodesById[id];
+    return node ? [node, ...node.childIds.flatMap(visit)] : [];
+  };
+  return workflow.rootNodeIds.flatMap(visit);
+}
+function assertArtifactWorkflow(workflow) {
+  if (workflow.schemaVersion !== 1)
+    throw new Error("Unsupported artifact workflow schema");
+  if (!Number.isSafeInteger(workflow.revision) || workflow.revision < 1) {
+    throw new Error("Artifact workflow revision must be a positive integer");
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const visiting = /* @__PURE__ */ new Set();
+  const nodes = [];
+  const visit = (id, expectedParentId) => {
+    const node = workflow.nodesById[id];
+    if (!node) throw new Error(`Artifact workflow node ${id} does not exist`);
+    if (visiting.has(id)) throw new Error("Artifact workflow contains a cycle");
+    if (visited.has(id))
+      throw new Error("Artifact workflow contains a duplicate node reference");
+    if (node.parentId !== expectedParentId) {
+      throw new Error(`Artifact workflow node ${id} has an invalid parent`);
+    }
+    visiting.add(id);
+    nodes.push(node);
+    node.childIds.forEach((childId) => visit(childId, id));
+    visiting.delete(id);
+    visited.add(id);
+  };
+  workflow.rootNodeIds.forEach((id) => visit(id, null));
+  if (visited.size !== Object.keys(workflow.nodesById).length) {
+    throw new Error("Artifact workflow contains unreachable nodes");
+  }
+  if (workflow.currentNodeId && !workflow.nodesById[workflow.currentNodeId]) {
+    throw new Error("Artifact workflow current node does not exist");
+  }
+  const currentNode = workflow.currentNodeId ? workflow.nodesById[workflow.currentNodeId] : null;
+  if (currentNode && currentNode.childIds.length > 0) {
+    throw new Error("Artifact workflow current node must be actionable leaf");
+  }
+  const actionable = nodes.filter(
+    (node) => isArtifactWorkflowNodeNavigableLeaf(workflow, node) && isArtifactWorkflowNodeActionable(node)
+  );
+  if (actionable.length > 1)
+    throw new Error("Artifact workflow has multiple current nodes");
+  if (actionable.length === 1 && actionable[0].id !== workflow.currentNodeId) {
+    throw new Error("Artifact workflow current node does not own its action");
+  }
+  if (workflow.currentNodeId && !actionable.length && !isArtifactWorkflowNodeTerminal(currentNode)) {
+    throw new Error("Artifact workflow current node is not actionable");
+  }
+}
+function requireArtifactWorkflow(artifact) {
+  if (!artifact.workflow) {
+    throw new Error(
+      `Artifact ${artifact.artifactId} has no canonical workflow`
+    );
+  }
+  assertArtifactWorkflow(artifact.workflow);
+  if (artifact.workflow.artifactId !== artifact.artifactId) {
+    throw new Error("Artifact workflow belongs to a different artifact");
+  }
+  return artifact;
+}
+function requireArtifactWorkflowResult(result) {
+  requireArtifactWorkflow(result.artifact);
+  return result;
+}
+
 // src/client.ts
 var DEFAULT_CONVERSATION_SESSION_LIST_LIMIT = 100;
 var MAX_CONVERSATION_SESSION_LIST_LIMIT = 500;
@@ -26666,6 +26894,7 @@ var EnvironmentSession = class extends Session {
   sessionDataHeaders;
   beforeMutationSend;
   heartbeatTimer = null;
+  heartbeatProbeInFlight = false;
   /** The last known graph container status, updated by checkReadiness(). */
   graphContainerStatus = null;
   constructor(client, environment, clientId, options = {}) {
@@ -26685,16 +26914,34 @@ var EnvironmentSession = class extends Session {
    * an application RPC may be delayed by Durable Object work even while the
    * underlying WebSocket is healthy.
    */
-  startHeartbeat() {
+  startHeartbeat(options = {}) {
     if (this.heartbeatTimer) return;
-    this.heartbeatTimer = setInterval(() => {
-      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);
+    const probeServer = options.probeServer === true;
+    this.heartbeatTimer = setInterval(
+      () => {
+        if (!this.client.isTransportOpen()) return;
+        if (probeServer) {
+          if (this.heartbeatProbeInFlight) return;
+          if (this.client.hasPendingRpcRequests()) return;
+          if (this.client.hasRecentInboundActivity(1e4)) return;
+          this.heartbeatProbeInFlight = true;
+          void this.client.call("client.heartbeat", {}).catch((error2) => {
+            if (this.client.isTransportOpen()) {
+              this.client.reportTransportFailure(error2);
+            }
+          }).finally(() => {
+            this.heartbeatProbeInFlight = false;
+          });
+          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")
+        );
+      },
+      probeServer ? 1e4 : 5e3
+    );
     this.heartbeatTimer.unref?.();
   }
   stopHeartbeat() {
@@ -26702,10 +26949,15 @@ var EnvironmentSession = class extends Session {
       clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = null;
     }
+    this.heartbeatProbeInFlight = false;
   }
   async hello() {
     const result = await super.hello();
-    this.startHeartbeat();
+    if (result.features?.serverHeartbeat === false) {
+      this.startHeartbeat({ probeServer: true });
+    } else {
+      this.startHeartbeat();
+    }
     return result;
   }
   get environmentId() {
@@ -26891,7 +27143,10 @@ var EnvironmentSession = class extends Session {
           queryOptions.targetId = options.target.id;
           delete queryOptions.target;
         }
-        return this.sessionDataRequest("/artifacts", queryOptions);
+        return this.sessionDataRequest("/artifacts", queryOptions).then((page) => ({
+          ...page,
+          items: page.items.map(requireArtifactWorkflow)
+        }));
       },
       listForLatestJob: (options = {}) => this.artifacts.list({
         ...options,
@@ -26904,7 +27159,7 @@ var EnvironmentSession = class extends Session {
         // `cache: no-store`; this also bypasses intermediaries that ignore
         // the Fetch cache directive for an otherwise identical GET URL.
         { _granularLiveRead: Date.now() }
-      ),
+      ).then(requireArtifactWorkflow),
       create: (artifact) => this.sessionDataRequest(
         "/artifacts",
         void 0,
@@ -26912,7 +27167,7 @@ var EnvironmentSession = class extends Session {
           method: "POST",
           body: artifact
         }
-      ),
+      ).then(requireArtifactWorkflow),
       acceptSuggestion: (sequence) => this.sessionDataRequest(
         "/artifacts/suggestions/accept",
         void 0,
@@ -26920,7 +27175,7 @@ var EnvironmentSession = class extends Session {
           method: "POST",
           body: { sequence }
         }
-      ),
+      ).then(requireArtifactWorkflow),
       updateInputs: (artifactId, patch) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}`,
         void 0,
@@ -26928,7 +27183,7 @@ var EnvironmentSession = class extends Session {
           method: "PATCH",
           body: patch
         }
-      ),
+      ).then(requireArtifactWorkflow),
       relationshipOptions: (artifactId, input) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}/relationship-options`,
         void 0,
@@ -26938,27 +27193,27 @@ var EnvironmentSession = class extends Session {
         `/artifacts/${encodeURIComponent(artifactId)}/relationship-create`,
         void 0,
         { method: "POST", body: input }
-      ),
+      ).then(requireArtifactWorkflow),
       validate: (artifactId) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}/validate`,
         void 0,
         { method: "POST" }
-      ),
+      ).then(requireArtifactWorkflowResult),
       execute: (artifactId, options) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}/execute`,
         void 0,
         { method: "POST", body: options }
-      ),
+      ).then(requireArtifactWorkflowResult),
       approve: (artifactId, options) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}/approve`,
         void 0,
         { method: "POST", body: options }
-      ),
+      ).then(requireArtifactWorkflowResult),
       cancel: (artifactId) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}/cancel`,
         void 0,
         { method: "POST" }
-      )
+      ).then(requireArtifactWorkflow)
     };
   }
   get manualActions() {

package/dist/{client-D1gq4TO4.d.ts → client-JCISbded.d.ts}

@@ -1,4 +1,4 @@
-import { dh as WSClientOptions, a7 as SessionFeedApi, bb as GranularQuotaProgress, T as ToolWithHandler, q as PublishToolsResult, ch as Job, r as ToolHandler, I as InstanceToolHandler, ck as UserMessageInput, cl as UserMessageAppendResult, c4 as EffectInfo, n as Prompt, c3 as ToolInfo, c6 as EffectsChangedEvent, c5 as ToolsChangedEvent, D as DomainState, aa as FeedListTransport, aT as GranularOptions, dO as EnvironmentImporter, aW as RecordUserOptions, aV as User, aY as OpenEnvironmentOptions, E as EnvironmentData, aS as AccessTokenProvider, bl as BuildPolicy, dL as EnvironmentSetupSummary, b2 as ConversationSessionListOptions, b0 as ConversationSessionInfo, b3 as ConversationSessionListResponse, a$ as CreateSessionOptions, h as RecordObjectOptions, dy as RecordObjectResult, dA as RecordObjectsOptions, dH as RecordImport, dD as RecordImportStatus, dG as RecordImportItem, a as EnvironmentRecordImportSummary, cf as EnvironmentFeedbackRecord, m as SessionHeapSnapshot, d5 as SessionDocumentResult, cm as AssistantReplyPublicationInput, cn as AssistantReplyPublicationResult, d6 as SessionCollectionListOptions, d8 as SessionCollectionListResult, cq as SessionTimelineEvent, d7 as SessionJobListOptions, c_ as SessionJobRecord, bP as SessionMutationView, cB as SessionArtifactListOptions, cA as SessionArtifactRecord, cD as SessionArtifactRelationshipOptionsInput, cF as SessionArtifactRelationshipOptionsResult, cG as SessionArtifactRelationshipCreateInput, cC as SessionArtifactValidationResult, cI as SessionArtifactExecutionOptions, cH as SessionArtifactExecutionResult, cJ as SessionArtifactApprovalOptions, cT as RecordManualActionInput, cV as ManualActionRecordResult, cW as ManualActionListOptions, cU as ManualActionOccurrence, cY as ManualActionSuggestionOptions, cX as ManualActionSuggestion, cM as ArtifactApprovalTaskListOptions, cL as ArtifactApprovalTask, cN as ArtifactApprovalDecisionInput, cO as ArtifactApprovalDecisionResult, cu as SessionFileRecord, cZ as SessionFileUploadOptions, S as SessionHeapEntry, k as SessionHeapList, d1 as SessionHeapVariable, o as SessionTranscriptEntry, eg as GraphQLResult, d3 as RecordSearchOptions, d2 as RecordSearchResult, d4 as RecordMentionInput, dr as DefineRelationshipOptions, dq as RelationshipInfo, dp as ModelRef, i as ManifestContent, dv as EnvironmentStateUpdateInput, dt as EnvironmentStateTarget, dx as EnvironmentStateProxy, dC as RecordImportOptions, dd as UserEnvironmentStateOptions, dc as UserEnvironmentState, de as MarkUserEnvironmentReadOptions, d as ProjectionMapper, bI as EffectProjectionResult, bN as ExternalCommitOptions, C as CommitReceipt, bJ as TransitionProjectionResult, bO as ObservationReceipt, aZ as AdoptEnvironmentOptions, a_ as ConnectOptions, dJ as RunEnvironmentImporterOptions, aF as OpenAIUsageSpendEvent, aE as GranularSpendContext, aH as RecordOpenAIUsageSpendResult, be as SandboxListResponse, bc as Sandbox, bd as CreateSandboxData, ei as DeleteResponse, bg as PermissionProfile, bh as CreatePermissionProfileData, bo as CreateEnvironmentData, ej as StreamEvent, ek as StreamSubscription, el as StreamStats, aX as Subject, bk as AssignmentListResponse } from './spend-B-IQmp7F.js';
+import { du as WSClientOptions, ab as SessionFeedApi, bf as GranularQuotaProgress, T as ToolWithHandler, t as PublishToolsResult, cl as Job, u as ToolHandler, I as InstanceToolHandler, co as UserMessageInput, cp as UserMessageAppendResult, c8 as EffectInfo, n as Prompt, c7 as ToolInfo, ca as EffectsChangedEvent, c9 as ToolsChangedEvent, D as DomainState, ae as FeedListTransport, aX as GranularOptions, e0 as EnvironmentImporter, a_ as RecordUserOptions, aZ as User, b0 as OpenEnvironmentOptions, E as EnvironmentData, aW as AccessTokenProvider, bp as BuildPolicy, dZ as EnvironmentSetupSummary, b6 as ConversationSessionListOptions, b4 as ConversationSessionInfo, b7 as ConversationSessionListResponse, b3 as CreateSessionOptions, h as RecordObjectOptions, dM as RecordObjectResult, dO as RecordObjectsOptions, dV as RecordImport, dR as RecordImportStatus, dU as RecordImportItem, a as EnvironmentRecordImportSummary, cj as EnvironmentFeedbackRecord, m as SessionHeapSnapshot, dh as SessionDocumentResult, cq as AssistantReplyPublicationInput, cr as AssistantReplyPublicationResult, di as SessionCollectionListOptions, dk as SessionCollectionListResult, cu as SessionTimelineEvent, dj as SessionJobListOptions, da as SessionJobRecord, bT as SessionMutationView, cN as SessionArtifactListOptions, r as SessionArtifactRecord, cP as SessionArtifactRelationshipOptionsInput, cR as SessionArtifactRelationshipOptionsResult, cS as SessionArtifactRelationshipCreateInput, cO as SessionArtifactValidationResult, cU as SessionArtifactExecutionOptions, cT as SessionArtifactExecutionResult, cV as SessionArtifactApprovalOptions, d3 as RecordManualActionInput, d5 as ManualActionRecordResult, d6 as ManualActionListOptions, d4 as ManualActionOccurrence, d8 as ManualActionSuggestionOptions, d7 as ManualActionSuggestion, cY as ArtifactApprovalTaskListOptions, cX as ArtifactApprovalTask, cZ as ArtifactApprovalDecisionInput, c_ as ArtifactApprovalDecisionResult, cy as SessionFileRecord, d9 as SessionFileUploadOptions, S as SessionHeapEntry, k as SessionHeapList, dd as SessionHeapVariable, o as SessionTranscriptEntry, eu as GraphQLResult, df as RecordSearchOptions, de as RecordSearchResult, dg as RecordMentionInput, dF as DefineRelationshipOptions, dE as RelationshipInfo, dD as ModelRef, i as ManifestContent, dJ as EnvironmentStateUpdateInput, dH as EnvironmentStateTarget, dL as EnvironmentStateProxy, dQ as RecordImportOptions, dq as UserEnvironmentStateOptions, dp as UserEnvironmentState, dr as MarkUserEnvironmentReadOptions, d as ProjectionMapper, bM as EffectProjectionResult, bR as ExternalCommitOptions, C as CommitReceipt, bN as TransitionProjectionResult, bS as ObservationReceipt, b1 as AdoptEnvironmentOptions, b2 as ConnectOptions, dX as RunEnvironmentImporterOptions, aJ as OpenAIUsageSpendEvent, aI as GranularSpendContext, aL as RecordOpenAIUsageSpendResult, bi as SandboxListResponse, bg as Sandbox, bh as CreateSandboxData, ew as DeleteResponse, bk as PermissionProfile, bl as CreatePermissionProfileData, bs as CreateEnvironmentData, ex as StreamEvent, ey as StreamSubscription, ez as StreamStats, a$ as Subject, bo as AssignmentListResponse } from './spend-lJDtuAr6.js';
 import * as Automerge from '@automerge/automerge';
 import { Doc } from '@automerge/automerge/slim';
 
@@ -194,6 +194,12 @@ declare class Session {
         ok: boolean;
         environmentId?: string;
         docId?: string;
+        features?: {
+            /** Whether the server sends application-level heartbeat frames. */
+            serverHeartbeat?: boolean;
+            /** Whether the server expects a hibernatable WebSocket lifecycle. */
+            hibernatingWebSocket?: boolean;
+        };
         graphContainerStatus?: {
             lastKeepAliveAt: number;
             status: "warming" | "hot" | "unknown";
@@ -794,6 +800,7 @@ declare class EnvironmentSession extends Session {
     private readonly sessionDataHeaders;
     private readonly beforeMutationSend?;
     private heartbeatTimer;
+    private heartbeatProbeInFlight;
     /** The last known graph container status, updated by checkReadiness(). */
     graphContainerStatus: {
         lastKeepAliveAt: number;
@@ -824,6 +831,10 @@ declare class EnvironmentSession extends Session {
         ok: boolean;
         environmentId?: string;
         docId?: string;
+        features?: {
+            serverHeartbeat?: boolean;
+            hibernatingWebSocket?: boolean;
+        };
         graphContainerStatus?: {
             lastKeepAliveAt: number;
             status: "warming" | "hot" | "unknown";
@@ -888,13 +899,22 @@ declare class EnvironmentSession extends Session {
     get mutations(): {
         list: (options?: {
             limit?: number;
+            compact?: boolean;
         }) => Promise<{
             items: SessionMutationView[];
         }>;
     };
     get artifacts(): {
-        list: (options?: SessionArtifactListOptions) => Promise<SessionCollectionListResult<SessionArtifactRecord>>;
-        listForLatestJob: (options?: Omit<SessionArtifactListOptions, "jobId" | "latestJob">) => Promise<SessionCollectionListResult<SessionArtifactRecord>>;
+        list: (options?: SessionArtifactListOptions) => Promise<{
+            items: SessionArtifactRecord[];
+            nextCursor: string | null;
+            totalCount: number;
+        }>;
+        listForLatestJob: (options?: Omit<SessionArtifactListOptions, "jobId" | "latestJob">) => Promise<{
+            items: SessionArtifactRecord[];
+            nextCursor: string | null;
+            totalCount: number;
+        }>;
         get: (artifactId: string) => Promise<SessionArtifactRecord>;
         create: (artifact: Partial<SessionArtifactRecord> & {
             label: string;