@granular-software/sdk 0.4.44 → 0.4.46

package/dist/index.mjs

@@ -4000,6 +4000,9 @@ var MAX_TIMER_DELAY_MS = 2147483647;
 var DEBUG_WS = process.env.GRANULAR_DEBUG_WS === "1";
 var DEFAULT_RPC_TIMEOUT_MS = 3e4;
 var DOMAIN_PACKAGE_RPC_TIMEOUT_MS = 12e4;
+var EFFECT_CONTROL_RPC_TIMEOUT_MS = 12e4;
+var DEFAULT_RECONNECT_DELAY_MS = 3e3;
+var DEFAULT_MAX_RECONNECT_ATTEMPTS = 5;
 function debugWs(...args) {
   if (DEBUG_WS) {
     console.log(...args);
@@ -4010,6 +4013,10 @@ function rpcTimeoutMsForMethod(method) {
     case "domain.fetchPackagePart":
     case "domain.getSummary":
       return DOMAIN_PACKAGE_RPC_TIMEOUT_MS;
+    case "client.heartbeat":
+    case "effects.publishCatalog":
+    case "effects.refresh":
+      return EFFECT_CONTROL_RPC_TIMEOUT_MS;
     default:
       return DEFAULT_RPC_TIMEOUT_MS;
   }
@@ -4029,6 +4036,7 @@ var WSClient = class {
   reconnectTimer = null;
   tokenRefreshTimer = null;
   isExplicitlyDisconnected = false;
+  reconnectAttempts = 0;
   options;
   constructor(options) {
     this.options = options;
@@ -4183,6 +4191,7 @@ var WSClient = class {
               clearTimeout(this.reconnectTimer);
               this.reconnectTimer = null;
             }
+            this.reconnectAttempts = 0;
             this.emit("open", {});
             resolve();
           });
@@ -4214,6 +4223,7 @@ var WSClient = class {
               clearTimeout(this.reconnectTimer);
               this.reconnectTimer = null;
             }
+            this.reconnectAttempts = 0;
             this.emit("open", {});
             resolve();
           };
@@ -4273,7 +4283,8 @@ var WSClient = class {
     return new Error(`WebSocket disconnected${suffix}`);
   }
   handleDisconnect(close = {}) {
-    const reconnectDelayMs = 3e3;
+    const baseReconnectDelayMs = typeof this.options.reconnectDelayMs === "number" && Number.isFinite(this.options.reconnectDelayMs) && this.options.reconnectDelayMs > 0 ? this.options.reconnectDelayMs : DEFAULT_RECONNECT_DELAY_MS;
+    const maxReconnectAttempts = typeof this.options.maxReconnectAttempts === "number" && Number.isFinite(this.options.maxReconnectAttempts) && this.options.maxReconnectAttempts >= 0 ? Math.floor(this.options.maxReconnectAttempts) : DEFAULT_MAX_RECONNECT_ATTEMPTS;
     const unexpected = !this.isExplicitlyDisconnected;
     const info = {
       code: close.code,
@@ -4293,6 +4304,30 @@ var WSClient = class {
       const disconnectError = this.buildDisconnectError(info);
       this.rejectPending(disconnectError);
       this.emit("disconnect", info);
+      if (this.reconnectAttempts >= maxReconnectAttempts) {
+        const reconnectInfo = {
+          error: `WebSocket reconnect attempts exhausted after ${maxReconnectAttempts} attempt(s).`,
+          sessionId: this.sessionId,
+          timestamp: Date.now()
+        };
+        this.emit("reconnect_error", reconnectInfo);
+        if (this.options.onReconnectError) {
+          try {
+            this.options.onReconnectError(reconnectInfo);
+          } catch (callbackError) {
+            console.error(
+              "[Granular] onReconnectError callback failed:",
+              callbackError
+            );
+          }
+        }
+        return;
+      }
+      this.reconnectAttempts += 1;
+      const reconnectDelayMs = Math.min(
+        3e4,
+        baseReconnectDelayMs * 2 ** Math.max(0, this.reconnectAttempts - 1)
+      );
       info.reconnectScheduled = true;
       info.reconnectDelayMs = reconnectDelayMs;
       if (this.options.onUnexpectedClose) {
@@ -4747,6 +4782,9 @@ var Session = class {
   promptCache = /* @__PURE__ */ new Map();
   /** Prompt ids locally answered before the document sync catches up. */
   hiddenPromptIds = /* @__PURE__ */ new Set();
+  domainPackagePartCache = /* @__PURE__ */ new Map();
+  domainPackagePartPromises = /* @__PURE__ */ new Map();
+  domainPackageFetchQueue = Promise.resolve();
   constructor(client, clientId, options = {}) {
     this.client = client;
     this.clientId = clientId || `client_${Date.now()}`;
@@ -4954,12 +4992,18 @@ var Session = class {
     const resolvedAnswer = resolvePromptAnswer(prompt, answer);
     this.promptCache.delete(promptId);
     this.hiddenPromptIds.add(promptId);
+    this.emit("prompt", { id: promptId, status: "answered" });
     try {
-      await this.client.call("prompt.answer", {
+      const response = await this.client.call("prompt.answer", {
         promptId,
         answer: resolvedAnswer,
         value: resolvedAnswer
       });
+      if (response && typeof response === "object" && "ok" in response && response.ok === false) {
+        const rejected = response;
+        const errorMessage = typeof rejected.error === "string" ? rejected.error : "Prompt answer was rejected.";
+        throw new Error(errorMessage);
+      }
     } catch (error) {
       this.hiddenPromptIds.delete(promptId);
       if (prompt) {
@@ -5187,11 +5231,33 @@ var Session = class {
    * Fetch a domain package part from the backend (no fallback).
    */
   async fetchDomainPart(part) {
-    const result = await this.client.call("domain.fetchPackagePart", {
-      moduleSpecifier: "@sandbox/domain",
-      part
+    const cached = this.domainPackagePartCache.get(part);
+    if (cached !== void 0) {
+      return cached;
+    }
+    const inFlight = this.domainPackagePartPromises.get(part);
+    if (inFlight) {
+      return inFlight;
+    }
+    const fetchPromise = this.domainPackageFetchQueue.then(async () => {
+      const result = await this.client.call("domain.fetchPackagePart", {
+        moduleSpecifier: "@sandbox/domain",
+        part
+      });
+      const content = result?.content ?? "";
+      this.domainPackagePartCache.set(part, content);
+      return content;
     });
-    return result?.content ?? "";
+    this.domainPackagePartPromises.set(part, fetchPromise);
+    this.domainPackageFetchQueue = fetchPromise.then(
+      () => void 0,
+      () => void 0
+    );
+    try {
+      return await fetchPromise;
+    } finally {
+      this.domainPackagePartPromises.delete(part);
+    }
   }
   /**
    * Get TypeScript class declarations for the current domain (for LLM/code gen).
@@ -5441,7 +5507,10 @@ import { ${allImports} } from "./sandbox-tools";
     const emitPrompt = (payload) => {
       const prompt = normalizePrompt(payload);
       if (!prompt) return;
-      this.hiddenPromptIds.delete(prompt.id);
+      if (this.hiddenPromptIds.has(prompt.id)) {
+        this.emit("prompt", { ...prompt, status: "answered" });
+        return;
+      }
       this.promptCache.set(prompt.id, prompt);
       this.emit("prompt", prompt);
     };
@@ -13052,6 +13121,7 @@ var LOCAL_CONTROL_REQUEST_RETRY_DELAY_MS = 500;
 var SESSION_DATA_REQUEST_RETRY_COUNT = 4;
 var SESSION_DATA_REQUEST_RETRY_DELAY_MS = 500;
 var EFFECT_HOST_CONNECT_TIMEOUT_MS = 15e3;
+var SESSION_CONNECT_TIMEOUT_MS = 15e3;
 function filenameFromUploadBody(body) {
   const maybe = body;
   return typeof maybe.name === "string" && maybe.name.trim() ? maybe.name.trim() : null;
@@ -13071,7 +13141,7 @@ function bodyInitFromSessionFileUpload(body) {
   }
   return body;
 }
-var EFFECT_CATALOG_SYNC_TIMEOUT_MS = 3e4;
+var EFFECT_CATALOG_SYNC_TIMEOUT_MS = 12e4;
 var EFFECT_CATALOG_SYNC_RETRY_COUNT = 3;
 var EFFECT_CATALOG_SYNC_RETRY_DELAY_MS = 1e3;
 function planRecordObjectsChunks(records, batchSize) {
@@ -15027,7 +15097,14 @@ var Granular = class _Granular {
     return tag;
   }
   buildManagedEnvironmentName(tag, versionId) {
-    return `__sdk__${tag}__${versionId}`;
+    return `__sdk__${tag}__${versionId}__pinned`;
+  }
+  isManagedEnvironmentName(environment, tagName) {
+    const name = environment.environment || environment.envName || "";
+    return name.startsWith(`__sdk__${tagName}__`);
+  }
+  isPinnedToVersion(environment, versionId) {
+    return environment.buildPolicy.mode === "pinned" && (environment.versionId === versionId || environment.buildPolicy.versionId === versionId || environment.buildPolicy.buildId === versionId);
   }
   matchesTagTrackedEnvironment(environment, tagName, tagId) {
     const environmentTagName = environment.tag?.name || environment.buildPolicy.tagName || null;
@@ -15088,7 +15165,7 @@ var Granular = class _Granular {
     );
     const currentMatches = this.sortEnvironmentsByRecency(
       userEnvironments.filter(
-        (environment) => this.matchesTagTrackedEnvironment(environment, tagName, tag.tagId) && environment.versionId === targetVersionId
+        (environment) => this.matchesTagTrackedEnvironment(environment, tagName, tag.tagId) && environment.versionId === targetVersionId && (!this.isManagedEnvironmentName(environment, tagName) || this.isPinnedToVersion(environment, targetVersionId))
       )
     );
     if (currentMatches.length > 0) {
@@ -15117,6 +15194,7 @@ var Granular = class _Granular {
         subjectId: user.granularId,
         environment: this.buildManagedEnvironmentName(tagName, targetVersionId),
         tagId: tag.tagId,
+        versionId: targetVersionId,
         permissionProfileId: null
       }),
       requestedOntology: ontology,
@@ -15162,6 +15240,7 @@ var Granular = class _Granular {
         row.summaryUpdatedAt ?? row.summary_updated_at
       ) : null,
       subjectId: row.subjectId != null ? String(row.subjectId) : null,
+      sessionScope: row.sessionScope != null || row.session_scope != null ? String(row.sessionScope ?? row.session_scope) : null,
       jobCount: typeof row.jobCount === "number" ? row.jobCount : void 0,
       toolCallCount: typeof row.toolCallCount === "number" ? row.toolCallCount : void 0
     };
@@ -15369,7 +15448,11 @@ var Granular = class _Granular {
       onUnexpectedClose: this.onUnexpectedClose,
       onReconnectError: this.onReconnectError
     });
-    await client.connect();
+    await withTimeout(
+      client.connect(),
+      SESSION_CONNECT_TIMEOUT_MS,
+      `session WebSocket connect for ${session.sessionId}`
+    );
     const environmentSession = new EnvironmentSession(
       client,
       environment,
@@ -15540,12 +15623,24 @@ var Granular = class _Granular {
     host.heartbeatInFlight = false;
   }
   async synchronizeEffectHost(host) {
-    await host.wsClient.call("client.hello", {
-      clientId: host.clientId,
-      protocolVersion: "2.0"
-    });
-    this.startEffectHostHeartbeat(host);
-    await this.publishSandboxEffectCatalog(host);
+    if (host.syncPromise) {
+      return host.syncPromise;
+    }
+    host.syncPromise = (async () => {
+      await host.wsClient.call("client.hello", {
+        clientId: host.clientId,
+        protocolVersion: "2.0"
+      });
+      await this.publishSandboxEffectCatalog(host);
+      this.startEffectHostHeartbeat(host);
+    })();
+    try {
+      await host.syncPromise;
+    } finally {
+      if (host.syncPromise) {
+        host.syncPromise = null;
+      }
+    }
   }
   async ensureSandboxEffectHost(sandboxId) {
     const existing = this.sandboxEffectHosts.get(sandboxId);
@@ -15581,7 +15676,8 @@ var Granular = class _Granular {
         wsClient,
         heartbeatTimer: null,
         heartbeatInFlight: false,
-        recovering: false
+        recovering: false,
+        syncPromise: null
       };
       wsClient.registerRpcHandler("effect.invoke", async (params) => {
         const request = params;
@@ -17688,7 +17784,8 @@ function buildGranularAgentSessionBlock(sessionContext) {
     runtimeId: sessionContext?.sandboxId || null,
     environmentId: sessionContext?.environmentId || null,
     userName: sessionContext?.userName || null,
-    domainRevision: sessionContext?.domainRevision || null
+    domainRevision: sessionContext?.domainRevision || null,
+    uiContext: sessionContext?.uiContext || null
   });
 }
 function buildGranularAgentHeapBlock(heapSummary) {
@@ -17935,7 +18032,7 @@ function buildGranularAgentToolBlock(tools, capabilityOverrides) {
     const rightScope = `${right.className || "global"}:${right.static ? "static" : "instance"}`;
     return leftScope.localeCompare(rightScope) || left.name.localeCompare(right.name);
   });
-  const writeActions = normalizedTools.filter((tool) => tool.ready !== false).map((tool) => {
+  const availableActions = normalizedTools.filter((tool) => tool.ready !== false).map((tool) => {
     const scope = tool.className ? `${tool.static ? "class" : "record"}:${tool.className}` : "global";
     return {
       name: tool.name,
@@ -17946,7 +18043,8 @@ function buildGranularAgentToolBlock(tools, capabilityOverrides) {
   const capabilities = {
     executeCode: resolvedCapabilities.executeCode,
     readEntities: resolvedCapabilities.readEntities,
-    writeActions,
+    availableActions,
+    writeActions: availableActions,
     workflowHelpers: resolvedCapabilities.workflowHelpers,
     savedData: resolvedCapabilities.savedData,
     showRecords: resolvedCapabilities.showRecords
@@ -17960,7 +18058,7 @@ function buildGranularAgentActionIndex(tools) {
     return leftScope.localeCompare(rightScope) || left.name.localeCompare(right.name);
   });
   if (normalizedTools.length === 0) {
-    return "No domain write actions are available.";
+    return "No executable actions are available.";
   }
   const globalTools = normalizedTools.filter((tool) => !tool.className);
   const staticTools = normalizedTools.filter(
@@ -18054,6 +18152,76 @@ function splitDomainDocumentation(domainDocumentation) {
   }
   return { types: normalized, docs: "" };
 }
+var DOMAIN_HELPER_FUNCTION_NAMES = /* @__PURE__ */ new Set([
+  "agent_heap_objects",
+  "agent_message",
+  "agent_text_message"
+]);
+function inferGlobalActionToolsFromDomainTypes(domainTypes) {
+  const inferred = [];
+  const seen = /* @__PURE__ */ new Set();
+  const declarationPattern = /(?:export\s+)?declare\s+function\s+([A-Za-z_$][\w$]*)\s*\(/g;
+  let match;
+  while (match = declarationPattern.exec(domainTypes)) {
+    const name = match[1];
+    if (!name || DOMAIN_HELPER_FUNCTION_NAMES.has(name) || seen.has(name)) {
+      continue;
+    }
+    seen.add(name);
+    inferred.push({
+      name,
+      description: "Executable global action declared by the domain runtime."
+    });
+  }
+  const actionLinePattern = /^-\s*([A-Za-z_$][\w$]*)\s+\(global\):\s*(.+)$/gm;
+  while (match = actionLinePattern.exec(domainTypes)) {
+    const name = match[1];
+    if (!name || DOMAIN_HELPER_FUNCTION_NAMES.has(name) || seen.has(name)) {
+      continue;
+    }
+    seen.add(name);
+    inferred.push({
+      name,
+      description: match[2]?.trim() || "Executable global action declared by the domain runtime."
+    });
+  }
+  const scopedActionLinePattern = /^-\s*([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)\s+\((record|class)\):\s*(.+)$/gm;
+  while (match = scopedActionLinePattern.exec(domainTypes)) {
+    const className = match[1]?.toLowerCase();
+    const name = match[2];
+    const scope = match[3];
+    if (!className || !name || DOMAIN_HELPER_FUNCTION_NAMES.has(name)) {
+      continue;
+    }
+    const key = `${className}:${scope}:${name}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    inferred.push({
+      name,
+      className,
+      static: scope === "class",
+      description: match[4]?.trim() || "Executable action declared by the domain runtime."
+    });
+  }
+  return inferred;
+}
+function resolvePromptTools(tools, domainTypes) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const tool of tools || []) {
+    if (!tool?.name) continue;
+    const key = `${tool.className || "global"}:${tool.static ? "static" : "instance"}:${tool.name}`;
+    byKey.set(key, tool);
+  }
+  for (const tool of inferGlobalActionToolsFromDomainTypes(domainTypes)) {
+    const key = `global:instance:${tool.name}`;
+    if (!byKey.has(key)) {
+      byKey.set(key, tool);
+    }
+  }
+  return [...byKey.values()];
+}
 function buildGranularAgentCheckpointBlock(checkpoint) {
   if (!checkpoint) {
     return renderConstBlock("previousCodeResult", null);
@@ -18126,12 +18294,13 @@ function buildGranularAgentSystemPrompt(input) {
   const outputMode = input.outputMode || "agentMessages";
   const promptCapabilities = resolvePromptCapabilities(input.capabilities);
   const domainSections = splitDomainDocumentation(input.domainDocumentation);
+  const promptTools = resolvePromptTools(input.tools, domainSections.types);
   const sessionBlock = buildGranularAgentSessionBlock(input.sessionContext);
   const toolBlock = buildGranularAgentToolBlock(
-    input.tools,
+    promptTools,
     input.capabilities
   );
-  const actionIndex = buildGranularAgentActionIndex(input.tools);
+  const actionIndex = buildGranularAgentActionIndex(promptTools);
   const domainBlock = buildGranularAgentDomainBlock(domainSections.types);
   const workflowBlock = buildGranularAgentWorkflowBlock(input.workflowSummary);
   const checkpointBlock = buildGranularAgentCheckpointBlock(input.checkpoint);
@@ -18159,7 +18328,7 @@ function buildGranularAgentSystemPrompt(input) {
   - When \`agent_text_message(...)\` mentions a grounded record that should remain clickable/referable, wrap only the visible record label in a self-closing inline reference tag: \`<granular-object class="class_name" id="stable_id_or_path" label="Visible label" />\`. Use the actual class name and stable id/path from the runtime record or effect result; do not invent ids, field names, or snake/camel-case aliases that are not present in the type declarations or returned object.
   - Treat \`agent_heap_objects(...)\` as the UI display call for user-visible records, not as a general storage helper. Do not wrap records under an \`items\` key.
   - When records should remain reusable for follow-ups, first save the runtime record or ordered record array with \`await heap.setVar("stable_selection_name", value)\`, then display that saved selection exactly once with \`await agent_heap_objects({ variableNames: ["stable_selection_name"] })\`.
-  - \`heap.setVar(...)\` only accepts scalar values, runtime records/sandbox instances, or arrays of runtime records/sandbox instances. Do not save plain action/effect result objects. If an action returns an id/path for a created record that should remain referable, fetch the created record first, then save/display that fetched record.
+  - \`heap.setVar(...)\` only accepts scalar values, runtime records/sandbox instances, or arrays of runtime records/sandbox instances from one class. Do not save plain action/effect result objects or arrays of JSON summaries returned by actions. If an action returns ids/paths for records that should remain referable or displayed as records, fetch the matching runtime records first with the generated class \`.get(...)\`/query API, then save/display those fetched records. If the action returned only structured summaries, answer from those summaries with \`agent_text_message(...)\`.
   - Do not use \`agent_heap_objects({ entries: [...] })\` or \`agent_heap_objects({ saveAs, entries })\` as a shortcut for ordered pages, queues, search results, or ranked lists; those forms can create duplicate or poorly labelled displays. Save the selection with \`heap.setVar(...)\` and display it via \`variableNames\` instead.
   - Use \`entryPaths\` only for a few already-known individual records and \`listNames\` only for a host-created list that you intentionally want to show. Do not display both an entry/list selection and a heap variable for the same records.
   - When the user asks to show, list, display, open, or "show them" for records you found, call \`agent_heap_objects(...)\`; do not answer only with a count or text summary.
@@ -18209,10 +18378,11 @@ ${outputRules}` : `Code:
 - Use choice only for 2 to 5 short grounded options.
 - For record choices, set each option value to a stable scalar such as the record \`_graphPath\` or \`id\`, not a label-only value.
 - After \`await loop.ask_user(...)\` returns from a choice prompt, tolerate either the option value, the option object, or a human-readable label by matching against value, id/path, label, and description before failing. If a returned label is a prefix or substring of exactly one option label, treat it as that option.
-- Use \`loop.confirm(...)\` for yes/no confirmation only when the user explicitly asks for confirmation, action or permission metadata requires it, policy requires it, or material uncertainty remains after grounding.
+- Use \`loop.confirm(...)\` for yes/no confirmation only when the user explicitly asks for a separate confirmation step, policy requires confirmation outside the action runtime, or material uncertainty remains after grounding.
+- If action, effect, tool, or permission metadata already marks the invoked action as confirmation-gated, do not call \`loop.confirm(...)\` before invoking it. Ground the target and input, then call the action once; the runtime action policy will surface the confirmation prompt and resume the same invocation after approval.
 - Do not add a generic yes/no confirmation after the user has already made a grounded choice, unless one of those confirmation conditions still applies.
-- Do not add confirmation only because an allowed mutation is visible to other people, customer-facing, or consequential. If the user clearly requested the mutation and the grounded target, action, and condition are unique, perform the mutation unless confirmation is required by the user, policy, action metadata, or remaining material uncertainty.
-- A conditional request such as "if this is true, do that" is authorization to perform the requested action after you verify the condition. Once the condition, target, and action are grounded uniquely, call the action directly; do not ask "should I perform/post/send this?" unless the user, policy, action metadata, or unresolved material uncertainty requires confirmation. The visibility or impact of an allowed action is not by itself unresolved uncertainty.
+- Do not add confirmation only because an allowed mutation is visible to other people, customer-facing, or consequential. If the user clearly requested the mutation and the grounded target, action, and condition are unique, perform the mutation unless confirmation is required outside the action runtime or remaining material uncertainty exists.
+- A conditional request such as "if this is true, do that" is authorization to perform the requested action after you verify the condition. Once the condition, target, and action are grounded uniquely, call the action directly; do not ask "should I perform/post/send this?" unless the user, policy outside the action runtime, or unresolved material uncertainty requires confirmation. The visibility or impact of an allowed action is not by itself unresolved uncertainty.
 - If the user explicitly asks you to stop for confirmation, natural-language text such as "please confirm" is not enough: call \`await loop.confirm(...)\` before the mutation, then perform the approved mutation in the same resumed job when it returns true.
 - Reuse existing task, decision, and closure ids from [State].
 - If a user request matches both a domain record/action and a workflow helper, prefer the domain capability.` : "";
@@ -18358,7 +18528,8 @@ Query policy:
 - For operational blocker, risk, status, or "what is happening" questions, inspect the relevant record's scalar fields such as status, priority, blocker, summary, latest update/message, due date, amount, and other domain-specific descriptive fields before answering.
 - For read-only readiness, risk, health, or status summaries, call any visible read-only assessment/status action on the grounded primary record before ad-hoc aggregation when such an action semantically matches the request. Use the returned fields in the reply and supplement with counts or record reads only when useful.
 - Do not hide required visible read-only assessment/status actions inside broad try/catch blocks. The runtime action surface should show that the assessment action ran.
-- Treat action/effect results as structured values, not necessarily arrays. Before indexing, iterating, checking \`.length\`, or calling array methods, normalize the result first: use the result itself only when \`Array.isArray(result)\`; otherwise read the exact array field shown in the output schema, or a documented array field such as \`items\`, \`matches\`, \`results\`, \`records\`, \`entries\`, \`candidates\`, \`options\`, or a domain-specific array field. Never convert a non-array object result to \`[]\` before checking its documented fields.
+- Treat action/effect results as structured values, not necessarily arrays. Before indexing, iterating, checking \`.length\`, or calling array methods, normalize the result first: use the result itself only when \`Array.isArray(result)\`; otherwise read the exact array field shown in the output schema, or a documented array field such as \`items\`, \`matches\`, \`results\`, \`records\`, \`entries\`, \`candidates\`, \`options\`, \`requests\`, \`vendors\`, \`transactions\`, \`approvals\`, \`receipts\`, or another domain-specific array field. If a structured result has \`count > 0\`, never conclude there are no matches until you inspect every array-valued field on that result object, especially fields named by the output schema. Never convert a non-array object result to \`[]\` before checking its documented fields.
+- Plain JSON objects returned by actions are not sandbox record instances, even when they contain ids, titles, labels, or status fields. Use them for reasoning and text responses. Do not pass action-returned JSON objects or arrays directly to \`heap.setVar(...)\` or \`agent_heap_objects(...)\`; fetch corresponding runtime records first when the user needs record display or follow-up references.
 - When a visible search, lookup, availability, or assessment action returns candidates or matches, treat those returned records as already scoped by the action inputs unless the output schema gives reliable fields for further narrowing. When matching returned candidates to grounded records, use the output schema's actual identifier fields, including \`id\`, \`path\`, or fields ending in \`Id\`; do not assume candidates have \`_graphPath\`. Do not discard all returned candidates by re-filtering on guessed property names.
 - For scheduling actions, convert relative wording into concrete ISO timestamps before mutating records.
 - When a decision depends on fresh external state and a visible read-only status/lookup action exists on the grounded record, call it before deciding, mutating, or refusing based on stale stored fields.
@@ -18420,6 +18591,7 @@ ${domainSections.docs}
 
 Actions:
 ${actionIndex}
+- Global actions are executable functions exported by "./sandbox-tools"; import each global action you call, e.g. \`import { some_action } from "./sandbox-tools"; await some_action(...)\`. This includes frontend actions such as opening, focusing, or navigating the host UI.
 - Actions listed under "Record-level" are instance methods. First fetch or find the specific record, then call the action on that instance, e.g. \`const item = await Item.get({ path }); await item.action_name(...)\`.
 - Actions listed under "Class-level" are class/static methods. Call them on the imported class, e.g. \`await Item.action_name(...)\`.
 - The action index is the visibility contract. If an action is listed for a class, call it directly on fetched/listed instances of that class; do not use \`typeof record.action_name === "function"\` as a discovery gate. If an action is not listed, do not call it.