@granular-software/sdk 0.4.70 → 0.4.72

package/dist/agent-evals.d.mts

@@ -1,5 +1,5 @@
-import { a as EnvironmentSession, G as Granular } from './client-qgWZ495o.mjs';
-import { aE as GranularSpendContext, az as OpenAITokenSpend, n as Prompt, h as RecordObjectOptions, i as ManifestContent, m as SessionHeapSnapshot, T as ToolWithHandler, a_ as ConnectOptions, bo as CreateEnvironmentData, aT as GranularOptions } from './spend-B-IQmp7F.mjs';
+import { a as EnvironmentSession, G as Granular } from './client-p5EhOwpP.mjs';
+import { aI as GranularSpendContext, aD as OpenAITokenSpend, n as Prompt, h as RecordObjectOptions, i as ManifestContent, m as SessionHeapSnapshot, T as ToolWithHandler, b2 as ConnectOptions, bs as CreateEnvironmentData, aX as GranularOptions } from './spend-lJDtuAr6.mjs';
 import { GranularAgentToolInfo, GeneratedJobCodeIssue, BuildGranularAgentSystemPromptInput, HarnessRenderedPrompt, HarnessRenderedContinuation, HarnessControllerBudgets } from './agent-harness.mjs';
 import '@automerge/automerge';
 import '@automerge/automerge/slim';
@@ -415,6 +415,7 @@ declare function createOpenAIChatTurnGenerator(options: {
     model?: string;
     baseUrl?: string;
     temperature?: number;
+    reasoningEffort?: "low" | "medium" | "high";
     headers?: Record<string, string>;
     usageContext?: GranularSpendContext;
     onUsage?: (usage: AgentEvalOpenAIUsageEvent) => void | Promise<void>;
@@ -470,6 +471,7 @@ interface AgentTesterOptions {
         model?: string;
         baseUrl?: string;
         temperature?: number;
+        reasoningEffort?: "low" | "medium" | "high";
         headers?: Record<string, string>;
     };
     model?: string;

package/dist/agent-evals.d.ts

@@ -1,5 +1,5 @@
-import { a as EnvironmentSession, G as Granular } from './client-D1gq4TO4.js';
-import { aE as GranularSpendContext, az as OpenAITokenSpend, n as Prompt, h as RecordObjectOptions, i as ManifestContent, m as SessionHeapSnapshot, T as ToolWithHandler, a_ as ConnectOptions, bo as CreateEnvironmentData, aT as GranularOptions } from './spend-B-IQmp7F.js';
+import { a as EnvironmentSession, G as Granular } from './client-JCISbded.js';
+import { aI as GranularSpendContext, aD as OpenAITokenSpend, n as Prompt, h as RecordObjectOptions, i as ManifestContent, m as SessionHeapSnapshot, T as ToolWithHandler, b2 as ConnectOptions, bs as CreateEnvironmentData, aX as GranularOptions } from './spend-lJDtuAr6.js';
 import { GranularAgentToolInfo, GeneratedJobCodeIssue, BuildGranularAgentSystemPromptInput, HarnessRenderedPrompt, HarnessRenderedContinuation, HarnessControllerBudgets } from './agent-harness.js';
 import '@automerge/automerge';
 import '@automerge/automerge/slim';
@@ -415,6 +415,7 @@ declare function createOpenAIChatTurnGenerator(options: {
     model?: string;
     baseUrl?: string;
     temperature?: number;
+    reasoningEffort?: "low" | "medium" | "high";
     headers?: Record<string, string>;
     usageContext?: GranularSpendContext;
     onUsage?: (usage: AgentEvalOpenAIUsageEvent) => void | Promise<void>;
@@ -470,6 +471,7 @@ interface AgentTesterOptions {
         model?: string;
         baseUrl?: string;
         temperature?: number;
+        reasoningEffort?: "low" | "medium" | "high";
         headers?: Record<string, string>;
     };
     model?: string;

package/dist/agent-evals.js

@@ -5317,6 +5317,38 @@ function stableDocumentFingerprint(value) {
     (key) => `${JSON.stringify(key)}:${stableDocumentFingerprint(record[key])}`
   ).join(",")}}`;
 }
+function canonicalDocumentFingerprint(value) {
+  const stripPresentation = (input, path2) => {
+    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, path2));
+    }
+    const record = input;
+    const output = {};
+    for (const [key, entry] of Object.entries(record)) {
+      if (path2.length === 1 && path2[0] === "feed" && [
+        "transientById",
+        "feedbackUsageByJob",
+        "revision",
+        "lastTransientOrdinal"
+      ].includes(key)) {
+        continue;
+      }
+      if (path2.length === 3 && path2[0] === "jobs" && path2[1] === "byId" && [
+        "actionTrace",
+        "actionSummary",
+        "actionSummaryText",
+        "lastActionAt"
+      ].includes(key)) {
+        continue;
+      }
+      output[key] = stripPresentation(entry, [...path2, key]);
+    }
+    return output;
+  };
+  return stableDocumentFingerprint(stripPresentation(value, []));
+}
 function debugWs(...args) {
   if (DEBUG_WS) {
     console.log(...args);
@@ -5634,6 +5666,7 @@ var WSClient = class {
         }
         this.lastInboundActivityAt = Date.now();
         this.reconnectAttempts = 0;
+        this.connectPromise = null;
         this.emit("open", {});
         finish();
       };
@@ -5796,7 +5829,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) {
@@ -5845,7 +5878,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."
       );
@@ -5967,6 +6000,7 @@ var WSClient = class {
       reconnectScheduled: false
     };
     this.ws = null;
+    this.connectPromise = null;
     this.emit("close", info);
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
@@ -6004,13 +6038,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 job = current.jobs?.byId?.[update.jobId];
+      if (job && typeof job === "object" && !Array.isArray(job)) {
+        job.actionTrace = update.actionTrace;
+        job.actionSummary = update.actionSummary;
+        job.actionSummaryText = update.actionSummaryText;
+        const lastEvent = update.actionTrace[update.actionTrace.length - 1];
+        if (lastEvent && typeof lastEvent.timestamp === "number") {
+          job.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"
@@ -6024,7 +6134,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",
@@ -12369,6 +12482,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(),
@@ -12453,6 +12567,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()
 ]);
@@ -12802,6 +12917,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 } : {}
   };
 }
@@ -12927,7 +13043,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 }`.'
       }
     ]
   },
@@ -13160,6 +13276,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");
   }
@@ -14817,6 +14938,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),
@@ -14888,6 +15010,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))}`
@@ -15199,7 +15324,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!
       }
 
@@ -15257,6 +15382,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
         to: StateMachineState!
         label: String
         description: String
+        user_visible: Boolean
         action_json: String
         assignee_json: String
         requirements_json: String
@@ -15338,6 +15464,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
             to,
             label,
             description,
+            user_visible,
             action_json,
             assignee_json,
             requirements_json,
@@ -15355,6 +15482,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
                 {
                   label,
                   description,
+                  userVisible: user_visible,
                   actionJson: action_json,
                   assigneeJson: assignee_json,
                   requirementsJson: requirements_json,
@@ -15419,6 +15547,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,
@@ -15505,6 +15634,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
             to { name }
             label
             description
+            user_visible
             action_json
             assignee_json
             requirements_json
@@ -15814,6 +15944,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;
@@ -17657,6 +17885,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 = {}) {
@@ -17676,16 +17905,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((error) => {
+            if (this.client.isTransportOpen()) {
+              this.client.reportTransportFailure(error);
+            }
+          }).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() {
@@ -17693,10 +17940,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() {
@@ -17882,7 +18134,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,
@@ -17895,7 +18150,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,
@@ -17903,7 +18158,7 @@ var EnvironmentSession = class extends Session {
           method: "POST",
           body: artifact
         }
-      ),
+      ).then(requireArtifactWorkflow),
       acceptSuggestion: (sequence) => this.sessionDataRequest(
         "/artifacts/suggestions/accept",
         void 0,
@@ -17911,7 +18166,7 @@ var EnvironmentSession = class extends Session {
           method: "POST",
           body: { sequence }
         }
-      ),
+      ).then(requireArtifactWorkflow),
       updateInputs: (artifactId, patch) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}`,
         void 0,
@@ -17919,7 +18174,7 @@ var EnvironmentSession = class extends Session {
           method: "PATCH",
           body: patch
         }
-      ),
+      ).then(requireArtifactWorkflow),
       relationshipOptions: (artifactId, input) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}/relationship-options`,
         void 0,
@@ -17929,27 +18184,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() {
@@ -22663,6 +22918,10 @@ ${actionIndex}
 - 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.
+- Preserve explicit qualifiers from the user's requested object identity, including quantities, product names, and named organizational scope. Do not shorten a title in a way that drops those qualifiers when they distinguish what is being created.
+- A contextual or ontology default may fill a value only when the user supplied no conflicting intent for that semantic role. If the user names a team, owner, account, location, or other scope that cannot be grounded, leave that relationship unresolved; never substitute the current actor's default or another convenient visible record.
+- A missing or inaccessible required relationship is not a reason to replace a reviewable action with a lookup-failure reply. Call the reviewable action with every grounded non-relationship value, omit the unresolved relationship, and let the artifact collect it from the user. This applies even when the user explicitly named the unavailable relationship.
+- Choose enum values from the request's meaning and the ontology-authored option semantics. Do not choose an enum merely because it makes an available default relationship, budget, policy, or downstream option compatible. If no enum is semantically supported, leave it unresolved or ask.
 - 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.
@@ -23838,6 +24097,9 @@ ${modelOutputInstruction()}`
     if (typeof options.temperature === "number") {
       payload.temperature = options.temperature;
     }
+    if (options.reasoningEffort) {
+      payload.reasoning_effort = options.reasoningEffort;
+    }
     let lastError = null;
     for (let attempt = 1; attempt <= 3; attempt += 1) {
       try {
@@ -26163,6 +26425,7 @@ function createAgentTester(options) {
     model: options.openai?.model || options.model,
     baseUrl: options.openai?.baseUrl,
     temperature: options.openai?.temperature,
+    reasoningEffort: options.openai?.reasoningEffort,
     headers: options.openai?.headers,
     onUsage: async (usage) => {
       await granular.recordOpenAIUsageSpend(usage, usage.usageContext);