@granular-software/sdk 0.4.36 → 0.4.38

package/dist/index.mjs

@@ -3929,11 +3929,22 @@ var TOKEN_REFRESH_LEEWAY_MS = 2 * 60 * 1e3;
 var TOKEN_REFRESH_RETRY_MS = 30 * 1e3;
 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;
 function debugWs(...args) {
   if (DEBUG_WS) {
     console.log(...args);
   }
 }
+function rpcTimeoutMsForMethod(method) {
+  switch (method) {
+    case "domain.fetchPackagePart":
+    case "domain.getSummary":
+      return DOMAIN_PACKAGE_RPC_TIMEOUT_MS;
+    default:
+      return DEFAULT_RPC_TIMEOUT_MS;
+  }
+}
 var WSClient = class {
   ws = null;
   url;
@@ -4358,13 +4369,14 @@ var WSClient = class {
     return new Promise((resolve, reject) => {
       this.messageQueue.push({ resolve, reject, id });
       this.ws.send(JSON.stringify(request));
+      const timeoutMs = rpcTimeoutMsForMethod(method);
       setTimeout(() => {
         const pending = this.messageQueue.find((q) => q.id === id);
         if (pending) {
           this.messageQueue = this.messageQueue.filter((q) => q.id !== id);
           reject(new Error(`RPC timeout: ${method}`));
         }
-      }, 3e4);
+      }, timeoutMs);
     });
   }
   async handleIncomingRpc(request) {
@@ -4478,10 +4490,48 @@ function normalizePromptText(value) {
 function extractPromptTokens(value) {
   return normalizePromptText(value).split(/\s+/).map((token) => token.trim()).filter((token) => token.length > 0);
 }
+function parseJsonPromptChoiceOption(option) {
+  const trimmed = option.trim();
+  if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    return asRecord(parsed);
+  } catch {
+    return null;
+  }
+}
+function normalizePromptChoiceOption(option) {
+  if (typeof option === "string") {
+    const record2 = parseJsonPromptChoiceOption(option);
+    if (!record2) {
+      return { value: option, label: option };
+    }
+    const value2 = typeof record2.value === "string" ? record2.value : typeof record2.id === "string" ? record2.id : typeof record2.label === "string" ? record2.label : JSON.stringify(record2);
+    return {
+      value: value2,
+      label: typeof record2.label === "string" ? record2.label : value2,
+      description: typeof record2.description === "string" ? record2.description : void 0
+    };
+  }
+  const record = option;
+  if (!record) {
+    return { value: "", label: "" };
+  }
+  const nestedJson = (typeof record.value === "string" ? parseJsonPromptChoiceOption(record.value) : null) || (typeof record.label === "string" ? parseJsonPromptChoiceOption(record.label) : null);
+  if (nestedJson) {
+    return normalizePromptChoiceOption(nestedJson);
+  }
+  const value = typeof record.value === "string" ? record.value : typeof record.label === "string" ? record.label : JSON.stringify(record);
+  return {
+    value,
+    label: typeof record.label === "string" ? record.label : value,
+    description: typeof record.description === "string" ? record.description : void 0
+  };
+}
 function scorePromptChoiceMatch(answer, answerTokens, option) {
-  const value = typeof option === "string" ? option : typeof option?.value === "string" ? option.value : "";
-  const label = typeof option === "string" ? option : typeof option?.label === "string" ? option.label : "";
-  const description = typeof option === "string" ? "" : typeof option?.description === "string" ? option.description : "";
+  const choice = normalizePromptChoiceOption(option);
+  const { value, label } = choice;
+  const description = choice.description || "";
   const haystack = normalizePromptText([value, label, description].filter(Boolean).join(" "));
   if (!haystack) return { score: 0, resolvedValue: value || label || null };
   let score = 0;
@@ -4517,7 +4567,9 @@ function normalizePrompt(rawValue) {
     type: normalizePromptType(source === raw ? raw : { ...raw, ...source }),
     title: typeof source.title === "string" ? source.title : "Input required",
     message: typeof source.message === "string" ? source.message : "",
-    options: Array.isArray(source.options) ? source.options : void 0,
+    options: Array.isArray(source.options) ? source.options.map(
+      (option) => typeof option === "string" || asRecord(option) ? normalizePromptChoiceOption(option) : option
+    ) : void 0,
     defaultValue: source.defaultValue,
     placeholder: typeof source.placeholder === "string" ? source.placeholder : void 0,
     allowEmpty: typeof source.allowEmpty === "boolean" ? source.allowEmpty : void 0,
@@ -4545,9 +4597,26 @@ function resolvePromptAnswer(prompt, answer) {
 }
 
 // src/session.ts
+var PROMPT_TRANSCRIPT_APPEND_TIMEOUT_MS = 5e3;
+function withPromptTranscriptTimeout(promise) {
+  let timeout = null;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timeout = setTimeout(() => {
+        reject(new Error("Timed out appending prompt answer transcript."));
+      }, PROMPT_TRANSCRIPT_APPEND_TIMEOUT_MS);
+    })
+  ]).finally(() => {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  });
+}
 var Session = class {
   client;
   clientId;
+  initialQuota;
   jobsMap = /* @__PURE__ */ new Map();
   pendingAgentMessagesByJobId = /* @__PURE__ */ new Map();
   eventListeners = /* @__PURE__ */ new Map();
@@ -4561,9 +4630,12 @@ var Session = class {
   lastKnownTools = /* @__PURE__ */ new Map();
   /** Last seen live prompts, keyed by prompt id, for answer normalization */
   promptCache = /* @__PURE__ */ new Map();
-  constructor(client, clientId) {
+  /** Prompt ids locally answered before the document sync catches up. */
+  hiddenPromptIds = /* @__PURE__ */ new Set();
+  constructor(client, clientId, options = {}) {
     this.client = client;
     this.clientId = clientId || `client_${Date.now()}`;
+    this.initialQuota = options.initialQuota || null;
     this.setupEventHandlers();
     this.setupToolInvokeHandler();
   }
@@ -4612,6 +4684,16 @@ var Session = class {
   get document() {
     return this.client.doc;
   }
+  get quota() {
+    return this.getQuota();
+  }
+  getQuota() {
+    const quota = this.client.doc.billing?.quota;
+    if (quota && typeof quota === "object") {
+      return quota;
+    }
+    return this.initialQuota;
+  }
   get sessionId() {
     return this.client.currentSessionId;
   }
@@ -4696,8 +4778,9 @@ var Session = class {
    * `effect.invoke` RPC back to the sandbox effect host, where the registered handlers
    * execute locally and return the result to the sandbox.
    */
-  async submitJob(code, domainRevision) {
-    let revision = domainRevision || this.currentDomainRevision || this.extractDomainRevisionFromDoc(this.client.doc) || void 0;
+  async submitJob(code, domainRevisionOrOptions) {
+    const options = typeof domainRevisionOrOptions === "string" ? { domainRevision: domainRevisionOrOptions } : domainRevisionOrOptions || {};
+    let revision = options.domainRevision || this.currentDomainRevision || this.extractDomainRevisionFromDoc(this.client.doc) || void 0;
     if (!revision) {
       try {
         const summary = await this.getDomain();
@@ -4712,7 +4795,9 @@ var Session = class {
     }
     const result = await this.client.call("job.submit", {
       domainRevision: revision,
-      code
+      code,
+      metadata: options.metadata,
+      agent: options.agent
     });
     if (!result.jobId) {
       throw new Error("Failed to submit job: no jobId returned");
@@ -4753,25 +4838,39 @@ var Session = class {
     const prompt = this.promptCache.get(promptId);
     const resolvedAnswer = resolvePromptAnswer(prompt, answer);
     this.promptCache.delete(promptId);
-    await this.client.call("prompt.answer", {
-      promptId,
-      answer: resolvedAnswer,
-      value: resolvedAnswer
-    });
+    this.hiddenPromptIds.add(promptId);
+    try {
+      await this.client.call("prompt.answer", {
+        promptId,
+        answer: resolvedAnswer,
+        value: resolvedAnswer
+      });
+    } catch (error) {
+      this.hiddenPromptIds.delete(promptId);
+      if (prompt) {
+        this.promptCache.set(promptId, prompt);
+      }
+      throw error;
+    }
     try {
       const content = this.stringifyConversationValue(resolvedAnswer);
       if (content.trim()) {
-        await this.appendConversationMessage({
-          role: "user",
-          content,
-          promptId
-        });
+        await withPromptTranscriptTimeout(
+          this.appendConversationMessage({
+            role: "user",
+            content,
+            promptId
+          })
+        );
       }
     } catch {
     }
   }
   async appendConversationMessage(input) {
-    return this.client.call("conversation.append", input);
+    return this.client.call(
+      "conversation.append",
+      input
+    );
   }
   /**
    * Get the current list of available effects.
@@ -4780,9 +4879,53 @@ var Session = class {
   getEffects() {
     const doc = this.client.doc;
     const toolMap = /* @__PURE__ */ new Map();
-    const domainPkg = doc.domain?.packages?.domain;
-    if (domainPkg?.tools && Array.isArray(domainPkg.tools)) {
-      for (const tool of domainPkg.tools) {
+    const domainPackages = doc.domain?.packages;
+    const packageCandidates = domainPackages && typeof domainPackages === "object" ? [
+      domainPackages.domain,
+      domainPackages["@sandbox/domain"],
+      ...Object.values(domainPackages)
+    ].filter(Boolean) : [];
+    for (const domainPkg of packageCandidates) {
+      if (domainPkg?.tools && Array.isArray(domainPkg.tools)) {
+        for (const tool of domainPkg.tools) {
+          if (!tool?.name || toolMap.has(tool.name)) continue;
+          toolMap.set(tool.name, {
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            outputSchema: tool.outputSchema,
+            className: tool.className || void 0,
+            static: tool.static || false,
+            ready: false,
+            publishedAt: void 0
+          });
+        }
+      }
+      if (!domainPkg?.classes || typeof domainPkg.classes !== "object") {
+        continue;
+      }
+      for (const [className, classDef] of Object.entries(
+        domainPkg.classes
+      )) {
+        const methods = Array.isArray(classDef?.methods) ? classDef.methods : [];
+        for (const method of methods) {
+          if (!method?.name || toolMap.has(method.name)) continue;
+          toolMap.set(method.name, {
+            name: method.name,
+            description: method.description,
+            inputSchema: method.inputSchema,
+            outputSchema: method.outputSchema,
+            className: method.className || classDef?.name || className,
+            static: method.static || false,
+            ready: false,
+            publishedAt: void 0
+          });
+        }
+      }
+    }
+    const legacyDomainPkg = doc.domain?.packages?.domain;
+    if (legacyDomainPkg?.tools && Array.isArray(legacyDomainPkg.tools)) {
+      for (const tool of legacyDomainPkg.tools) {
         if (!tool?.name) continue;
         toolMap.set(tool.name, {
           name: tool.name,
@@ -4796,6 +4939,27 @@ var Session = class {
         });
       }
     }
+    if (legacyDomainPkg?.classes && typeof legacyDomainPkg.classes === "object") {
+      for (const [className, classDef] of Object.entries(
+        legacyDomainPkg.classes
+      )) {
+        const methods = Array.isArray(classDef?.methods) ? classDef.methods : [];
+        for (const method of methods) {
+          if (!method?.name || toolMap.has(method.name)) continue;
+          toolMap.set(method.name, {
+            name: method.name,
+            description: method.description,
+            inputSchema: method.inputSchema,
+            outputSchema: method.outputSchema,
+            className: method.className || classDef?.name || className,
+            static: method.static || false,
+            ready: false,
+            publishedAt: void 0
+          });
+        }
+      }
+    }
+    const hasPolicyFilteredDomainTools = toolMap.size > 0;
     const catalogs = doc.catalog?.rawToolCatalogs || {};
     for (const [clientId, catalog] of Object.entries(catalogs)) {
       const cat = catalog;
@@ -4803,6 +4967,7 @@ var Session = class {
       for (const tool of cat.tools) {
         if (!tool?.name) continue;
         const existing = toolMap.get(tool.name);
+        if (hasPolicyFilteredDomainTools && !existing) continue;
         if (existing?.publishedAt && cat.publishedAt && existing.publishedAt > cat.publishedAt)
           continue;
         const isLocal = clientId === this.clientId;
@@ -4822,6 +4987,24 @@ var Session = class {
     }
     return Array.from(toolMap.values());
   }
+  /**
+   * Return the currently open prompt payloads known to this session.
+   *
+   * These come from live `prompt` / `prompt.request` websocket events and
+   * preserve the exact shape used by `answerPrompt(...)`.
+   */
+  getPrompts() {
+    return Array.from(this.promptCache.values()).map((prompt) => ({
+      ...prompt,
+      options: Array.isArray(prompt.options) ? prompt.options.map(
+        (option) => typeof option === "string" ? option : { ...option }
+      ) : void 0,
+      metadata: prompt.metadata ? { ...prompt.metadata } : void 0
+    }));
+  }
+  getHiddenPromptIds() {
+    return Array.from(this.hiddenPromptIds);
+  }
   /**
    * Backwards-compatible alias for `getEffects()`.
    */
@@ -4921,11 +5104,7 @@ var Session = class {
       if (!normalizedDocs) {
         return normalizedTypes;
       }
-      return [
-        normalizedTypes,
-        "Generated usage notes from ./sandbox-tools docs:",
-        normalizedDocs
-      ].join("\n\n");
+      return [normalizedTypes, "[Docs]", normalizedDocs].join("\n\n");
     }
     if (normalizedDocs) {
       return normalizedDocs;
@@ -5147,6 +5326,7 @@ import { ${allImports} } from "./sandbox-tools";
     const emitPrompt = (payload) => {
       const prompt = normalizePrompt(payload);
       if (!prompt) return;
+      this.hiddenPromptIds.delete(prompt.id);
       this.promptCache.set(prompt.id, prompt);
       this.emit("prompt", prompt);
     };
@@ -5329,6 +5509,7 @@ var JobImplementation = class {
   eventListeners = /* @__PURE__ */ new Map();
   bufferedAgentMessages = [];
   bufferedAgentMessageIds = /* @__PURE__ */ new Set();
+  resultSettled = false;
   metadata;
   constructor(id, client, initialState) {
     this.id = id;
@@ -5353,7 +5534,9 @@ var JobImplementation = class {
         if (execData.error) {
           this.finalize("failed", void 0, execData.error);
         } else {
-          this.finalize("succeeded", execData.result);
+          this.finalize("succeeded", execData.result, void 0, {
+            hasResult: Object.prototype.hasOwnProperty.call(execData, "result")
+          });
         }
         this.emit("status", this.status);
       }
@@ -5389,9 +5572,6 @@ var JobImplementation = class {
       if (normalizedStatus === "failed" || normalizedStatus === "timeout" || normalizedStatus === "canceled") {
         this.finalize(normalizedStatus);
       }
-      if (normalizedStatus === "succeeded") {
-        this.finalize("succeeded");
-      }
       this.emit("status", normalizedStatus);
     });
     this.client.on(`job.${id}.stdout`, (line) => {
@@ -5411,7 +5591,7 @@ var JobImplementation = class {
       this.emit("stderr", line);
     });
     this.client.on(`job.${id}.result`, (result) => {
-      this.finalize("succeeded", result);
+      this.finalize("succeeded", result, void 0, { hasResult: true });
     });
     this.client.on(`job.${id}.error`, (error) => {
       this.finalize("failed", void 0, error);
@@ -5432,7 +5612,9 @@ var JobImplementation = class {
     this.client.on("job.completed", (data) => {
       const jobData = data;
       if (jobData.jobId === id) {
-        this.finalize("succeeded", jobData.result);
+        this.finalize("succeeded", jobData.result, void 0, {
+          hasResult: true
+        });
         this.emit("status", this.status);
       }
     });
@@ -5557,7 +5739,7 @@ var JobImplementation = class {
       this.metadata.status = "running";
     }
   }
-  finalize(status, result, error) {
+  finalize(status, result, error, options = {}) {
     if (!this.metadata.startedAt) {
       this.metadata.startedAt = Date.now();
     }
@@ -5565,14 +5747,18 @@ var JobImplementation = class {
     this.metadata.status = status;
     this.metadata.completedAt = this.metadata.completedAt || Date.now();
     this.metadata.durationMs = this.metadata.completedAt - this.metadata.startedAt;
-    if (result !== void 0) {
+    if (!this.resultSettled && (options.hasResult || result !== void 0)) {
       this.metadata.result = sanitizeFeedbackValue(result);
+      this.resultSettled = true;
       this._resolveResult(result);
     }
-    if (error !== void 0) {
-      const message = error instanceof Error ? error.message : String(error);
+    if (!this.resultSettled && (error !== void 0 || status === "failed" || status === "timeout" || status === "canceled")) {
+      const fallbackError = new Error(`Job ${this.id} ${status}.`);
+      const cause = error ?? fallbackError;
+      const message = cause instanceof Error ? cause.message : String(cause);
       this.metadata.error = truncateFeedbackString(message);
-      this._rejectResult(error);
+      this.resultSettled = true;
+      this._rejectResult(cause);
     }
   }
   upsertToolCall(next) {
@@ -5655,6 +5841,17 @@ function humanTextFromStdout(stdout) {
   }
   return null;
 }
+function responseTextFromAgentMessages(agentMessages) {
+  for (const message of [...agentMessages].reverse()) {
+    const record = asRecord2(message);
+    if (!record) continue;
+    for (const key of RESPONSE_KEYS) {
+      const normalized = normalizeText(record[key]);
+      if (normalized) return normalized;
+    }
+  }
+  return null;
+}
 function pushString(target, value) {
   if (typeof value === "string" && value.trim()) {
     target.add(value.trim());
@@ -5680,6 +5877,41 @@ function collectReferencesFromRecord(record, refs) {
   for (const key of VARIABLE_ARRAY_KEY_CANDIDATES)
     pushStringArray(refs.variableNames, record[key]);
 }
+function stringValue(record, keys) {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  return null;
+}
+function findEntryPathForRecord(record, heap) {
+  const directPath = stringValue(record, ["entryPath", "path"]);
+  if (directPath && heap.entriesByPath?.[directPath]) {
+    return directPath;
+  }
+  const id = stringValue(record, ["id", "_id", "recordId", "objectId"]);
+  if (!id) {
+    return null;
+  }
+  const className = stringValue(record, [
+    "className",
+    "_className",
+    "__className",
+    "prototype",
+    "type"
+  ]);
+  const entries = Object.values(heap.entriesByPath || {});
+  const exact = entries.find(
+    (entry) => entry.id === id && (!className || entry.className === className || entry.prototypes?.includes(className))
+  );
+  if (exact?.path) {
+    return exact.path;
+  }
+  const idOnlyMatches = entries.filter((entry) => entry.id === id);
+  return idOnlyMatches.length === 1 ? idOnlyMatches[0].path : null;
+}
 function scanForHeapReferences(value, heap, refs, depth = 0, seen = /* @__PURE__ */ new Set()) {
   if (value === null || value === void 0 || depth > 4 || seen.has(value))
     return;
@@ -5700,6 +5932,8 @@ function scanForHeapReferences(value, heap, refs, depth = 0, seen = /* @__PURE__
   const record = asRecord2(value);
   if (!record) return;
   seen.add(value);
+  const entryPath = findEntryPathForRecord(record, heap);
+  if (entryPath) refs.entryPaths.add(entryPath);
   collectReferencesFromRecord(record, refs);
   for (const key of UI_CONTAINER_KEYS) {
     const nested = asRecord2(record[key]);
@@ -5808,6 +6042,7 @@ function resolveJobPresentation({
   jobId,
   result,
   stdout = [],
+  agentMessages = [],
   sessionHeap,
   allowExplicitArtifacts = true
 }) {
@@ -5840,7 +6075,7 @@ function resolveJobPresentation({
   const hasExplicitArtifacts = allowExplicitArtifacts && (explicitEntries.length > 0 || explicitLists.length > 0);
   const lists = hasExplicitArtifacts ? explicitLists : jobLists;
   const entries = hasExplicitArtifacts ? explicitEntries : changedEntries;
-  const responseText = extractResponseText(result, stdout) || fallbackResponseText(entries, lists);
+  const responseText = extractResponseText(result, stdout) || responseTextFromAgentMessages(agentMessages) || fallbackResponseText(entries, lists);
   return {
     responseText,
     entries,
@@ -10316,6 +10551,67 @@ external_exports.object({
   transitions: external_exports.array(StateMachineTransitionSchema),
   finalStates: external_exports.array(external_exports.string()).optional()
 }).strict();
+var POLICY_OPERATORS = [
+  "eq",
+  "neq",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "contains",
+  "not_contains",
+  "starts_with",
+  "ends_with",
+  "exists"
+];
+var PolicyPredicateSchema = external_exports.object({
+  path: external_exports.union([external_exports.string(), external_exports.array(external_exports.string())]).optional(),
+  field: external_exports.string().optional(),
+  input: external_exports.string().optional(),
+  operator: external_exports.enum([...POLICY_OPERATORS]),
+  stringValue: external_exports.string().optional(),
+  numberValue: external_exports.number().optional(),
+  booleanValue: external_exports.boolean().optional(),
+  value: external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean(), external_exports.null()]).optional()
+}).strict();
+var PolicyStateMachinePredicateSchema = external_exports.object({
+  machine: external_exports.string().min(1),
+  operator: external_exports.enum([...POLICY_OPERATORS]),
+  state: external_exports.string().optional(),
+  stringValue: external_exports.string().optional()
+}).strict();
+var PolicyConditionSchema = external_exports.lazy(
+  () => external_exports.object({
+    all: external_exports.array(PolicyConditionSchema).optional(),
+    any: external_exports.array(PolicyConditionSchema).optional(),
+    not: PolicyConditionSchema.optional(),
+    input: PolicyPredicateSchema.optional(),
+    object: PolicyPredicateSchema.optional(),
+    stateMachine: PolicyStateMachinePredicateSchema.optional()
+  }).strict().refine(
+    (data) => [
+      data.all,
+      data.any,
+      data.not,
+      data.input,
+      data.object,
+      data.stateMachine
+    ].filter((value) => value !== void 0).length === 1,
+    {
+      message: "Policy condition must define exactly one of all, any, not, input, object, or stateMachine"
+    }
+  )
+);
+var PolicyRuleSchema = external_exports.object({
+  id: external_exports.string().min(1).optional(),
+  reason: external_exports.string().optional(),
+  when: PolicyConditionSchema
+}).strict();
+var PoliciesSchema = external_exports.object({
+  allowWhen: external_exports.array(PolicyRuleSchema).optional(),
+  confirmWhen: external_exports.array(PolicyRuleSchema).optional(),
+  denyWhen: external_exports.array(PolicyRuleSchema).optional()
+}).strict();
 external_exports.object({
   postCondition: external_exports.union([
     external_exports.string(),
@@ -10345,7 +10641,8 @@ external_exports.object({
       reason: external_exports.string().optional(),
       mode: external_exports.string().optional()
     }).strict()
-  ]).optional()
+  ]).optional(),
+  policies: PoliciesSchema.optional()
 }).strict();
 
 // ../metamodel-core/src/index.ts
@@ -11019,6 +11316,110 @@ async function invokeRegisteredEffect(effectMap, request) {
   return resolved.handler(request.input, context);
 }
 
+// src/spend.ts
+function toGranularHttpBase(apiUrl) {
+  const url = new URL(apiUrl);
+  if (url.protocol === "ws:") {
+    url.protocol = "http:";
+  } else if (url.protocol === "wss:") {
+    url.protocol = "https:";
+  }
+  url.pathname = url.pathname.replace(/\/ws\/connect$/, "").replace(/\/ws$/, "");
+  if (!url.pathname || url.pathname === "/") {
+    url.pathname = "/granular";
+  }
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/$/, "");
+}
+function cleanIdPart(value) {
+  return value.replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^_+|_+$/g, "");
+}
+function buildOpenAISpendEventId(usage, context = {}) {
+  const requestId = usage.requestId?.trim();
+  if (!requestId) return void 0;
+  const scope = context.sessionId || context.environmentId || context.subjectId || context.sandboxId || "global";
+  return ["spend", "openai", scope, requestId].map(cleanIdPart).join("_");
+}
+function pricingEffectiveAtSeconds(value) {
+  if (!value) return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? Math.floor(parsed / 1e3) : null;
+}
+function compactContext(context) {
+  return Object.fromEntries(
+    Object.entries(context).filter(
+      ([, value]) => value != null && value !== ""
+    )
+  );
+}
+function omitTenantId(context) {
+  const scopedContext = { ...context };
+  delete scopedContext.tenantId;
+  return scopedContext;
+}
+async function recordOpenAIUsageSpend(options) {
+  const usageContext = compactContext({
+    ...options.usage.usageContext || {},
+    ...options.context || {}
+  });
+  const context = omitTenantId(usageContext);
+  const spendEventId = options.usage.spendEventId || buildOpenAISpendEventId(options.usage, context);
+  const metadata = {
+    ...options.metadata || {},
+    ...options.usage.rawUsage !== void 0 ? { openaiUsage: options.usage.rawUsage } : {},
+    usageContext: context
+  };
+  const response = await fetch(
+    `${toGranularHttpBase(options.apiUrl)}/control/spend/events`,
+    {
+      method: "POST",
+      cache: "no-store",
+      headers: {
+        Authorization: `Bearer ${options.token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        ...spendEventId ? { spendEventId } : {},
+        sandboxId: context.sandboxId || null,
+        environmentId: context.environmentId || null,
+        sessionId: context.sessionId || null,
+        subjectId: context.subjectId || null,
+        permissionProfileId: context.permissionProfileId || null,
+        source: "openai",
+        lineItemType: "llm_tokens",
+        provider: options.usage.provider,
+        model: options.usage.model,
+        operation: options.usage.operation || "chat.completions",
+        requestId: options.usage.requestId || null,
+        inputTokens: options.usage.inputTokens,
+        outputTokens: options.usage.outputTokens,
+        cachedInputTokens: options.usage.cachedInputTokens,
+        reasoningTokens: options.usage.reasoningTokens,
+        quantity: options.usage.totalTokens,
+        quantityUnit: "tokens",
+        inputPricePerMillionMicros: options.usage.inputPricePerMillionMicros,
+        cachedInputPricePerMillionMicros: options.usage.cachedInputPricePerMillionMicros,
+        outputPricePerMillionMicros: options.usage.outputPricePerMillionMicros,
+        amountMicros: options.usage.amountMicros,
+        currency: options.usage.currency,
+        pricingSource: options.usage.pricingSource,
+        pricingEffectiveAt: pricingEffectiveAtSeconds(
+          options.usage.pricingEffectiveAt
+        ),
+        estimated: false,
+        metadata
+      })
+    }
+  );
+  if (!response.ok) {
+    throw new Error(
+      `Granular spend event failed (${response.status}): ${await response.text()}`
+    );
+  }
+  return response.json();
+}
+
 // ../metamodel-enum/src/index.ts
 function renderInlineStringUnion(values) {
   return values.map((value) => JSON.stringify(value)).join(" | ");
@@ -11377,6 +11778,148 @@ var noteMetamodelPackage = defineMetamodelPackage({
   }
 });
 
+// ../policy-engine/src/index.ts
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function normalizePath(value) {
+  if (Array.isArray(value)) {
+    return value.map((part) => String(part)).filter(Boolean);
+  }
+  if (typeof value === "string") {
+    return value.includes(".") ? value.split(".").filter(Boolean) : [value];
+  }
+  return [];
+}
+function firstDefinedValue(spec) {
+  if ("value" in spec) return spec.value;
+  if ("stringValue" in spec) return spec.stringValue;
+  if ("numberValue" in spec) return spec.numberValue;
+  if ("booleanValue" in spec) return spec.booleanValue;
+  if ("state" in spec) return spec.state;
+  return void 0;
+}
+function normalizeCondition(input) {
+  if (input === void 0 || input === null) return { kind: "always" };
+  if (!isRecord(input)) {
+    throw new Error("Policy condition must be an object");
+  }
+  if (Array.isArray(input.all)) {
+    return {
+      kind: "all",
+      conditions: input.all.map((item) => normalizeCondition(item))
+    };
+  }
+  if (Array.isArray(input.any)) {
+    return {
+      kind: "any",
+      conditions: input.any.map((item) => normalizeCondition(item))
+    };
+  }
+  if (input.not !== void 0) {
+    return { kind: "not", condition: normalizeCondition(input.not) };
+  }
+  for (const source of ["input", "object", "stateMachine"]) {
+    const raw = input[source];
+    if (!isRecord(raw)) continue;
+    const operator = raw.operator;
+    if (operator !== "eq" && operator !== "neq" && operator !== "gt" && operator !== "gte" && operator !== "lt" && operator !== "lte" && operator !== "contains" && operator !== "not_contains" && operator !== "starts_with" && operator !== "ends_with" && operator !== "exists") {
+      throw new Error(`Unsupported policy operator: ${String(operator)}`);
+    }
+    if (source === "stateMachine") {
+      const machine = typeof raw.machine === "string" ? raw.machine : "";
+      if (!machine) throw new Error("stateMachine condition requires machine");
+      return {
+        kind: "predicate",
+        source,
+        path: [machine],
+        machine,
+        operator,
+        value: firstDefinedValue(raw)
+      };
+    }
+    const path = normalizePath(raw.path ?? raw.field ?? raw.input);
+    if (path.length === 0) {
+      throw new Error(`${source} condition requires a path`);
+    }
+    return {
+      kind: "predicate",
+      source,
+      path,
+      operator,
+      value: firstDefinedValue(raw)
+    };
+  }
+  throw new Error(
+    "Policy condition must contain all, any, not, input, object, or stateMachine"
+  );
+}
+function summarizeCondition(condition) {
+  switch (condition.kind) {
+    case "always":
+      return "always";
+    case "all":
+      return condition.conditions.map(summarizeCondition).join(" and ");
+    case "any":
+      return condition.conditions.map(summarizeCondition).join(" or ");
+    case "not":
+      return `not (${summarizeCondition(condition.condition)})`;
+    case "predicate": {
+      const path = condition.source === "stateMachine" ? `stateMachine.${condition.machine || condition.path.join(".")}` : `${condition.source}.${condition.path.join(".")}`;
+      if (condition.operator === "exists") return `${path} exists`;
+      return `${path} ${condition.operator} ${String(condition.value)}`;
+    }
+  }
+}
+
+// ../metamodel-policy/src/index.ts
+function escapeGraphqlString(value) {
+  return JSON.stringify(value);
+}
+function buildPolicyMutations(effectKey, spec) {
+  const policies = spec.policies;
+  if (!policies) return [];
+  const mutations = [];
+  const addRules = (key, outcome) => {
+    const rules = policies[key] || [];
+    rules.forEach((rule, index) => {
+      const condition = normalizeCondition(rule.when);
+      const summary = rule.reason || summarizeCondition(condition);
+      const id = rule.id || `${effectKey}:${outcome}:${index + 1}`;
+      mutations.push({
+        label: `set policy ${outcome} on ${effectKey}`,
+        query: `mutation { set_policy_rule(effect_key: ${escapeGraphqlString(effectKey)}, policy_id: ${escapeGraphqlString(id)}, outcome: ${escapeGraphqlString(outcome)}, reason: ${escapeGraphqlString(summary)}, condition_json: ${escapeGraphqlString(JSON.stringify(condition))}) }`
+      });
+    });
+  };
+  addRules("allowWhen", "allow");
+  addRules("confirmWhen", "confirm");
+  addRules("denyWhen", "deny");
+  return mutations;
+}
+var policyMetamodelPackage = defineMetamodelPackage({
+  id: "policy",
+  manifest: {
+    buildEffectMutations: buildPolicyMutations
+  },
+  summary: {
+    selections: {
+      methodFields: ["policies"]
+    },
+    readMethodSummary(rawMethod) {
+      return rawMethod.policies ? { metamodels: { policies: rawMethod.policies } } : {};
+    }
+  },
+  docs: {
+    effectRows: [
+      {
+        key: "policies",
+        description: "Universal effect policies with allowWhen, confirmWhen, and denyWhen structural conditions."
+      }
+    ]
+  }
+});
+
 // ../metamodel-required/src/index.ts
 function buildRequiredFieldMutations(fieldPath, required) {
   if (!required) return [];
@@ -12151,7 +12694,8 @@ var DEFAULT_METAMODEL_PACKAGES = [
   searchableMetamodelPackage,
   validationRuleMetamodelPackage,
   stateMachineMetamodelPackage,
-  effectBehaviorsMetamodelPackage
+  effectBehaviorsMetamodelPackage,
+  policyMetamodelPackage
 ];
 createMetamodelRegistry(
   DEFAULT_METAMODEL_PACKAGES
@@ -12218,6 +12762,12 @@ var DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_COUNT = 3;
 var DEFAULT_DIRECT_RECORD_OBJECTS_RETRY_DELAY_MS = 1e3;
 var LOCAL_CONTROL_REQUEST_RETRY_COUNT = 4;
 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 EFFECT_CATALOG_SYNC_TIMEOUT_MS = 3e4;
+var EFFECT_CATALOG_SYNC_RETRY_COUNT = 3;
+var EFFECT_CATALOG_SYNC_RETRY_DELAY_MS = 1e3;
 function planRecordObjectsChunks(records, batchSize) {
   const total = records.length;
   const size = Math.max(1, Math.min(batchSize, total));
@@ -12232,6 +12782,19 @@ function planRecordObjectsChunks(records, batchSize) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function withTimeout(promise, timeoutMs, label) {
+  let timer = null;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  return Promise.race([promise, timeout]).finally(() => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  });
+}
 function isLocalControlUrl(url) {
   try {
     const parsed = new URL(url);
@@ -12245,7 +12808,19 @@ function isRetryableLocalWorkerRestart(status, body, url) {
 }
 function isRetryableRecordObjectsError(error) {
   const message = error instanceof Error ? error.message : String(error);
-  return /worker restarted mid-request|econnreset|network|socket connection was closed unexpectedly|timed out/i.test(
+  return /worker restarted mid-request|econnreset|network|socket connection was closed unexpectedly|timed out|bad gateway|too many requests|gateway timeout|control plane api error \((?:429|500|502|503|504)\)|graphql api error \((?:429|500|502|503|504)\)|failed to record batch/i.test(
+    message
+  );
+}
+function isRetryableEffectRegistrationError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return /timed out|websocket disconnected|websocket not connected|rpc timeout|worker restarted mid-request|network connection lost|bad gateway|gateway timeout|too many requests|(?:control plane|granular|graphql) api error \((?:429|500|502|503|504)\)/i.test(
+    message
+  );
+}
+function isRetryableSessionDataError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return /network connection lost|worker restarted mid-request|econnreset|socket connection was closed unexpectedly|bad gateway|gateway timeout|service unavailable|session data api error \((?:429|500|502|503|504)\)/i.test(
     message
   );
 }
@@ -12267,16 +12842,28 @@ function computeEffectRegistrationKey(effect) {
     effect.versionSelector
   )}`;
 }
-function buildEffectHostUrl(apiUrl, sandboxId, effectClientId, clientId) {
-  const url = new URL(apiUrl);
-  if (url.pathname.endsWith("/granular/ws/connect")) {
+function buildEffectHostUrl(apiUrl, sandboxId, effectClientId, clientId, effectHostUrl) {
+  const overrideUrl = effectHostUrl || process.env.GRANULAR_EFFECT_HOST_URL || process.env.EFFECT_HOST_URL;
+  const api = new URL(apiUrl);
+  const localRuntimeBase = process.env.RUNTIME_ORCHESTRATOR_URL || (isLocalControlUrl(apiUrl) ? `${api.protocol}//${api.hostname}:8791` : "");
+  const url = new URL(overrideUrl || localRuntimeBase || apiUrl);
+  if (url.protocol === "https:") {
+    url.protocol = "wss:";
+  } else if (url.protocol === "http:") {
+    url.protocol = "ws:";
+  }
+  if (!overrideUrl && isLocalControlUrl(apiUrl) && api.pathname.endsWith("/granular")) {
+    url.pathname = "/granular/orchestrator/effects/connect";
+  } else if (url.pathname.endsWith("/granular/ws/connect")) {
     url.pathname = url.pathname.replace(/\/ws\/connect$/, "/effects/connect");
   } else if (url.pathname.endsWith("/granular")) {
-    url.pathname = `${url.pathname.replace(/\/$/, "")}/effects/connect`;
+    url.pathname = isLocalControlUrl(url.toString()) ? "/granular/orchestrator/effects/connect" : `${url.pathname.replace(/\/$/, "")}/effects/connect`;
   } else if (url.pathname.endsWith("/v2/ws/connect")) {
     url.pathname = url.pathname.replace(/\/ws\/connect$/, "/effects/connect");
   } else if (url.pathname.endsWith("/v2/ws")) {
     url.pathname = url.pathname.replace(/\/ws$/, "/effects/connect");
+  } else if (url.pathname === "/" && isLocalControlUrl(url.toString()) && (url.port === "8791" || !overrideUrl && Boolean(localRuntimeBase))) {
+    url.pathname = "/granular/orchestrator/effects/connect";
   } else if (url.pathname.endsWith("/ws/connect")) {
     url.pathname = url.pathname.replace(/\/ws\/connect$/, "/effects/connect");
   } else if (url.pathname.endsWith("/ws")) {
@@ -12311,6 +12898,79 @@ function normalizeHeapSnapshot(raw) {
     updatedAt: typeof heap.updatedAt === "number" ? heap.updatedAt : Date.now()
   };
 }
+function normalizeGraphPathSegment(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+function extractRecordIdFromGraphPath(path, className) {
+  const normalizedPrefix = `${normalizeGraphPathSegment(className)}_`;
+  if (path.startsWith(normalizedPrefix)) {
+    return path.slice(normalizedPrefix.length);
+  }
+  const legacyPrefix = `${className}_`;
+  if (path.startsWith(legacyPrefix)) {
+    return path.slice(legacyPrefix.length);
+  }
+  return path;
+}
+function toRecordSearchResult(className, node) {
+  const path = typeof node.path === "string" ? node.path : "";
+  if (!path) return null;
+  const fields = Array.isArray(node.submodels) ? node.submodels.flatMap(
+    (submodel) => {
+      const name = typeof submodel?.label === "string" && submodel.label.trim() ? submodel.label : typeof submodel?.path === "string" ? submodel.path.split(":").pop() || submodel.path : "";
+      if (!name) return [];
+      if (typeof submodel.string_value === "string") {
+        return [{ name, type: "string", value: submodel.string_value }];
+      }
+      if (typeof submodel.number_value === "number") {
+        return [{ name, type: "number", value: submodel.number_value }];
+      }
+      if (typeof submodel.boolean_value === "boolean") {
+        return [
+          {
+            name,
+            type: "boolean",
+            value: submodel.boolean_value
+          }
+        ];
+      }
+      return [];
+    }
+  ) : [];
+  return {
+    path,
+    className,
+    id: extractRecordIdFromGraphPath(path, className),
+    label: typeof node.label === "string" && node.label.trim() ? node.label : extractRecordIdFromGraphPath(path, className),
+    description: typeof node.description === "string" && node.description.trim() ? node.description : null,
+    fields
+  };
+}
+function normalizeRecordSearchText(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, " ").replace(/\s+/g, " ").trim();
+}
+function rankRecordSearchResult(result, query, index) {
+  const normalizedQuery = normalizeRecordSearchText(query);
+  if (!normalizedQuery) {
+    return index;
+  }
+  const label = normalizeRecordSearchText(result.label || "");
+  const id = normalizeRecordSearchText(result.id || "");
+  const path = normalizeRecordSearchText(result.path || "");
+  const className = normalizeRecordSearchText(result.className || "");
+  const searchable = [label, id, path, className].filter(Boolean);
+  if (label === normalizedQuery) return index;
+  if (id === normalizedQuery || path === normalizedQuery) return 100 + index;
+  if (label.startsWith(normalizedQuery)) return 200 + index;
+  if (searchable.some((value) => value.startsWith(normalizedQuery))) {
+    return 300 + index;
+  }
+  if (label.includes(normalizedQuery)) return 400 + index;
+  if (searchable.some((value) => value.includes(normalizedQuery))) {
+    return 500 + index;
+  }
+  return 900 + index;
+}
 function deriveRuntimeBaseUrl(apiEndpoint) {
   try {
     const endpoint = new URL(apiEndpoint);
@@ -12399,7 +13059,7 @@ function normalizeEnvironmentData(environment) {
     setup: normalizeEnvironmentSetupSummary(environment.setup)
   };
 }
-var Environment = class {
+var Environment = class _Environment {
   granular;
   envData;
   _apiKey;
@@ -12594,28 +13254,30 @@ var Environment = class {
     return response.json();
   }
   // ==================== ID ↔ GRAPH PATH MAPPING ====================
+  static normalizeGraphPathSegment(value) {
+    return value.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^A-Za-z0-9]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "").toLowerCase();
+  }
   /**
-   * Convert a class name + real-world ID into a unique graph path.
+   * Convert a class name + application record ID into Granular's graph path.
    *
-   * Two objects of *different* classes may share the same real-world ID,
-   * so the graph path must incorporate the class to guarantee uniqueness.
-   *
-   * Format: `{className}_{id}` — deterministic, human-readable.
-   *
-   * **Convention**: class names should be simple identifiers without
-   * underscores (e.g. `author`, `book`).  This ensures the prefix is
-   * unambiguously parseable by `extractIdFromGraphPath`.
+   * This mirrors the record-write path normalization used by the control plane.
+   * Keep the original customer/system ID in `real_id`; graph paths are stable
+   * internal addresses, not the source of truth for business identity.
    */
   static toGraphPath(className, id) {
-    return `${className}_${id}`;
+    return `${_Environment.normalizeGraphPathSegment(className)}_${_Environment.normalizeGraphPathSegment(id)}`;
   }
   /**
-   * Extract the real-world ID from a graph path, given the class name.
+   * Best-effort extraction of an ID-like suffix from a graph path.
    *
-   * Strips the `{className}_` prefix. Returns the raw path if the
-   * expected prefix is not found.
+   * Prefer the record's `real_id` field whenever exact customer/system IDs
+   * matter, because graph path normalization is intentionally lossy.
    */
   static extractIdFromGraphPath(graphPath, className) {
+    const normalizedPrefix = `${_Environment.normalizeGraphPathSegment(className)}_`;
+    if (graphPath.startsWith(normalizedPrefix)) {
+      return graphPath.substring(normalizedPrefix.length);
+    }
     const prefix = `${className}_`;
     return graphPath.startsWith(prefix) ? graphPath.substring(prefix.length) : graphPath;
   }
@@ -12662,6 +13324,62 @@ var Environment = class {
     }
     return response.json();
   }
+  async searchRecords(query, options = {}) {
+    const normalizedQuery = query.replace(/\s+/g, " ").trim();
+    const limit = Math.max(1, Math.min(50, Math.floor(options.limit ?? 12)));
+    const offset = Math.max(0, Math.floor(options.offset ?? 0));
+    const response = await this.graphql(
+      `
+        query RecordMentionSearch(
+          $query: String
+          $limit: Int
+          $offset: Int
+          $classNames: [String!]
+        ) {
+          record_search(
+            query: $query
+            limit: $limit
+            offset: $offset
+            class_names: $classNames
+          ) {
+            className
+            model {
+              path
+              label
+              description
+              submodels {
+                path
+                label
+                string_value
+                number_value
+                boolean_value
+              }
+            }
+          }
+        }
+      `,
+      {
+        query: normalizedQuery,
+        limit,
+        offset,
+        classNames: options.classNames?.length ? options.classNames : []
+      }
+    );
+    const seen = /* @__PURE__ */ new Set();
+    const results = (response.data?.record_search || []).flatMap((entry) => {
+      const className = entry.className?.trim();
+      const item = className && entry.model ? toRecordSearchResult(className, entry.model) : null;
+      if (!item || seen.has(item.path)) {
+        return [];
+      }
+      seen.add(item.path);
+      return [item];
+    });
+    return results.map((result, index) => ({
+      result,
+      rank: rankRecordSearchResult(result, normalizedQuery, index)
+    })).sort((left, right) => left.rank - right.rank).map((item) => item.result).slice(0, limit);
+  }
   // ==================== RELATIONSHIP METHODS ====================
   /**
    * Define a relationship between two model types.
@@ -13427,7 +14145,8 @@ var Environment = class {
         body: JSON.stringify({
           records,
           batchSize: options.batchSize,
-          setupRunId: options.setupRunId
+          setupRunId: options.setupRunId,
+          writeMode: options.writeMode
         })
       }
     );
@@ -13479,11 +14198,13 @@ var Environment = class {
 };
 var EnvironmentSession = class extends Session {
   environment;
+  sessionDataRoutePrefix;
   /** The last known graph container status, updated by checkReadiness() or on heartbeat */
   graphContainerStatus = null;
-  constructor(client, environment, clientId) {
-    super(client, clientId);
+  constructor(client, environment, clientId, options = {}) {
+    super(client, clientId, { initialQuota: options.initialQuota });
     this.environment = environment;
+    this.sessionDataRoutePrefix = options.sessionDataRoutePrefix || "/orchestrator/ws/sessions";
   }
   get environmentId() {
     return this.environment.environmentId;
@@ -13528,7 +14249,7 @@ var EnvironmentSession = class extends Session {
     const doc = this.document;
     return normalizeHeapSnapshot(doc?.heap);
   }
-  async sessionDataRequest(path, query) {
+  async sessionDataRequest(path, query, init2 = {}) {
     const searchParams = new URLSearchParams();
     for (const [key, value] of Object.entries(query || {})) {
       if (value !== null && typeof value !== "undefined" && value !== "") {
@@ -13536,23 +14257,39 @@ var EnvironmentSession = class extends Session {
       }
     }
     const queryString = searchParams.toString();
-    const response = await fetch(
-      `${this.environment.runtimeBaseUrl}/orchestrator/ws/sessions/${encodeURIComponent(this.sessionId)}${path}${queryString ? `?${queryString}` : ""}`,
-      {
-        method: "GET",
-        headers: {
-          Authorization: `Bearer ${this.environment.authToken}`,
-          "Content-Type": "application/json"
+    const url = `${this.environment.runtimeBaseUrl}${this.sessionDataRoutePrefix}/${encodeURIComponent(this.sessionId)}${path}${queryString ? `?${queryString}` : ""}`;
+    const body = typeof init2.body === "undefined" ? void 0 : JSON.stringify(init2.body);
+    for (let attempt = 1; attempt <= SESSION_DATA_REQUEST_RETRY_COUNT; attempt += 1) {
+      try {
+        const response = await fetch(url, {
+          method: init2.method || "GET",
+          headers: {
+            Authorization: `Bearer ${this.environment.authToken}`,
+            "Content-Type": "application/json"
+          },
+          ...typeof body === "undefined" ? {} : { body }
+        });
+        if (response.ok) {
+          return response.json();
+        }
+        const errorText = await response.text();
+        const error = new Error(
+          `Session data API Error (${response.status}): ${errorText}`
+        );
+        if (isLocalControlUrl(url) && isRetryableSessionDataError(error) && attempt < SESSION_DATA_REQUEST_RETRY_COUNT) {
+          await sleep(SESSION_DATA_REQUEST_RETRY_DELAY_MS * attempt);
+          continue;
         }
+        throw error;
+      } catch (error) {
+        if (isLocalControlUrl(url) && isRetryableSessionDataError(error) && attempt < SESSION_DATA_REQUEST_RETRY_COUNT) {
+          await sleep(SESSION_DATA_REQUEST_RETRY_DELAY_MS * attempt);
+          continue;
+        }
+        throw error;
       }
-    );
-    if (!response.ok) {
-      const errorText = await response.text();
-      throw new Error(
-        `Session data API Error (${response.status}): ${errorText}`
-      );
     }
-    return response.json();
+    throw new Error(`Session data API Error: exhausted retries for ${url}`);
   }
   async collectAllSessionItems(listPage) {
     const items = [];
@@ -13610,6 +14347,17 @@ var EnvironmentSession = class extends Session {
         get: (name) => this.sessionDataRequest(
           `/heap/lists/${encodeURIComponent(name)}`
         )
+      },
+      variables: {
+        list: (options = {}) => this.sessionDataRequest("/heap/variables", options),
+        get: (name) => this.sessionDataRequest(
+          `/heap/variables/${encodeURIComponent(name)}`
+        ),
+        delete: (name) => this.sessionDataRequest(
+          `/heap/variables/${encodeURIComponent(name)}`,
+          void 0,
+          { method: "DELETE" }
+        )
       }
     };
   }
@@ -13678,8 +14426,21 @@ var EnvironmentSession = class extends Session {
   async graphql(query, variables) {
     return this.environment.graphql(query, variables);
   }
-  async defineRelationship(options) {
-    return this.environment.defineRelationship(options);
+  async searchRecords(query, options = {}) {
+    return this.environment.searchRecords(query, options);
+  }
+  async mentionRecord(input) {
+    return this.sessionDataRequest(
+      "/records/mention",
+      void 0,
+      {
+        method: "POST",
+        body: input
+      }
+    );
+  }
+  async defineRelationship(options) {
+    return this.environment.defineRelationship(options);
   }
   async getRelationships(modelPath) {
     return this.environment.getRelationships(modelPath);
@@ -13825,6 +14586,7 @@ var Granular = class _Granular {
   WebSocketCtor;
   onUnexpectedClose;
   onReconnectError;
+  effectHostUrl;
   debugHttp = process.env.GRANULAR_DEBUG_HTTP === "1";
   /** Sandbox-level effect registry: sandboxId → (effectKey@selector → ToolWithHandler) */
   sandboxEffects = /* @__PURE__ */ new Map();
@@ -13853,6 +14615,7 @@ var Granular = class _Granular {
     this.WebSocketCtor = options.WebSocketCtor;
     this.onUnexpectedClose = options.onUnexpectedClose;
     this.onReconnectError = options.onReconnectError;
+    this.effectHostUrl = options.effectHostUrl;
     this.httpUrl = this.apiUrl.replace(/^wss:\/\//, "https://").replace(/^ws:\/\//, "http://").replace(/\/ws$/, "");
   }
   /**
@@ -14023,6 +14786,30 @@ var Granular = class _Granular {
       permissions: options.permissions || options.user?.permissions || []
     });
   }
+  /**
+   * Run a registered environment importer against an environment that was
+   * opened outside this SDK instance, for example by a delegated browser flow.
+   *
+   * This uses the same setup-run and queued record-import plumbing as
+   * `openEnvironment()`: importer stages, expected object counts, and queued
+   * import counters remain visible through `environment.setup` and
+   * `getRecordImportSummary()`.
+   */
+  async runEnvironmentImporterForEnvironment(environmentId, options = {}) {
+    const environmentData = await this.environments.get(environmentId);
+    const environment = this.bindEnvironmentHandle(environmentData);
+    const requestedOntology = options.ontology || environmentData.ontologyId || environmentData.sandboxId;
+    return this.runEnvironmentImporter(
+      {
+        environment: environmentData,
+        requestedOntology,
+        sandboxId: environmentData.sandboxId,
+        subjectId: environmentData.subjectId,
+        setupTriggerReason: options.reason || "new_environment"
+      },
+      environment
+    );
+  }
   resolveRequestedTag(options, methodName) {
     const tag = options.tag?.trim() || options.tagName?.trim() || options.environment?.trim();
     if (!tag) {
@@ -14214,6 +15001,15 @@ var Granular = class _Granular {
     const environment = this.bindEnvironmentHandle(envData);
     return this.bindWebSocketEnvironmentSession(environment, clientId, minted);
   }
+  async recordOpenAIUsageSpend(usage, context, options) {
+    return recordOpenAIUsageSpend({
+      apiUrl: this.apiUrl,
+      token: this.apiKey,
+      usage,
+      context,
+      metadata: options?.metadata
+    });
+  }
   /**
    * Mark a session closed in the control plane. If `environment` is the connected handle for that
    * `sessionId`, disconnects the WebSocket so the runtime tears down cleanly.
@@ -14266,15 +15062,25 @@ var Granular = class _Granular {
     return ontologyImporter;
   }
   async maybeRunEnvironmentImporter(resolved, environment) {
-    if (!resolved.setupTriggerReason) {
-      return;
+    const setupTriggerReason = resolved.setupTriggerReason;
+    if (!setupTriggerReason) {
+      return null;
     }
+    return this.runEnvironmentImporter(
+      {
+        ...resolved,
+        setupTriggerReason
+      },
+      environment
+    );
+  }
+  async runEnvironmentImporter(resolved, environment) {
     const importer = this.resolveEnvironmentImporter(
       resolved.requestedOntology,
       resolved.sandboxId
     );
     if (!importer) {
-      return;
+      return null;
     }
     const setupRun = await this.request(
       `/control/environments/${environment.environmentId}/setup-runs`,
@@ -14314,16 +15120,24 @@ var Granular = class _Granular {
       },
       importRecords: async (records, options) => environment.enqueueRecordImport(records, {
         batchSize: options?.batchSize,
+        writeMode: options?.writeMode,
         setupRunId
       })
     };
     try {
       await importer(importerContext);
-      await updateSetupRun({ markHookCompleted: true });
+      const completedSetupRun = await this.request(
+        `/control/environment-setup-runs/${setupRunId}`,
+        {
+          method: "PATCH",
+          body: JSON.stringify({ markHookCompleted: true })
+        }
+      );
       const refreshedEnvironment = await this.environments.get(
         environment.environmentId
       );
       environment.syncEnvironmentData(refreshedEnvironment);
+      return completedSetupRun;
     } catch (error) {
       await updateSetupRun({
         status: "failed",
@@ -14350,7 +15164,8 @@ var Granular = class _Granular {
     const environmentSession = new EnvironmentSession(
       client,
       environment,
-      clientId
+      clientId,
+      { initialQuota: session.quota || null }
     );
     await environmentSession.hello();
     return environmentSession;
@@ -14371,27 +15186,45 @@ var Granular = class _Granular {
     return effects;
   }
   serializeEffect(effect) {
-    return {
+    const serialized = {
       effectKey: computeEffectKey2(effect),
       name: effect.name,
       description: effect.description,
       inputSchema: effect.inputSchema,
-      outputSchema: effect.outputSchema,
       stability: effect.stability || "stable",
-      provenance: effect.provenance || { source: "custom" },
-      tags: effect.tags,
-      className: effect.className,
-      static: effect.static,
-      versionSelector: effect.versionSelector
+      provenance: effect.provenance || { source: "custom" }
     };
+    if (effect.outputSchema !== void 0) {
+      serialized.outputSchema = effect.outputSchema;
+    }
+    if (effect.tags !== void 0) {
+      serialized.tags = effect.tags;
+    }
+    if (effect.className !== void 0) {
+      serialized.className = effect.className;
+    }
+    if (effect.static !== void 0) {
+      serialized.static = effect.static;
+    }
+    if (effect.versionSelector !== void 0) {
+      serialized.versionSelector = effect.versionSelector;
+    }
+    if (effect.metamodels !== void 0) {
+      serialized.metamodels = effect.metamodels;
+    }
+    return serialized;
   }
   async publishSandboxEffectCatalog(host) {
     const effects = Array.from(
       this.getSandboxEffectMap(host.sandboxId).values()
     ).map((effect) => this.serializeEffect(effect));
-    const result = await host.wsClient.call("effects.publishCatalog", {
-      effects
-    });
+    const result = await withTimeout(
+      host.wsClient.call("effects.publishCatalog", {
+        effects
+      }),
+      EFFECT_CATALOG_SYNC_TIMEOUT_MS,
+      `effects.publishCatalog for sandbox ${host.sandboxId}`
+    );
     const acceptedCount = typeof result?.acceptedCount === "number" ? result.acceptedCount : 0;
     const rejected = Array.isArray(result?.rejected) ? result.rejected : [];
     if (acceptedCount === 0 && rejected.length > 0) {
@@ -14410,8 +15243,26 @@ var Granular = class _Granular {
     }
   }
   async syncSandboxEffectCatalog(sandboxId) {
-    const host = await this.ensureSandboxEffectHost(sandboxId);
-    await this.publishSandboxEffectCatalog(host);
+    let lastError;
+    for (let attempt = 1; attempt <= EFFECT_CATALOG_SYNC_RETRY_COUNT; attempt += 1) {
+      try {
+        const host = await this.ensureSandboxEffectHost(sandboxId);
+        await this.publishSandboxEffectCatalog(host);
+        return;
+      } catch (error) {
+        lastError = error;
+        this.disconnectSandboxEffectHost(sandboxId);
+        if (attempt === EFFECT_CATALOG_SYNC_RETRY_COUNT || !isRetryableEffectRegistrationError(error)) {
+          throw error;
+        }
+        console.warn(
+          `[Granular] Retrying effect registration for sandbox ${sandboxId} after transient failure (${attempt}/${EFFECT_CATALOG_SYNC_RETRY_COUNT - 1} retries used):`,
+          error
+        );
+        await sleep(EFFECT_CATALOG_SYNC_RETRY_DELAY_MS * attempt);
+      }
+    }
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
   }
   recoverEffectHost(host, error) {
     if (host.recovering) {
@@ -14504,7 +15355,8 @@ var Granular = class _Granular {
           this.apiUrl,
           sandboxId,
           effectClientId,
-          clientId
+          clientId,
+          this.effectHostUrl
         ),
         sessionId: `effect-host:${effectClientId}`,
         token: this.apiKey,
@@ -14540,7 +15392,11 @@ var Granular = class _Granular {
       wsClient.on("disconnect", () => {
         this.stopEffectHostHeartbeat(host);
       });
-      await wsClient.connect();
+      await withTimeout(
+        wsClient.connect(),
+        EFFECT_HOST_CONNECT_TIMEOUT_MS,
+        `effect host WebSocket connect for sandbox ${sandboxId}`
+      );
       await this.synchronizeEffectHost(host);
       this.sandboxEffectHosts.set(sandboxId, host);
       return host;
@@ -14663,7 +15519,7 @@ var Granular = class _Granular {
   /**
    * Ensure a permission profile exists for a sandbox, creating it if needed.
    * If profileName matches an existing profile name, returns its ID.
-   * Otherwise, creates a new profile with default allow-all rules.
+   * Otherwise, creates a v1 source-profile file shape with an allow default.
    */
   async ensurePermissionProfile(sandboxId, profileName) {
     try {
@@ -14677,8 +15533,11 @@ var Granular = class _Granular {
     const created = await this.permissionProfiles.create(sandboxId, {
       name: profileName,
       rules: {
-        effects: { allow: ["*"] },
-        resources: { allow: ["*"] }
+        schemaVersion: 1,
+        name: profileName,
+        description: profileName === "allow-all" ? "Every declared action is visible unless a manifest policy denies it." : `Generated permission profile ${profileName}`,
+        defaults: { actionPolicy: "allow" },
+        actions: []
       }
     });
     return created.permissionProfileId;
@@ -14751,33 +15610,63 @@ var Granular = class _Granular {
    * Permission Profile management for sandboxes
    */
   get permissionProfiles() {
+    const profileSourceFromRecord = (record) => {
+      const profile = record.profile || record.rules || {};
+      return {
+        ...profile,
+        schemaVersion: profile.schemaVersion || 1,
+        name: profile.name || record.name,
+        description: profile.description || record.description
+      };
+    };
     return {
       list: async (sandboxId) => {
         const result = await this.request(
-          `/control/sandboxes/${sandboxId}/permission-profiles`
+          `/control/sandboxes/${sandboxId}/permission-profile-sources`
         );
         return result.items;
       },
       get: async (sandboxId, profileId) => {
-        return this.request(
-          `/control/sandboxes/${sandboxId}/permission-profiles/${profileId}`
+        const result = await this.request(
+          `/control/sandboxes/${sandboxId}/permission-profile-sources`
+        );
+        const profile = result.items.find(
+          (item) => item.permissionProfileId === profileId || item.name === profileId
         );
+        if (!profile) {
+          throw new Error(`Permission profile source not found: ${profileId}`);
+        }
+        return profile;
       },
       create: async (sandboxId, data) => {
-        return this.request(
-          `/control/sandboxes/${sandboxId}/permission-profiles`,
+        const profile = {
+          ...data.rules,
+          schemaVersion: 1,
+          name: data.name
+        };
+        const existingProfiles = await this.permissionProfiles.list(sandboxId);
+        const profiles = [
+          ...existingProfiles.filter((existing) => existing.name !== data.name).map((existing) => profileSourceFromRecord(existing)),
+          profile
+        ];
+        const result = await this.request(
+          `/control/sandboxes/${sandboxId}/permission-profile-sources`,
           {
-            method: "POST",
-            body: JSON.stringify(data)
+            method: "PUT",
+            body: JSON.stringify({ profiles })
           }
         );
+        const synced = result.items.find((item) => item.name === data.name) || result.items[0];
+        if (!synced) {
+          throw new Error(
+            `Permission profile source sync did not return ${data.name}`
+          );
+        }
+        return synced;
       },
-      delete: async (sandboxId, profileId) => {
-        return this.request(
-          `/control/sandboxes/${sandboxId}/permission-profiles/${profileId}`,
-          {
-            method: "DELETE"
-          }
+      delete: async (_sandboxId, _profileId) => {
+        throw new Error(
+          "Permission profile sources are updated by syncing the desired source set."
         );
       }
     };
@@ -15033,6 +15922,85 @@ var Granular = class _Granular {
 };
 
 // src/agent-harness.ts
+var DEFAULT_IGNORED_REASONING_COMMENT_DIRECTIVES = [
+  /^@ts-ignore\b/i,
+  /^@ts-expect-error\b/i,
+  /^eslint-[\w-]+\b/i,
+  /^biome-ignore\b/i,
+  /^prettier-ignore\b/i,
+  /^istanbul ignore\b/i
+];
+var DEFAULT_LOW_SIGNAL_REASONING_LINES = [
+  /^running\.?$/i,
+  /^working\.?$/i,
+  /^thinking\.?$/i,
+  /^generating(?: code)?\.?$/i,
+  /^starting(?: execution)?\.?$/i
+];
+function parseReasoningCommentLine(line, options = {}) {
+  const trimmed = line.trimStart();
+  if (!trimmed.startsWith("//")) return null;
+  const text = trimmed.replace(/^\/\/\s?/, "").trim();
+  if (!text) return { kind: "ignored" };
+  const ignoredDirectives = options.ignoredCommentDirectives || DEFAULT_IGNORED_REASONING_COMMENT_DIRECTIVES;
+  if (ignoredDirectives.some((pattern) => pattern.test(text))) {
+    return { kind: "ignored" };
+  }
+  const lowSignalLines = options.lowSignalReasoningLines || DEFAULT_LOW_SIGNAL_REASONING_LINES;
+  if (lowSignalLines.some((pattern) => pattern.test(text))) {
+    return { kind: "ignored" };
+  }
+  return { kind: "reasoning", text };
+}
+function consumeGranularReasoningTraceChunk(buffer, chunk, options = {}) {
+  let text = buffer + chunk;
+  let visibleText = "";
+  const reasoningLines = [];
+  while (true) {
+    const newlineIndex = text.indexOf("\n");
+    if (newlineIndex === -1) break;
+    const rawLine = text.slice(0, newlineIndex);
+    text = text.slice(newlineIndex + 1);
+    const comment = parseReasoningCommentLine(
+      rawLine.replace(/\r$/, ""),
+      options
+    );
+    if (comment?.kind === "reasoning") {
+      reasoningLines.push(comment.text);
+    } else if (comment?.kind === "ignored") {
+      continue;
+    } else {
+      visibleText += `${rawLine}
+`;
+    }
+  }
+  if (options.final && text.length > 0) {
+    const comment = parseReasoningCommentLine(text.replace(/\r$/, ""), options);
+    if (comment?.kind === "reasoning") {
+      reasoningLines.push(comment.text);
+      text = "";
+    } else if (comment?.kind === "ignored") {
+      text = "";
+    } else {
+      visibleText += text;
+      text = "";
+    }
+  }
+  return { buffer: text, visibleText, reasoningLines };
+}
+function consumeGranularReasoningOnlyChunk(buffer, chunk, options = {}) {
+  const result = consumeGranularReasoningTraceChunk(buffer, chunk, options);
+  return {
+    buffer: result.buffer,
+    reasoningLines: result.reasoningLines
+  };
+}
+function stripGranularReasoningTrace(text, options = {}) {
+  return consumeGranularReasoningTraceChunk("", text, {
+    ...options,
+    final: true
+  }).visibleText.trim();
+}
 function asRecord4(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   return value;
@@ -15056,21 +16024,8 @@ function uniqueStrings(values, maxCount) {
   }
   return output;
 }
-function formatScalar(value) {
-  if (typeof value === "string") return JSON.stringify(value);
-  if (typeof value === "number" || typeof value === "boolean")
-    return String(value);
-  if (value === null) return "null";
-  return "unknown";
-}
-function describeHeapEntry(entry, previewFieldLimit = 3) {
-  const headline = entry.label || entry.id || entry.path || "Unknown";
-  const pathLabel = entry.path && entry.path !== headline ? ` <${entry.path}>` : "";
-  const classLabel = entry.className || "unknown";
-  const preview = asArray2(entry.fields).filter(
-    (field) => field?.name && field.name !== "_realId" && field.name !== "real_id"
-  ).slice(0, previewFieldLimit).map((field) => `${field.name}=${formatScalar(field.value)}`).join(", ");
-  return preview ? `${headline}${pathLabel} [${classLabel}] ${preview}` : `${headline}${pathLabel} [${classLabel}]`;
+function renderConstBlock(name, value) {
+  return `const ${name} = ${JSON.stringify(value, null, 2)} as const;`;
 }
 function hashString(value) {
   if (!value) return null;
@@ -15081,97 +16036,248 @@ function hashString(value) {
   }
   return (hash >>> 0).toString(16).padStart(8, "0");
 }
-function hasSubstantiveAwaitAfterPrompt(code, marker) {
-  const startIndex = code.indexOf(marker);
-  if (startIndex === -1) return true;
-  const segment = code.slice(startIndex + marker.length);
-  const callMatches = segment.matchAll(
-    /await\s+([A-Za-z0-9_$.]+)\.([A-Za-z0-9_]+)\s*\(/g
+function findUndefinedSimpleTemplateIdentifier(source) {
+  const declared = /* @__PURE__ */ new Set();
+  const globals = /* @__PURE__ */ new Set([
+    "Array",
+    "Boolean",
+    "Date",
+    "JSON",
+    "Math",
+    "Number",
+    "Object",
+    "Promise",
+    "String",
+    "undefined",
+    "null",
+    "true",
+    "false"
+  ]);
+  for (const match of source.matchAll(/import\s*\{([^}]+)\}\s*from/g)) {
+    for (const part of match[1].split(",")) {
+      const aliasMatch = part.trim().match(/\bas\s+([A-Za-z_$][\w$]*)$/);
+      const nameMatch = part.trim().match(/^([A-Za-z_$][\w$]*)/);
+      const name = aliasMatch?.[1] || nameMatch?.[1];
+      if (name) declared.add(name);
+    }
+  }
+  for (const match of source.matchAll(
+    /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\b/g
+  )) {
+    declared.add(match[1]);
+  }
+  for (const match of source.matchAll(
+    /\bfor\s*(?:await\s*)?\(\s*(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s+of\b/g
+  )) {
+    declared.add(match[1]);
+  }
+  for (const match of source.matchAll(
+    /\bcatch\s*\(\s*([A-Za-z_$][\w$]*)\s*\)/g
+  )) {
+    declared.add(match[1]);
+  }
+  for (const match of source.matchAll(
+    /\(\s*([A-Za-z_$][\w$]*)\s*(?:,\s*[A-Za-z_$][\w$]*)*\s*\)\s*=>/g
+  )) {
+    declared.add(match[1]);
+  }
+  for (const match of source.matchAll(/\b([A-Za-z_$][\w$]*)\s*=>/g)) {
+    declared.add(match[1]);
+  }
+  for (const match of source.matchAll(/\$\{\s*([A-Za-z_$][\w$]*)\s*\}/g)) {
+    const identifier = match[1];
+    if (!declared.has(identifier) && !globals.has(identifier)) {
+      return identifier;
+    }
+  }
+  return null;
+}
+function getGeneratedJobSyntaxError(source) {
+  const withoutImports = source.replace(
+    /^\s*import\s+[\s\S]*?\s+from\s+["'][^"']+["']\s*;?\s*$/gm,
+    ""
   );
-  for (const match of callMatches) {
-    const receiver = match[1] || "";
-    const method = match[2] || "";
-    if (receiver === "loop" || receiver === "heap") continue;
-    if (method.startsWith("get_") || method.startsWith("get")) continue;
-    return true;
+  try {
+    new Function(`return (async () => {
+${withoutImports}
+});`);
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+function hasNestedTemplateLiteralExpression(source) {
+  let inString = null;
+  let escaped = false;
+  const templateStack = [];
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    const next = source[index + 1] || "";
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (inString === "'" || inString === '"') {
+      if (char === inString) inString = null;
+      continue;
+    }
+    if (inString === "`") {
+      const current = templateStack[templateStack.length - 1];
+      if (char === "`") {
+        if (current?.expressionDepth && current.expressionDepth > 0) {
+          return true;
+        }
+        templateStack.pop();
+        if (templateStack.length === 0) inString = null;
+        continue;
+      }
+      if (char === "$" && next === "{") {
+        if (current) current.expressionDepth += 1;
+        index += 1;
+        continue;
+      }
+      if (char === "}" && current?.expressionDepth) {
+        current.expressionDepth -= 1;
+      }
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      inString = char;
+      continue;
+    }
+    if (char === "`") {
+      inString = "`";
+      templateStack.push({ expressionDepth: 0 });
+    }
   }
   return false;
 }
-function reviewGeneratedJobCode(code) {
+function reviewGeneratedJobCode(code, _options = {}) {
   const normalized = typeof code === "string" ? code : "";
-  if (!normalized.trim()) return [];
   const issues = [];
+  if (!normalized.trim()) {
+    return issues;
+  }
   if (/require\s*\(\s*['"]\.\/sandbox-tools['"]\s*\)/.test(normalized)) {
     issues.push({
       code: "commonjs_require",
       severity: "error",
-      message: "Use ESM imports like `import { Customer, loop } from './sandbox-tools';` instead of require('./sandbox-tools'). Generated jobs must be plain runnable JavaScript for the sandbox runtime."
-    });
-  }
-  const placeholderPatterns = [
-    /ready to make the change next/i,
-    /ready to .* next/i,
-    /ready to .* now/i,
-    /i can make the change now/i,
-    /i can do that next/i,
-    /i'?m ready to continue/i,
-    /have your approval .* ready to make/i,
-    /approved\./i
-  ];
-  if (normalized.includes("await loop.confirm(")) {
-    const postConfirm = normalized.slice(
-      normalized.indexOf("await loop.confirm(")
-    );
-    const hasPlaceholder = placeholderPatterns.some(
-      (pattern) => pattern.test(postConfirm)
-    );
-    const hasSubstantiveAwait = hasSubstantiveAwaitAfterPrompt(
-      normalized,
-      "await loop.confirm("
-    );
-    if (!hasSubstantiveAwait || hasPlaceholder) {
-      issues.push({
-        code: "placeholder_after_confirm",
-        severity: "error",
-        message: "After await loop.confirm(...) returns true, the job must perform the approved mutation in the same resumed run. Do not stop with placeholder text like 'Approved, I can make the change now.'"
-      });
-    }
+      message: "Use ESM imports from './sandbox-tools' instead of require('./sandbox-tools')."
+    });
   }
-  if (normalized.includes("await loop.ask_user(")) {
-    const postPrompt = normalized.slice(
-      normalized.indexOf("await loop.ask_user(")
-    );
-    const hasPlaceholder = placeholderPatterns.some(
-      (pattern) => pattern.test(postPrompt)
-    );
-    const hasSubstantiveAwait = hasSubstantiveAwaitAfterPrompt(
-      normalized,
-      "await loop.ask_user("
-    );
-    if (hasPlaceholder && !hasSubstantiveAwait) {
-      issues.push({
-        code: "placeholder_after_ask_user",
-        severity: "error",
-        message: "After await loop.ask_user(...) returns a usable answer, continue the workflow in the same resumed run instead of stopping with placeholder text about doing the work later."
-      });
-    }
+  if (/\bprocess\.exit\s*\(/.test(normalized)) {
+    issues.push({
+      code: "process_exit",
+      severity: "error",
+      message: "Generated jobs must not call process.exit(...). Return from the job or emit a runtime message instead."
+    });
+  }
+  if (/\bawait\s+import\s*\(\s*['"]\.\/sandbox-tools['"]\s*\)/.test(normalized)) {
+    issues.push({
+      code: "dynamic_import_in_job",
+      severity: "error",
+      message: "Import sandbox tools with a static top-level import from './sandbox-tools'; do not use dynamic import for runtime tools."
+    });
+  }
+  if (hasNestedTemplateLiteralExpression(normalized)) {
+    issues.push({
+      code: "nested_template_literal_in_job",
+      severity: "error",
+      message: "Avoid nested template literals inside template expressions. Precompute conditional text in variables or use simpler string construction."
+    });
   }
-  const hasConversationalReturn = /return\s+[`'"]/.test(normalized) || /\breply\s*:/.test(normalized) || /\bagent_message\s*\(/.test(normalized) || /\bagent_text_message\s*\(/.test(normalized);
-  const returnsObjectLiteral = /return\s+\{[\s\S]*?\}/.test(normalized);
-  const returnsShowPayload = /return\s+\{[\s\S]*?\bshow\s*:/.test(normalized);
-  const closesLoop = /loop\.close_loop\s*\(/.test(normalized);
-  if (!hasConversationalReturn && returnsObjectLiteral && !closesLoop) {
+  const syntaxError = getGeneratedJobSyntaxError(normalized);
+  if (syntaxError) {
     issues.push({
-      code: "missing_user_reply",
+      code: "syntax_error_in_job",
       severity: "error",
-      message: "User-facing jobs must end with a natural-language answer. Return a short string, an object with a top-level `reply` string, or post text with agent_text_message(...). Do not end with bare structured JSON."
+      message: `The generated job has a JavaScript syntax error before runtime execution: ${syntaxError}.`
     });
   }
-  if (returnsShowPayload) {
+  if (/[\u2018-\u201F]/.test(normalized)) {
     issues.push({
-      code: "return_show_not_for_ui",
+      code: "syntax_error_in_job",
       severity: "error",
-      message: "Do not use the final return value to send UI record refs through `show`. Use agent_heap_objects(...) for heap-backed UI, then return plain text if you still want a final textual answer."
+      message: "Use plain ASCII quotes and apostrophes in generated job strings."
+    });
+  }
+  const undefinedTemplateIdentifier = findUndefinedSimpleTemplateIdentifier(normalized);
+  if (undefinedTemplateIdentifier) {
+    issues.push({
+      code: "undefined_template_identifier",
+      severity: "error",
+      message: `The template literal references \`${undefinedTemplateIdentifier}\`, but that identifier is not declared in the generated job.`
+    });
+  }
+  if (/\{\s*\.\.\.[A-Za-z_$][\w$]*/.test(normalized)) {
+    issues.push({
+      code: "object_spread_in_job",
+      severity: "error",
+      message: "Avoid object spread in generated jobs until the backend runtime transform can validate it structurally."
+    });
+  }
+  if (/\bloop\./.test(normalized) && !/import\s*\{[^}]*\bloop\b[^}]*\}\s*from\s*['"]\.\/sandbox-tools['"]/.test(
+    normalized
+  )) {
+    issues.push({
+      code: "missing_loop_import",
+      severity: "error",
+      message: "The job calls loop.* but does not import loop from './sandbox-tools'."
+    });
+  }
+  const bareLoopHelperImport = normalized.match(
+    /import\s*\{[^}]*\b(ask_user|confirm|open_decision|close_decision|create_task|update_task|complete_task|close_loop)\b[^}]*\}\s*from\s*['"]\.\/sandbox-tools['"]/
+  );
+  if (bareLoopHelperImport) {
+    issues.push({
+      code: "bare_loop_helper_import",
+      severity: "error",
+      message: "Workflow helpers are exposed on the imported `loop` object. Import `loop` from './sandbox-tools' and call helpers as `loop.create_task(...)`, `loop.open_decision(...)`, `loop.confirm(...)`, etc.; do not import them as bare functions."
+    });
+  }
+  if (/\bloop\.open_decision\s*\(\s*\{[\s\S]*?\boptions\s*:/.test(normalized)) {
+    issues.push({
+      code: "loop_helper_contract",
+      severity: "error",
+      message: "loop.open_decision(...) must use `candidates: [...]`, not `options: [...]`. Every candidate must include a string `id`."
+    });
+  }
+  if (/\bloop\.close_decision\s*\(\s*\{[\s\S]*?\bselected\s*:/.test(normalized)) {
+    issues.push({
+      code: "loop_helper_contract",
+      severity: "error",
+      message: "loop.close_decision(...) must use `selectedId`, not `selected`."
+    });
+  }
+  if (/\bloop\.(?:create_task|update_task|complete_task)\s*\(\s*\{[\s\S]*?\bid\s*:/.test(
+    normalized
+  )) {
+    issues.push({
+      code: "loop_helper_contract",
+      severity: "error",
+      message: "Loop task helpers must use `taskId`, not `id`, for explicit task identifiers."
+    });
+  }
+  if (/\bconsole\.log\s*\(\s*JSON\.stringify\s*\(\s*\{[\s\S]*?\b(?:action|reply|code)\s*:/.test(
+    normalized
+  )) {
+    issues.push({
+      code: "stdout_json_reply",
+      severity: "error",
+      message: "Do not print JSON chat envelopes from generated jobs; use runtime messaging or return a plain result."
+    });
+  }
+  if (/\breturn\s+\{[\s\S]*?\baction\s*:\s*['"]reply['"][\s\S]*?\breply\s*:/.test(
+    normalized
+  )) {
+    issues.push({
+      code: "return_chat_payload",
+      severity: "error",
+      message: "Do not return chat envelopes like { action, reply, code } from generated jobs; return a plain value or use runtime messaging."
     });
   }
   return issues;
@@ -15230,15 +16336,40 @@ function collectConversationReferents(liveDoc) {
     const ts = Number(message.ts) || 0;
     const messageId = typeof message.id === "string" ? message.id : void 0;
     const jobId = typeof message.jobId === "string" ? message.jobId : void 0;
-    for (const entryPath of uniqueStrings(asArray2(show.entryPaths))) {
+    const entryPaths = uniqueStrings(asArray2(show.entryPaths));
+    const entryClassCounts = /* @__PURE__ */ new Map();
+    const entryMetadata = entryPaths.map((entryPath) => {
       const entry = asRecord4(entriesByPath[entryPath]);
+      const className = typeof entry?.className === "string" ? entry.className : void 0;
+      if (className) {
+        entryClassCounts.set(
+          className,
+          (entryClassCounts.get(className) || 0) + 1
+        );
+      }
+      return { entryPath, entry, className };
+    });
+    const displayGroupId = entryMetadata.length > 1 ? `message:${messageId || jobId || ts}:entries` : void 0;
+    for (const [
+      index,
+      { entryPath, entry, className }
+    ] of entryMetadata.entries()) {
       pushReferent({
         id: `entry:${entryPath}`,
         kind: "entry",
         ref: entryPath,
+        role: "assistant",
+        source: "heap_objects",
         entryPath,
-        className: typeof entry?.className === "string" ? entry.className : void 0,
+        recordId: typeof entry?.id === "string" ? entry.id : void 0,
+        className,
         label: typeof entry?.label === "string" && entry.label.trim() ? entry.label.trim() : typeof entry?.id === "string" && entry.id.trim() ? entry.id.trim() : entryPath,
+        ...displayGroupId ? {
+          displayGroupId,
+          displayGroupIndex: index,
+          displayGroupSize: entryMetadata.length,
+          ...className && (entryClassCounts.get(className) || 0) > 1 ? { displayGroupSameTypeSize: entryClassCounts.get(className) } : {}
+        } : {},
         messageId,
         jobId,
         ts
@@ -15250,6 +16381,8 @@ function collectConversationReferents(liveDoc) {
         id: `list:${listName}`,
         kind: "list",
         ref: listName,
+        role: "assistant",
+        source: "heap_objects",
         listName,
         className: typeof list?.className === "string" ? list.className : void 0,
         count: Array.isArray(list?.paths) ? list.paths.length : null,
@@ -15270,9 +16403,12 @@ function collectConversationReferents(liveDoc) {
         id: `variable:${variableName}`,
         kind: "variable",
         ref: variableName,
+        role: "assistant",
+        source: "heap_objects",
         variableName,
         variableKind: typeof variable?.kind === "string" ? variable.kind : void 0,
         entryPath,
+        recordId: typeof entry?.id === "string" ? entry.id : void 0,
         listName,
         className: typeof variable?.className === "string" ? variable.className : typeof entry?.className === "string" ? entry.className : typeof list?.className === "string" ? list.className : void 0,
         label: typeof entry?.label === "string" && entry.label.trim() ? entry.label.trim() : typeof entry?.id === "string" && entry.id.trim() ? entry.id.trim() : null,
@@ -15293,18 +16429,24 @@ function projectConversationReferentFocus(liveDoc) {
   const entryPaths = [];
   const listNames = [];
   const variableNames = [];
-  for (const referent of referents.slice(0, 8)) {
-    if (referent.kind === "entry" && typeof referent.entryPath === "string") {
+  let entryCount = 0;
+  let listCount = 0;
+  let variableCount = 0;
+  for (const referent of referents) {
+    if (referent.kind === "entry" && typeof referent.entryPath === "string" && entryCount < 8) {
+      entryCount += 1;
       entryPaths.push(referent.entryPath);
       continue;
     }
-    if (referent.kind === "list" && typeof referent.listName === "string") {
+    if (referent.kind === "list" && typeof referent.listName === "string" && listCount < 4) {
+      listCount += 1;
       listNames.push(referent.listName);
       const list = asRecord4(listsByName[referent.listName]);
       entryPaths.push(...asArray2(list?.paths).slice(0, 4));
       continue;
     }
-    if (referent.kind === "variable" && typeof referent.variableName === "string") {
+    if (referent.kind === "variable" && typeof referent.variableName === "string" && variableCount < 4) {
+      variableCount += 1;
       variableNames.push(referent.variableName);
       if (typeof referent.entryPath === "string") {
         entryPaths.push(referent.entryPath);
@@ -15322,61 +16464,91 @@ function projectConversationReferentFocus(liveDoc) {
     variableNames: uniqueStrings(variableNames, 4)
   };
 }
-function projectConversationReferentSummary(liveDoc) {
-  const referents = collectConversationReferents(liveDoc).slice(0, 8);
-  if (referents.length === 0) {
-    return "No recent referents recorded from prior assistant replies.";
-  }
-  const entryLines = [];
-  const listLines = [];
-  const variableLines = [];
+function selectConversationReferentsForPrompt(referents) {
+  const selected = [];
+  const seen = /* @__PURE__ */ new Set();
+  let entryCount = 0;
+  let listCount = 0;
+  let variableCount = 0;
   for (const referent of referents) {
+    if (!referent.kind || !referent.ref) continue;
+    const key = `${referent.kind}:${referent.ref}`;
+    if (seen.has(key)) continue;
+    if (referent.kind === "entry") {
+      if (entryCount >= 8) continue;
+      entryCount += 1;
+    } else if (referent.kind === "list") {
+      if (listCount >= 4) continue;
+      listCount += 1;
+    } else if (referent.kind === "variable") {
+      if (variableCount >= 4) continue;
+      variableCount += 1;
+    }
+    seen.add(key);
+    selected.push(referent);
+  }
+  return selected;
+}
+function projectConversationReferentSummary(liveDoc) {
+  const referents = selectConversationReferentsForPrompt(
+    collectConversationReferents(liveDoc)
+  );
+  const compact = referents.map((referent) => {
     if (referent.kind === "entry" && referent.entryPath) {
-      const label = referent.label || referent.entryPath;
-      const classLabel = referent.className || "unknown";
-      entryLines.push(`- ${label} <${referent.entryPath}> [${classLabel}]`);
-      continue;
+      return {
+        kind: "entry",
+        role: referent.role || null,
+        source: referent.source || null,
+        path: referent.entryPath,
+        id: referent.recordId || null,
+        type: referent.className || "unknown",
+        label: referent.label || referent.entryPath,
+        group: referent.displayGroupId ? {
+          id: referent.displayGroupId,
+          index: typeof referent.displayGroupIndex === "number" ? referent.displayGroupIndex : null,
+          size: typeof referent.displayGroupSize === "number" ? referent.displayGroupSize : null,
+          sameTypeSize: typeof referent.displayGroupSameTypeSize === "number" ? referent.displayGroupSameTypeSize : null
+        } : void 0
+      };
+    }
+    if (referent.kind === "entry" && referent.recordId) {
+      return {
+        kind: "entry",
+        role: referent.role || null,
+        source: referent.source || null,
+        id: referent.recordId,
+        type: referent.className || "unknown",
+        label: referent.label || referent.recordId
+      };
     }
     if (referent.kind === "list" && referent.listName) {
-      const classLabel = referent.className || "unknown";
-      const countLabel = typeof referent.count === "number" ? referent.count : "?";
-      listLines.push(
-        `- ${referent.listName}: list<${classLabel}> -> ${countLabel} item(s)`
-      );
-      continue;
+      return {
+        kind: "list",
+        role: referent.role || null,
+        source: referent.source || null,
+        name: referent.listName,
+        type: referent.className || "unknown",
+        count: typeof referent.count === "number" ? referent.count : null
+      };
     }
     if (referent.kind === "variable" && referent.variableName) {
-      if (referent.variableKind === "entry" && referent.entryPath && referent.className) {
-        const label = referent.label || referent.entryPath;
-        variableLines.push(
-          `- ${referent.variableName}: entry<${referent.className}> -> ${label} <${referent.entryPath}>`
-        );
-        continue;
-      }
-      if (referent.variableKind === "list" && referent.listName && referent.className) {
-        const countLabel = typeof referent.count === "number" ? referent.count : "?";
-        variableLines.push(
-          `- ${referent.variableName}: list<${referent.className}> -> ${countLabel} item(s) via ${referent.listName}`
-        );
-        continue;
-      }
-      if (referent.variableKind === "scalar") {
-        variableLines.push(
-          `- ${referent.variableName}: scalar = ${formatScalar(referent.scalarValue)}`
-        );
-        continue;
-      }
-      variableLines.push(`- ${referent.variableName}`);
+      return {
+        kind: "variable",
+        role: referent.role || null,
+        source: referent.source || null,
+        name: referent.variableName,
+        valueKind: referent.variableKind || null,
+        type: referent.className || null,
+        path: referent.entryPath || null,
+        list: referent.listName || null,
+        label: referent.label || null,
+        count: typeof referent.count === "number" ? referent.count : null,
+        value: referent.variableKind === "scalar" ? referent.scalarValue ?? null : void 0
+      };
     }
-  }
-  const lines = [];
-  lines.push("Entries:");
-  lines.push(...entryLines.length > 0 ? entryLines : ["- none"]);
-  lines.push("", "Lists:");
-  lines.push(...listLines.length > 0 ? listLines : ["- none"]);
-  lines.push("", "Variables:");
-  lines.push(...variableLines.length > 0 ? variableLines : ["- none"]);
-  return lines.join("\n");
+    return null;
+  }).filter(Boolean);
+  return renderConstBlock("recentReferences", compact);
 }
 function getCurrentClosureId(liveDoc) {
   const loop = asRecord4(liveDoc?.loop);
@@ -15597,56 +16769,24 @@ function projectWorkflowFocus(liveDoc, pendingPrompts = [], options) {
 }
 function projectWorkflowSummary(liveDoc, pendingPrompts = [], options) {
   const focus = projectWorkflowFocus(liveDoc, pendingPrompts, options);
-  const lines = [];
-  lines.push("Workflow Boundary:");
-  if (focus.boundaryReason === "request_start") {
-    lines.push(
-      "- Start from work recorded after the current user request began."
-    );
-  } else if (focus.boundaryReason === "last_closed_loop" && focus.latestClosureId) {
-    lines.push(`- Start from work recorded after ${focus.latestClosureId}.`);
-  } else {
-    lines.push(
-      "- No prior closed loop recorded; use the latest user request as the boundary."
-    );
-  }
-  lines.push("", "Recent Actions:");
-  if (focus.recentActionSummary.length === 0) {
-    lines.push("- none");
-  } else {
-    for (const line of focus.recentActionSummary) {
-      lines.push(line.startsWith("- ") ? line : `- ${line}`);
-    }
-  }
-  lines.push("", "Working Set Hints:");
-  if (focus.variableNames.length === 0 && focus.listNames.length === 0 && focus.entryPaths.length === 0) {
-    lines.push("- none");
-  } else {
-    if (focus.variableNames.length > 0) {
-      lines.push(`- variables: ${focus.variableNames.join(", ")}`);
-    }
-    if (focus.listNames.length > 0) {
-      lines.push(`- lists: ${focus.listNames.join(", ")}`);
-    }
-    if (focus.entryPaths.length > 0) {
-      lines.push(`- entries: ${focus.entryPaths.join(", ")}`);
-    }
-  }
-  lines.push("", "Open Workflow Handles:");
-  if (focus.activeTaskIds.length === 0 && focus.openDecisionIds.length === 0 && focus.openPromptIds.length === 0) {
-    lines.push("- none");
-  } else {
-    if (focus.activeTaskIds.length > 0) {
-      lines.push(`- tasks: ${focus.activeTaskIds.join(", ")}`);
-    }
-    if (focus.openDecisionIds.length > 0) {
-      lines.push(`- decisions: ${focus.openDecisionIds.join(", ")}`);
-    }
-    if (focus.openPromptIds.length > 0) {
-      lines.push(`- prompts: ${focus.openPromptIds.join(", ")}`);
+  return renderConstBlock("workflowContext", {
+    boundary: {
+      timestamp: focus.boundaryTimestamp,
+      reason: focus.boundaryReason,
+      latestClosureId: focus.latestClosureId || null
+    },
+    recentActions: focus.recentActionSummary,
+    workingSet: {
+      variables: focus.variableNames,
+      lists: focus.listNames,
+      entries: focus.entryPaths
+    },
+    openHandles: {
+      tasks: focus.activeTaskIds,
+      decisions: focus.openDecisionIds,
+      prompts: focus.openPromptIds
     }
-  }
-  return lines.join("\n");
+  });
 }
 function hasOpenPrompt(liveDoc, pendingPrompts) {
   if (pendingPrompts.length > 0) return true;
@@ -15667,7 +16807,6 @@ function getExclusivePromptTarget(pendingPrompts) {
   return prompt?.type === "input" ? prompt : null;
 }
 function projectLoopSummary(liveDoc, pendingPrompts = [], options) {
-  const lines = [];
   const loop = asRecord4(liveDoc?.loop);
   const boundary = getWorkflowBoundary(liveDoc, options);
   const tasks = toSortedRecords(loop?.tasksById).filter((task) => {
@@ -15689,22 +16828,12 @@ function projectLoopSummary(liveDoc, pendingPrompts = [], options) {
     5
   );
   const hiddenTaskCount = Math.max(0, activeTasks.length - visibleTasks.length);
-  lines.push("Tasks:");
-  if (visibleTasks.length === 0) {
-    lines.push("- none");
-  } else {
-    lines.push("- Reuse existing taskId values exactly as written below.");
-    for (const task of visibleTasks) {
-      const title = typeof task.title === "string" ? task.title : "Untitled task";
-      const taskId = typeof task.taskId === "string" ? task.taskId : "unknown";
-      const status = typeof task.status === "string" ? task.status : "pending";
-      const summary = typeof task.summary === "string" && task.summary.trim() ? ` \u2014 ${task.summary.trim()}` : "";
-      lines.push(`- [${status}] ${title} (${taskId})${summary}`);
-    }
-    if (hiddenTaskCount > 0) {
-      lines.push(`- ${hiddenTaskCount} more active task(s) omitted`);
-    }
-  }
+  const compactTasks = visibleTasks.map((task) => ({
+    id: typeof task.taskId === "string" ? task.taskId : "unknown",
+    title: typeof task.title === "string" ? task.title : "Untitled task",
+    status: typeof task.status === "string" ? task.status : "pending",
+    summary: typeof task.summary === "string" && task.summary.trim() ? task.summary.trim() : null
+  }));
   const decisions = toSortedRecords(loop?.decisionsById).filter((decision) => {
     const updatedAt = Number(decision.updatedAt) || Number(decision.createdAt) || 0;
     if (boundary.reason === "request_start") {
@@ -15718,33 +16847,29 @@ function projectLoopSummary(liveDoc, pendingPrompts = [], options) {
     (decision) => decision.status === "open"
   );
   const visibleDecisions = (openDecisions.length > 0 ? openDecisions : decisions.slice(0, 1)).slice(0, 3);
-  lines.push("", "Recent Decisions:");
-  if (visibleDecisions.length === 0) {
-    lines.push("- none");
-  } else {
-    lines.push("- Reuse existing decisionId values exactly as written below.");
-    for (const decision of visibleDecisions) {
-      const status = typeof decision.status === "string" ? decision.status : "resolved";
-      const title = typeof decision.title === "string" && decision.title.trim() ? decision.title.trim() : "Decision";
-      const decisionId = typeof decision.decisionId === "string" ? decision.decisionId : "unknown";
-      if (status === "open") {
-        const candidatePreview = asArray2(decision.candidates).slice(0, 3).map((candidate) => {
-          const record = asRecord4(candidate);
-          if (!record) return null;
-          const candidateId = typeof record.id === "string" ? record.id : "unknown";
-          const candidateLabel = typeof record.label === "string" && record.label.trim() ? record.label.trim() : candidateId;
-          return candidateLabel === candidateId ? candidateId : `${candidateLabel} (${candidateId})`;
-        }).filter((value) => Boolean(value)).join(", ");
-        lines.push(
-          `- [open] ${title} (${decisionId})${candidatePreview ? ` \u2014 candidates: ${candidatePreview}` : ""}`
-        );
-      } else {
-        const selected = asRecord4(decision.selected);
-        const label = typeof selected?.label === "string" ? selected.label : typeof selected?.id === "string" ? selected.id : "unknown";
-        lines.push(`- [resolved] ${title} (${decisionId}) -> ${label}`);
+  const compactDecisions = visibleDecisions.map((decision) => {
+    const status = typeof decision.status === "string" ? decision.status : "resolved";
+    const selected = asRecord4(decision.selected);
+    return {
+      id: typeof decision.decisionId === "string" ? decision.decisionId : "unknown",
+      title: typeof decision.title === "string" && decision.title.trim() ? decision.title.trim() : "Decision",
+      status,
+      candidates: status === "open" ? asArray2(decision.candidates).slice(0, 5).map((candidate) => {
+        const record = asRecord4(candidate);
+        if (!record) return null;
+        return {
+          id: typeof record.id === "string" ? record.id : "unknown",
+          label: typeof record.label === "string" && record.label.trim() ? record.label.trim() : null,
+          description: typeof record.description === "string" && record.description.trim() ? record.description.trim() : null,
+          metadata: asRecord4(record.metadata)
+        };
+      }).filter(Boolean) : [],
+      selected: status === "open" ? null : {
+        id: typeof selected?.id === "string" ? selected.id : null,
+        label: typeof selected?.label === "string" ? selected.label : null
       }
-    }
-  }
+    };
+  });
   const openPrompts = [
     ...pendingPrompts.map((prompt) => ({
       id: prompt.id,
@@ -15764,29 +16889,29 @@ function projectLoopSummary(liveDoc, pendingPrompts = [], options) {
       (pendingPrompt) => pendingPrompt.id === promptId
     ) : false);
   }) : openPrompts;
-  lines.push("", "Open Prompts:");
-  if (visiblePrompts.length === 0) {
-    lines.push("- none");
-  } else {
-    for (const prompt of visiblePrompts.slice(0, 3)) {
-      const title = typeof prompt.title === "string" && prompt.title.trim() ? prompt.title.trim() : "Input required";
-      const type = typeof prompt.type === "string" ? prompt.type : "input";
-      const message = typeof prompt.message === "string" && prompt.message.trim() ? ` \u2014 ${prompt.message.trim()}` : "";
-      lines.push(`- [${type}] ${title}${message}`);
-    }
-  }
+  const compactPrompts = visiblePrompts.slice(0, 3).map((prompt) => {
+    const promptRecord = asRecord4(prompt) || {};
+    return {
+      id: typeof promptRecord.id === "string" ? promptRecord.id : typeof promptRecord.promptId === "string" ? promptRecord.promptId : null,
+      type: typeof promptRecord.type === "string" ? promptRecord.type : "input",
+      title: typeof promptRecord.title === "string" && promptRecord.title.trim() ? promptRecord.title.trim() : "Input required",
+      message: typeof promptRecord.message === "string" && promptRecord.message.trim() ? promptRecord.message.trim() : null
+    };
+  });
   const currentClosureId = getCurrentClosureId(liveDoc);
   const closureRecord = currentClosureId ? asRecord4(asRecord4(loop?.closuresById)?.[currentClosureId]) : null;
   const visibleClosure = closureRecord && (boundary.reason !== "request_start" || (Number(closureRecord.createdAt) || 0) >= boundary.timestamp) ? closureRecord : null;
-  lines.push("", "Loop Closure:");
-  if (visibleClosure) {
-    const status = typeof visibleClosure.status === "string" ? visibleClosure.status : "completed";
-    const summary = typeof visibleClosure.summary === "string" ? visibleClosure.summary : "No summary";
-    lines.push(`- current: [${status}] ${summary} (${currentClosureId})`);
-  } else {
-    lines.push("- none");
-  }
-  return lines.join("\n");
+  return renderConstBlock("workflowState", {
+    tasks: compactTasks,
+    hiddenActiveTaskCount: hiddenTaskCount,
+    decisions: compactDecisions,
+    openPrompts: compactPrompts,
+    closure: visibleClosure ? {
+      id: currentClosureId,
+      status: typeof visibleClosure.status === "string" ? visibleClosure.status : "completed",
+      summary: typeof visibleClosure.summary === "string" ? visibleClosure.summary : null
+    } : null
+  });
 }
 function projectHeapSummary(heap, options) {
   const heapRecord = asRecord4(heap) || {};
@@ -15831,55 +16956,72 @@ function projectHeapSummary(heap, options) {
     referencedPaths.add(path);
   }
   const visibleLists = Object.values(listsByName).map((value) => asRecord4(value)).filter((value) => Boolean(value)).filter(
-    (list) => variables.some((variable) => variable.listName === list.name) || Boolean(list.name && focusedListNames.has(list.name))
+    (list) => variables.some(
+      (variable) => Boolean(variable?.listName === list.name)
+    ) || Boolean(list.name && focusedListNames.has(list.name))
   ).sort((left, right) => (right.updatedAt || 0) - (left.updatedAt || 0)).slice(0, maxLists);
   const visibleEntries = Object.values(entriesByPath).map((value) => asRecord4(value)).filter((value) => Boolean(value)).filter((entry) => entry.path && referencedPaths.has(entry.path)).sort((left, right) => (right.updatedAt || 0) - (left.updatedAt || 0)).slice(0, maxEntries);
-  const lines = [];
-  lines.push("Variables:");
-  if (variables.length === 0) {
-    lines.push("- none");
-  } else {
-    for (const variable of variables) {
-      if (variable.kind === "scalar") {
-        lines.push(
-          `- ${variable.name}: scalar = ${formatScalar(variable.value)}`
-        );
-        continue;
-      }
-      if (variable.kind === "entry") {
-        const entry = variable.entryPath ? asRecord4(
-          entriesByPath[variable.entryPath]
-        ) : null;
-        lines.push(
-          `- ${variable.name}: entry<${variable.className || entry?.className || "unknown"}> -> ${entry ? describeHeapEntry(entry) : variable.entryPath || "missing"}`
-        );
-        continue;
-      }
-      const list = variable.listName ? asRecord4(listsByName[variable.listName]) : null;
-      lines.push(
-        `- ${variable.name}: list<${variable.className || list?.className || "unknown"}> -> ${(list?.paths || []).length} item(s)`
-      );
-    }
-  }
-  lines.push("", "Named Lists:");
-  if (visibleLists.length === 0) {
-    lines.push("- none");
-  } else {
-    for (const list of visibleLists) {
-      lines.push(
-        `- ${list.name}: ${list.className || "unknown"}[${(list.paths || []).length}]`
-      );
-    }
-  }
-  lines.push("", "Active Entries:");
-  if (visibleEntries.length === 0) {
-    lines.push("- none");
-  } else {
-    for (const entry of visibleEntries) {
-      lines.push(`- ${describeHeapEntry(entry)}`);
-    }
-  }
-  return lines.join("\n");
+  return renderConstBlock("savedData", {
+    variables: Object.fromEntries(
+      variables.filter((variable) => typeof variable.name === "string").map((variable) => {
+        if (variable.kind === "scalar") {
+          return [
+            variable.name,
+            { kind: "scalar", value: variable.value ?? null }
+          ];
+        }
+        if (variable.kind === "entry") {
+          const entry = variable.entryPath ? asRecord4(
+            entriesByPath[variable.entryPath]
+          ) : null;
+          return [
+            variable.name,
+            {
+              kind: "entry",
+              type: variable.className || entry?.className || "unknown",
+              path: variable.entryPath || null,
+              label: entry?.label || entry?.id || null
+            }
+          ];
+        }
+        const list = variable.listName ? asRecord4(listsByName[variable.listName]) : null;
+        return [
+          variable.name,
+          {
+            kind: "list",
+            type: variable.className || list?.className || "unknown",
+            list: variable.listName || null,
+            count: (list?.paths || []).length
+          }
+        ];
+      })
+    ),
+    lists: Object.fromEntries(
+      visibleLists.filter((list) => typeof list.name === "string").map((list) => [
+        list.name,
+        {
+          type: list.className || "unknown",
+          count: (list.paths || []).length
+        }
+      ])
+    ),
+    entries: Object.fromEntries(
+      visibleEntries.filter((entry) => typeof entry.path === "string").map((entry) => [
+        entry.path,
+        {
+          type: entry.className || "unknown",
+          id: entry.id || null,
+          label: entry.label || entry.id || null,
+          fields: asArray2(entry.fields).filter(
+            (field) => field?.name && field.name !== "_realId" && field.name !== "real_id"
+          ).slice(0, 3).map((field) => ({
+            name: field.name,
+            value: field.value ?? null
+          }))
+        }
+      ])
+    )
+  });
 }
 function createHarnessVerifierSnapshot(input) {
   const workflowFocus = projectWorkflowFocus(
@@ -15976,8 +17118,8 @@ function buildContinuationInstruction(resultPreview) {
     "If the user names a concrete record that is not already in the heap, resolve it from the graph before saying it is missing: try a broad search, then a small set of normalized/fuzzy variants or a paged scan when the domain supports it.",
     "If the request needs all matching records, use iterate(...) or page until hasMore is false. A single list(...) or page(...) call is only one page.",
     "If this request clearly spans multiple steps and there are no active tasks yet, create 2-4 short user-visible tasks now.",
-    "Reuse any existing taskId and decisionId values exactly as they appear in AGENT LOOP STATE.",
-    "When progress depends on the user's choice, missing detail, or approval, use loop.ask_user(...) or loop.confirm(...) so the job pauses and resumes through the live workflow.",
+    "Reuse any existing taskId and decisionId values exactly as they appear in [State].",
+    "When progress depends on the user's choice, missing detail, or confirmation, use loop.ask_user(...) or loop.confirm(...) so the job pauses and resumes through the live workflow.",
     "After a resumed ask_user or confirm call, continue the same job and perform the newly authorized action when the answer is sufficient. Do not stop with placeholder text like 'I'm ready to do it next.'",
     "If you ask the user a new question in this job, do not also close the loop in the same job.",
     "Write the smallest straightforward code for the current step. Avoid defensive fallback branches for hypothetical states that are not currently true.",
@@ -15988,39 +17130,101 @@ ${resultPreview}` : null
   ].filter(Boolean).join("\n\n");
 }
 function buildGranularAgentDomainBlock(domainDocumentation) {
-  return domainDocumentation?.trim() || "No domain reference available. The graph may not be ready yet.";
+  return domainDocumentation?.trim() || "No domain contract available. The graph may not be ready yet.";
 }
 function buildGranularAgentSessionBlock(sessionContext) {
-  if (!sessionContext) return "No session metadata available.";
-  const rows = [
-    ["sandboxId", sessionContext.sandboxId],
-    ["environmentId", sessionContext.environmentId],
-    ["userName", sessionContext.userName]
-  ];
-  const activeRows = rows.filter(([, value]) => Boolean(value));
-  if (activeRows.length === 0) return "No session metadata available.";
-  return activeRows.map(([key, value]) => `${key}: ${value}`).join("\n");
+  return renderConstBlock("session", {
+    runtimeId: sessionContext?.sandboxId || null,
+    environmentId: sessionContext?.environmentId || null,
+    userName: sessionContext?.userName || null,
+    domainRevision: sessionContext?.domainRevision || null
+  });
 }
 function buildGranularAgentHeapBlock(heapSummary) {
-  return heapSummary?.trim() || "Heap is empty for this session.";
+  return heapSummary?.trim() || renderConstBlock("savedData", {
+    variables: {},
+    lists: {},
+    entries: {}
+  });
 }
 function buildGranularAgentReferentBlock(referentSummary) {
-  return referentSummary?.trim() || "No recent referents recorded from prior assistant replies.";
+  return referentSummary?.trim() || renderConstBlock("recentReferences", []);
 }
 function buildGranularAgentLoopBlock(loopSummary) {
-  return loopSummary?.trim() || "No active loop state recorded for this session.";
+  return loopSummary?.trim() || renderConstBlock("workflowState", {
+    tasks: [],
+    decisions: [],
+    openPrompts: [],
+    closure: null
+  });
 }
 function buildGranularAgentWorkflowBlock(workflowSummary) {
-  return workflowSummary?.trim() || "No current workflow snapshot recorded for this request yet.";
+  return workflowSummary?.trim() || renderConstBlock("workflowContext", {
+    boundary: null,
+    recentActions: [],
+    workingSet: {
+      variables: [],
+      lists: [],
+      entries: []
+    },
+    openHandles: {
+      tasks: [],
+      decisions: [],
+      prompts: []
+    }
+  });
 }
-function buildGranularAgentToolBlock(tools) {
+function resolvePromptCapabilities(capabilities) {
+  return {
+    executeCode: capabilities?.executeCode !== false,
+    readEntities: capabilities?.readEntities !== false,
+    workflowHelpers: Array.isArray(capabilities?.workflowHelpers) ? capabilities.workflowHelpers : [
+      "ask_user",
+      "confirm",
+      "open_decision",
+      "close_decision",
+      "create_task",
+      "update_task",
+      "complete_task",
+      "close_loop"
+    ],
+    savedData: capabilities?.savedData !== false,
+    showRecords: capabilities?.showRecords !== false
+  };
+}
+function buildGranularAgentToolBlock(tools, capabilityOverrides) {
+  const resolvedCapabilities = resolvePromptCapabilities(capabilityOverrides);
+  const normalizedTools = (tools || []).filter((tool) => tool?.name).slice().sort((left, right) => {
+    const leftScope = `${left.className || "global"}:${left.static ? "static" : "instance"}`;
+    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 scope = tool.className ? `${tool.static ? "class" : "record"}:${tool.className}` : "global";
+    return {
+      name: tool.name,
+      scope,
+      description: tool.description?.trim() || null
+    };
+  });
+  const capabilities = {
+    executeCode: resolvedCapabilities.executeCode,
+    readEntities: resolvedCapabilities.readEntities,
+    writeActions,
+    workflowHelpers: resolvedCapabilities.workflowHelpers,
+    savedData: resolvedCapabilities.savedData,
+    showRecords: resolvedCapabilities.showRecords
+  };
+  return renderConstBlock("capabilities", capabilities);
+}
+function buildGranularAgentActionIndex(tools) {
   const normalizedTools = (tools || []).filter((tool) => tool?.name).slice().sort((left, right) => {
     const leftScope = `${left.className || "global"}:${left.static ? "static" : "instance"}`;
     const rightScope = `${right.className || "global"}:${right.static ? "static" : "instance"}`;
     return leftScope.localeCompare(rightScope) || left.name.localeCompare(right.name);
   });
   if (normalizedTools.length === 0) {
-    return "No live effects are available in this session yet.";
+    return "No domain write actions are available.";
   }
   const globalTools = normalizedTools.filter((tool) => !tool.className);
   const staticTools = normalizedTools.filter(
@@ -16029,9 +17233,7 @@ function buildGranularAgentToolBlock(tools) {
   const instanceTools = normalizedTools.filter(
     (tool) => Boolean(tool.className && !tool.static)
   );
-  const lines = [
-    "Treat this block as the planning map. Use DOMAIN REFERENCE below for exact signatures and query examples."
-  ];
+  const lines = ["Available actions by scope:"];
   const appendGroup = (title, group) => {
     lines.push(`- ${title}:`);
     if (group.length === 0) {
@@ -16040,189 +17242,563 @@ function buildGranularAgentToolBlock(tools) {
     }
     for (const tool of group.slice(0, 10)) {
       const availability = tool.ready === false ? " [not ready]" : "";
+      const schema = formatActionSchemaSummary(tool);
       const description = tool.description?.trim() ? ` - ${tool.description.trim()}` : "";
-      lines.push(`  ${tool.name}${availability}${description}`);
+      lines.push(`  ${tool.name}${availability}${schema}${description}`);
     }
     if (group.length > 10) {
       lines.push(`  +${group.length - 10} more`);
     }
   };
-  appendGroup("Global effects", globalTools);
-  appendGroup("Class-level effects", staticTools);
-  appendGroup("Record-level effects", instanceTools);
+  appendGroup("Global", globalTools);
+  appendGroup("Class-level", staticTools);
+  appendGroup("Record-level", instanceTools);
   return lines.join("\n");
 }
-function buildGranularAgentCheckpointBlock(checkpoint) {
-  if (!checkpoint) {
-    return "No previous execution checkpoint recorded for this request yet.";
-  }
-  const lines = [];
-  if (typeof checkpoint.iteration === "number") {
-    lines.push(`iteration: ${checkpoint.iteration}`);
-  }
-  if (checkpoint.latestJobStatus) {
-    lines.push(`latestJobStatus: ${checkpoint.latestJobStatus}`);
-  }
-  if (checkpoint.controllerOutcome) {
-    lines.push(`controllerOutcome: ${checkpoint.controllerOutcome}`);
+function normalizeJsonSchema(value) {
+  if (typeof value === "string") {
+    try {
+      return asRecord4(JSON.parse(value));
+    } catch {
+      return null;
+    }
   }
-  if (checkpoint.controllerReason) {
-    lines.push(`controllerReason: ${checkpoint.controllerReason}`);
+  return asRecord4(value);
+}
+function jsonSchemaTypeName(schema) {
+  const record = normalizeJsonSchema(schema);
+  if (!record) return "unknown";
+  const type = record.type;
+  if (typeof type === "string") {
+    if (type === "array") return "array";
+    if (type === "object") return "object";
+    return type;
   }
-  if (typeof checkpoint.noProgressCount === "number") {
-    lines.push(`noProgressCount: ${checkpoint.noProgressCount}`);
+  return "unknown";
+}
+function summarizeObjectSchema(schema) {
+  const record = normalizeJsonSchema(schema);
+  const properties = asRecord4(record?.properties);
+  if (!properties || Object.keys(properties).length === 0) {
+    return record ? "{}" : null;
+  }
+  const required = new Set(asArray2(record?.required));
+  const fields = Object.entries(properties).slice(0, 8).map(([name, property]) => {
+    const marker = required.has(name) ? "*" : "?";
+    return `${name}${marker}: ${jsonSchemaTypeName(property)}`;
+  });
+  const remaining = Object.keys(properties).length - fields.length;
+  return remaining > 0 ? `${fields.join(", ")}, +${remaining}` : fields.join(", ");
+}
+function formatActionSchemaSummary(tool) {
+  const input = summarizeObjectSchema(tool.inputSchema);
+  const output = summarizeObjectSchema(tool.outputSchema);
+  const parts = [];
+  if (input) parts.push(`input { ${input} }`);
+  if (output) parts.push(`output { ${output} }`);
+  return parts.length ? ` (${parts.join("; ")})` : "";
+}
+function splitDomainDocumentation(domainDocumentation) {
+  const normalized = domainDocumentation?.trim() || "";
+  if (!normalized) return { types: "", docs: "" };
+  const docsSectionMatch = normalized.match(/\n\s*\[Docs\]\s*\n/i);
+  if (docsSectionMatch?.index !== void 0) {
+    return {
+      types: normalized.slice(0, docsSectionMatch.index).trim(),
+      docs: normalized.slice(docsSectionMatch.index + docsSectionMatch[0].length).trim()
+    };
   }
-  if (checkpoint.latestJobError?.trim()) {
-    lines.push(`latestJobError: ${checkpoint.latestJobError.trim()}`);
+  const legacyMarker = "Generated usage notes from ./sandbox-tools docs:";
+  const legacyIndex = normalized.indexOf(legacyMarker);
+  if (legacyIndex !== -1) {
+    return {
+      types: normalized.slice(0, legacyIndex).trim(),
+      docs: normalized.slice(legacyIndex + legacyMarker.length).trim()
+    };
   }
-  if (Array.isArray(checkpoint.latestActionSummary) && checkpoint.latestActionSummary.length > 0) {
-    lines.push("latestActionSummary:");
-    for (const line of checkpoint.latestActionSummary.slice(0, 8)) {
-      const normalizedLine = normalizeActionSummaryForPrompt(line);
-      lines.push(
-        normalizedLine.startsWith("- ") ? normalizedLine : `- ${normalizedLine}`
-      );
+  return { types: normalized, docs: "" };
+}
+function buildGranularAgentCheckpointBlock(checkpoint) {
+  if (!checkpoint) {
+    return renderConstBlock("previousCodeResult", null);
+  }
+  return renderConstBlock("previousCodeResult", {
+    iteration: typeof checkpoint.iteration === "number" ? checkpoint.iteration : null,
+    latestJobStatus: checkpoint.latestJobStatus || null,
+    controllerOutcome: checkpoint.controllerOutcome || null,
+    controllerReason: checkpoint.controllerReason || null,
+    noProgressCount: typeof checkpoint.noProgressCount === "number" ? checkpoint.noProgressCount : null,
+    latestJobError: checkpoint.latestJobError?.trim() || null,
+    latestActionSummary: Array.isArray(checkpoint.latestActionSummary) ? checkpoint.latestActionSummary.slice(0, 8).map(normalizeActionSummaryForPrompt) : [],
+    latestJobResult: checkpoint.latestJobResult?.trim() || null
+  });
+}
+function parseSummaryOutcome(summary) {
+  const outcome = {};
+  for (const part of summary.split(",")) {
+    const trimmed = part.trim();
+    const match = /^([A-Za-z0-9_]+)=(.+)$/.exec(trimmed);
+    if (!match) continue;
+    const [, key, rawValue] = match;
+    const unquoted = rawValue.replace(/^"|"$/g, "");
+    if (/^-?\d+(?:\.\d+)?$/.test(unquoted)) {
+      outcome[key] = Number(unquoted);
+    } else if (unquoted === "true" || unquoted === "false") {
+      outcome[key] = unquoted === "true";
+    } else {
+      outcome[key] = unquoted;
     }
   }
-  if (checkpoint.latestJobResult?.trim()) {
-    lines.push(`latestJobResult:
-${checkpoint.latestJobResult.trim()}`);
+  return outcome;
+}
+function buildKnownFactsFromCheckpoint(checkpoint) {
+  const summaries = Array.isArray(checkpoint?.latestActionSummary) ? checkpoint.latestActionSummary.map(normalizeActionSummaryForPrompt) : [];
+  const facts = [];
+  for (const summary of summaries) {
+    const countedMatch = /^-\s*Counted\s+([A-Za-z0-9_]+).*?->\s*value=(\d+)/.exec(summary);
+    if (countedMatch) {
+      facts.push({
+        entity: countedMatch[1],
+        query: {},
+        totalCount: Number(countedMatch[2])
+      });
+      continue;
+    }
+    const listedMatch = /^-\s*Listed\s+([A-Za-z0-9_]+).*?->\s*(.+)$/.exec(
+      summary
+    );
+    if (!listedMatch) continue;
+    const outcome = parseSummaryOutcome(listedMatch[2]);
+    const count = typeof outcome.totalCount === "number" ? outcome.totalCount : typeof outcome.count === "number" ? outcome.count : void 0;
+    if (typeof count !== "number") continue;
+    const fact = {
+      entity: listedMatch[1],
+      query: {},
+      totalCount: count
+    };
+    if (typeof outcome.hasMore === "boolean") {
+      fact.lastPageHasMore = outcome.hasMore;
+      fact.loadedAllItems = !outcome.hasMore;
+    } else if (typeof outcome.count === "number" && outcome.count === count) {
+      fact.loadedAllItems = true;
+    }
+    facts.push(fact);
   }
-  return lines.length > 0 ? lines.join("\n") : "No previous execution checkpoint recorded for this request yet.";
+  return facts.slice(0, 8);
 }
 function buildGranularAgentSystemPrompt(input) {
+  const outputMode = input.outputMode || "agentMessages";
+  const promptCapabilities = resolvePromptCapabilities(input.capabilities);
+  const domainSections = splitDomainDocumentation(input.domainDocumentation);
   const sessionBlock = buildGranularAgentSessionBlock(input.sessionContext);
-  const toolBlock = buildGranularAgentToolBlock(input.tools);
-  const domainBlock = buildGranularAgentDomainBlock(input.domainDocumentation);
+  const toolBlock = buildGranularAgentToolBlock(
+    input.tools,
+    input.capabilities
+  );
+  const actionIndex = buildGranularAgentActionIndex(input.tools);
+  const domainBlock = buildGranularAgentDomainBlock(domainSections.types);
   const workflowBlock = buildGranularAgentWorkflowBlock(input.workflowSummary);
   const checkpointBlock = buildGranularAgentCheckpointBlock(input.checkpoint);
   const heapBlock = buildGranularAgentHeapBlock(input.heapSummary);
   const referentBlock = buildGranularAgentReferentBlock(input.referentSummary);
   const loopBlock = buildGranularAgentLoopBlock(input.loopSummary);
-  return `You are an AI assistant for a live Granular session.
-You can help the user understand the domain, answer questions, or generate and execute code against the live session.
-Your tone must be natural and human-like.
+  const knownFactsBlock = renderConstBlock(
+    "knownFacts",
+    buildKnownFactsFromCheckpoint(input.checkpoint)
+  );
+  const outputRules = outputMode === "returnValue" ? promptCapabilities.showRecords ? `- End every user-facing job by returning either a short natural-language string or an object like \`{ reply, show }\`.
+- Use \`{ reply, show }\` when the host UI should render records, heap variables, or lists from session state.
+- For multi-record display, prefer a saved list/listName so the UI can render a table; use entryPaths for a few individual records.
+- When the user asks to show, list, display, open, or "show them" for records you found, include those heap-backed records in \`show\`; do not answer only with a count or text summary.
+- For count-only questions such as "how many", "how many X do I have", or "what is the total number of X", call the entity \`.count(...)\` or use page \`totalCount\` only when a page is already needed for other reasons. Answer with text only. Do not fetch, save, or display sample records just to ground a numeric count.
+- Do not call \`agent_text_message(...)\` or \`agent_heap_objects(...)\` unless the host explicitly opts into those side-channel message helpers.` : `- End every user-facing job by returning a short natural-language string.` : promptCapabilities.showRecords ? `- Every job that answers the user must emit \`agent_text_message(...)\` and/or \`agent_heap_objects(...)\`.
+- \`agent_text_message(...)\` displays text directly to the user in the host UI. Treat it as the user-facing progress and reply channel, not as a debug log.
+  - For long-running or multi-step jobs, send several short \`agent_text_message(...)\` updates as useful milestones are reached so the user can see what is happening instead of waiting in silence.
+  - Write \`agent_text_message(...)\` content in a friendly, readable product-assistant style: concrete, concise, and natural. Avoid robotic status dumps, raw implementation names, and unexplained IDs unless the ID helps the user.
+  - 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.
+  - 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.
+  - For count-only questions such as "how many", "how many X do I have", or "what is the total number of X", call the entity \`.count(...)\` or use page \`totalCount\` only when a page is already needed for other reasons. Answer with \`agent_text_message(...)\` only. Do not call \`agent_heap_objects(...)\`, \`saveAs\`, or \`heap.setVar(...)\` unless the user also asked to see records or a later requested action needs a reusable record selection.
+  - Any job that identifies a specific record in the visible answer must also display that grounded record with \`agent_heap_objects(...)\` when the user should see/open it, or save it with \`heap.setVar(...)\` when it is only needed for follow-up resolution.
+  - For ordered record slices, pages, queues, search results, or ranked lists, save the slice with \`heap.setVar(...)\` and then call \`agent_heap_objects({ variableNames: [...] })\` once. Use a stable name that preserves the slice identity and ordering so later references such as "the second item" or "back on the first slice" resolve to the correct earlier slice, not merely the most recent record.
+  - Do not rely on the final return value for UI output. Do not return ad-hoc \`reply\` / \`show\` payloads instead of explicit agent message calls.` : `- Every job that answers the user must emit \`agent_text_message(...)\`.
+- \`agent_text_message(...)\` displays text directly to the user in the host UI. Treat it as the user-facing progress and reply channel, not as a debug log.
+- For long-running or multi-step jobs, send several short \`agent_text_message(...)\` updates as useful milestones are reached so the user can see what is happening instead of waiting in silence.
+- Write \`agent_text_message(...)\` content in a friendly, readable product-assistant style: concrete, concise, and natural. Avoid robotic status dumps, raw implementation names, and unexplained IDs unless the ID helps the user.
+- 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.`;
+  const codeRules = promptCapabilities.executeCode ? `Code:
+- Use when the request needs session data, saved data, workflow state, record display, or available actions.
+- When using code, assistant text must be empty or one brief summary.
+- Code must be plain runnable JavaScript with top-level await.
+- Import needed classes and helpers from "./sandbox-tools".
+- Use static top-level imports such as \`import { Foo, agent_text_message } from "./sandbox-tools";\`. Do not use dynamic \`await import("./sandbox-tools")\`.
+- Keep generated jobs as straightforward top-level scripts. Small local helper functions are allowed when they make the code clearer, but avoid hiding domain actions, prompts, or relationship traversal inside broad generic helpers.
+- Do not nest template literals: never put a backtick string inside another template string or inside a \`\${...}\` expression. Build conditional text in variables first, or use simple string concatenation. For multi-line replies, prefer a \`lines\` array and \`.join("\\n")\`.
+- Do not write an action branch that finds multiple candidates, emits a "please choose" message, and returns. When the current request asks for an action, the same branch must call \`await loop.ask_user(...)\`, resolve the answer, and continue to the requested action before the job finishes.
+- User-visible output must use the provided message or record-display helpers.
+- After calling an action or effect, inspect the returned object and base the user-facing answer on its actual fields.
+- When calling an action, use the exact input property names from the action schema. Do not invent synonym keys for required inputs.
+- After a mutation succeeds, ground the answer in the affected record by emitting or saving the record for UI display and naming a stable user-visible identifier when one exists. Do not answer only "done" or "sent".
+- Never call \`process.exit(...)\`; emit a message and use \`return;\` to stop early.
+- Add short \`//\` planning comments before meaningful blocks. The user will see these comments concatenated as a planning trace while the job is being drafted, so they should read together like a properly written plan.
+- In \`//\` planning comments, clearly explain the logic of what the job is about to do: the sequence of steps, why each step matters, and any important decision points or branches.
+- Write \`//\` planning comments for the user, not for engineers: make them friendly, plain-language, and easy to understand.
+- Keep \`//\` planning comments in future tense, but vary the phrasing so they do not become a repetitive list of sentences that all start the same way.
+- Make the \`//\` planning trace feel connected: use natural transitions for sequence, dependency, contrast, and branching when useful. If the next step depends on what the job finds, say that in plain language.
+- Avoid technical terms, implementation names, code concepts, hidden helper names, and complex domain jargon in \`//\` planning comments unless the user already used that wording.
+- Each \`//\` planning comment should provide valuable feedback about the plan or next visible step. Do not add filler such as "Starting", "Running", or "Processing".
+${outputRules}` : `Code:
+- Code execution is unavailable. Use text only, or ask the user for missing information.`;
+  const workflowRules = promptCapabilities.workflowHelpers.length > 0 ? `Workflow:
+- Use workflow helpers when missing input should pause and resume the workflow.
+- If code discovers missing required input after a read, use \`await loop.ask_user(...)\`; do not just tell the user to provide it.
+- Do not ask the user for data the job can discover from grounded records, relationships, saved session state, or visible read-only actions. Ask only when the missing value is truly unavailable, ambiguous, or requires a human decision.
+- When ambiguity blocks a requested action, import \`loop\` and use \`await loop.ask_user({ type: "choice", ... })\` with grounded options so the same job can resume and complete the action. A plain text request such as "please choose one" is not a workflow and leaves the action unhandled.
+- If a requested action has 2 to 5 plausible grounded targets, the job is not complete after showing them. Do not stop after \`agent_text_message(...)\` or \`agent_heap_objects(...)\`; import \`loop\`, ask for a grounded choice with \`await loop.ask_user(...)\`, then call the action on the selected record after the job resumes.
+- If a lookup before a mutation returns multiple plausible target records, do not mutate the first sorted or first returned record. Ask for a grounded choice unless the user supplied a unique identifier, ordinal, or selector that leaves exactly one target.
+- 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.
+- 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.
+- 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.` : "";
+  return `[Harness]
+You are an assistant for a live user session. Use plain, natural language.
 
-Call the \`execute_code\` effect ONLY when the user's intent matches the domain's capabilities and requires executing code against the live session. If the user is just asking a general question or if their request doesn't match the available effects or domain types, respond with text to explain.
-When you call \`execute_code\`, additional assistant text must be either:
-- empty, or
-- a brief summary of the actions the generated code will perform.
-Do not include any other kind of commentary when calling \`execute_code\`.
-- If the next step needs to create or update workflow state in the live session, you must call \`execute_code\`. This includes \`loop.ask_user(...)\`, \`loop.confirm(...)\`, \`loop.open_decision(...)\`, \`loop.close_decision(...)\`, \`loop.create_task(...)\`, \`loop.update_task(...)\`, \`loop.complete_task(...)\`, and \`loop.close_loop(...)\`.
-- If the next step is an interactive clarification that should be resumable in the live workflow, you must call \`execute_code\`. A missing preference, rule, metric, target, or option selection is not a plain-text reply when the answer should drive the next live step.
-- If you can offer a short grounded shortlist, that clarification should usually be \`loop.ask_user({ type: 'choice', ... })\` instead of a plain-text question with bullet options.
-- Never simulate a live prompt, confirmation, decision, task change, or loop closure in plain text. Plain-text replies are only for conversational answers that do not need to mutate session state.
+Mode selection:
+Text only:
+- Use for general explanations, unsupported requests, or requests that do not need session data.
+- Do not use text only when the user asks you to check, look up, search, inspect, update, schedule, or otherwise use session data or tools.
+- Do not answer with a promise like "I'll check" or "I'll do that next"; if the request needs tools, choose a job and run them now.
+- Do not expose internal names, helper names, file paths, parameter names, or code.
+- In code jobs, never use \`console.log(JSON.stringify({ action, reply, code }))\` as a user reply. Use the provided message helpers or final return contract.
 
-\u2500\u2500\u2500 STREAMING COMMENT RULES \u2500\u2500\u2500
-- While you are writing code, add short single-line comments with the prefix \`// \` before meaningful blocks.
-- These comments should explain the intent in friendly product language, not in implementation jargon.
-- Comments are shown live as a reasoning trace, so keep them brief, concrete, and useful.
-- Do not mention method names, file paths, or internal identifiers in those comments.
-- Use only single-line \`//\` comments for this purpose. Do not use block comments.
-- If you are replying with text only, you may also include a few leading \`// \` comment lines before the final answer.
-- End text-only replies with the plain user-facing answer on normal lines, without a comment prefix.
+${codeRules}
 
-\u2500\u2500\u2500 RESPONSE STYLE RULES \u2500\u2500\u2500
-- Use plain, friendly product language.
-- Never mention internal implementation details in user-facing text:
-  class names, effect names, method names, function names, file paths, parameter names, or code snippets.
-- Never expose dotted identifiers such as \`Class.method\` in user-facing text.
-- Do not say "sandbox" in user-facing text unless the user is explicitly asking about the runtime environment itself.
-- If you need clarification, ask in everyday language.
-- If the missing information should pause the live workflow for later continuation, ask through \`loop.ask_user(...)\` in generated code rather than with a plain-text question.
-- If you are asking the user to pick from explicit options, prefer a live \`loop.ask_user({ type: 'choice', ... })\` prompt over a direct reply that lists those options in text.
-- Keep replies concise and clear.
-- This is a conversation UI, not an API console. Favor human answers over machine-shaped payloads.
+${workflowRules}
 
-\u2500\u2500\u2500 SESSION CONTEXT \u2500\u2500\u2500
-${sessionBlock}
+High-priority execution rules:
+- Treat a human reference as something to ground, not as missing data. When the user names or describes a record, group, queue, parent, relationship, or prior result and asks to inspect, decide, update, schedule, approve, send, or otherwise act on session data, run a code job to ground it before asking the user for more details.
+- For a human-described primary anchor, a no-match answer is only justified after more than one distinct grounding attempt, such as owner/container grounding, relationship traversal, exact id/path lookup, or shorter target-local search. Before the primary no-match return, retry that same anchor with fewer text constraints or a distinct grounding strategy; do not stop after one zero-result list/find/page call.
+- A confirmation requirement is not a reason to stay text-only. Do all safe read-only grounding and availability/status checks first, then call \`loop.confirm(...)\` or \`loop.ask_user(...)\` before the mutation.
+- In any code branch where a requested action or mutation has multiple possible targets, import \`loop\` statically and use \`await loop.ask_user(...)\` in that branch. This includes ambiguity discovered after a query returns several records. A branch that only shows candidates, asks in text, and returns leaves the requested action unfinished.
+- Before any mutation, know whether the target is one record or several. A singular phrase like "the item" is not proof of uniqueness after a query finds multiple matching records. If the user did not give an exact identifier or explicit selection criterion, call \`loop.ask_user({ type: "choice", ... })\` with grounded choices; do not choose by age, amount, priority, order, or convenience on your own. Resolve the target before any yes/no confirmation.
+- Treat partial names, first words, aliases, and shorthand labels as partial references. Use search/contains or grounded relationship traversal first; do not report no match after only an exact \`equal_to\` name filter.
+- When a partial name, alias, or shorthand resolves to a stored record, include that record's stored display value in the visible answer at least once. Prefer exact fields such as name, title, number, label, or other user-facing identifier over the user's shorthand.
+- If the user says the label/name may be wrong, or gives a nickname/quoted phrase, do not stop after one direct target search. Ground the stable anchor in the request first, such as the named owner, container, parent, account, project, location, or other higher-level record; then traverse its declared relationships, inspect related candidate records, and only then report no match or ask for help.
+- If the user says "still", "current", "latest", "where", "check", "if", or asks you to decide whether a condition is true, first identify the record that can prove the condition. When that condition names a related object, the code order must be: load the action target or anchor, traverse to the related evidence record, call its visible status/lookup action when available, then decide whether to mutate. Do not branch, return, or reject the condition from parent/action-target status before that evidence step.
+- When a condition names an anchored noun phrase whose final noun is an entity type, the final entity type is the evidence record to test. Use the earlier words only to ground or traverse to that record; do not test the anchor record as a substitute.
+- Do not treat prior read-only summaries, cached parent fields, action-target fields, or stored related-record fields as fresh evidence for a later conditional mutation when a related evidence object and visible lookup/status action can be reached.
+- When the user asks whether a suitable or available candidate exists for assignment, scheduling, routing, or ownership, call the visible availability/matching/search action on the candidate entity when one exists. Existing relationships or current assignments are context, not proof of current availability.
+- When a request names an owner, parent, account, project, location, or other container plus a target item, plan it as two steps: ground the owner/container, then discover the target through declared relationships, relationship filters, or short target-local search. Do not combine owner/container words with target words in one target-class search, and do not require owner/container words to appear in target-local fields such as title or summary.
+- When the target or evidence record is reached through relationships, use the declared relationship index/getter list as a graph and walk getters whose target types lead toward the needed entity. If a target has a one-record parent field and the user named the grandparent/owner, start from the grandparent/owner and traverse down through getters; do not put the grandparent condition inside the target's parent filter. If a relationship is documented as one-record or many-to-one, never use \`some\` on it.
+- After refusing a bypass, external-send, export, or restricted-data request, a follow-up that refers to the same item/case/record inherits that boundary even if no record was saved. Do not perform a different mutation, search for replacement candidates, or ask which restricted referent to use; refuse unless a visible allowed workflow explicitly authorizes the new request.
+- If the previous answer mentioned, displayed, or contrasted multiple plausible records and the next mutation uses only "it", "that", "that one", "the item", or similar, ask which grounded record to use. Even if one record seems more actionable, the pronoun alone is ambiguous, and a confirmation prompt is not a substitute for a grounded choice prompt.
+- A saved list, heap object collection, table, or record-display artifact with multiple possible mutation targets counts as multiple plausible records even when the visible text only gave counts. Do not pick the first, last, or most recent item from that collection for a pronoun like "that one"; ask for a grounded choice first.
+- For "first N", "next N", "top N", queue, slice, newest/oldest, or ranked-list requests, use the runtime paging surface on the target record type when it exists. Relationship getters can help discover context, but a local \`.slice(0, N)\` over a relationship array is not a paged queue result.
+- When selecting a single "top", "best", "urgent", or "most relevant" record from a broad set, do not rely on lexicographic sorting of label fields or the first page while more results exist. Narrow with grounded filters or gather enough candidates first, then rank from explicit record fields.
+- Do not remove candidates returned by an availability/search action solely because they are already assigned, current, or previously related, unless the user asked for a different candidate. If the action returned them as available or matching, they remain valid candidates.
+- In filters, use \`some\` only on relationship fields that are declared as many/collection fields. Singular relationship fields must use \`path\`, \`id\`, or \`is\`; if unsure, follow declared getters from an already grounded record instead.
 
-\u2500\u2500\u2500 CAPABILITY SNAPSHOT \u2500\u2500\u2500
-${toolBlock}
+Intent resolution:
+- If intent is explicit, act directly.
+- For pronouns and discourse references like this, it, that, those, them, their, the previous one, or the selected ones, inspect recentReferences first. Do not use recentReferences array order as a selector when several same-type records could satisfy the phrase.
+- For follow-up phrases like same item, that record, the one you showed, or the previous result, read the single type-compatible recentReference before doing a fresh search. If the follow-up names a related target or evidence type, use the recent record only as the anchor and traverse declared relationships toward that type before searching the target class directly or deciding a condition.
+- If recentReferences contains an exact entry path for the follow-up target, call the matching class \`.get({ path })\` first only when that entry is the single plausible type-compatible referent or the user identified it with a unique identifier, ordinal, or descriptive selector. A phrase like "that one" is still a bare pronoun when multiple same-type records were displayed or saved together.
+- recentReferences includes user-mentioned records, assistant inline object references, and assistant heap object messages; prefer the latest type-compatible reference only when it is the single plausible referent for the phrase and not merely the last item from a multi-record display or saved list.
+- Record paths are opaque ids. Never synthesize a path from a label, name, title, or user phrase; copy an exact path from [State] or discover the record with a query.
+- If there is exactly one latest type-compatible reference for a phrase like "that same item", use it directly; do not ask the user to restate the item when you can already name or fetch it. This does not apply when the user refers to an earlier slice/list by ordinal wording, or when the prior answer intentionally contrasted several records.
+- For explicit continuity phrases like "that same item", "same record", or "the previous result", do not ask the user which record they mean. Use the recent reference first; if no saved reference exists, rerun the prior narrow grounding lookup from the conversation text instead of answering text-only that the record is not grounded.
+- If a follow-up mutation uses only a pronoun such as "it" or "that" after the prior turn mentioned multiple same-type records, ask the user to choose from grounded options before mutating.
+- If the prior turn displayed or summarized two or more plausible records and the next mutation says only "it", "that", or "on it", do not infer the target from your own ranking; call \`loop.ask_user({ type: "choice", ... })\` with the grounded records first, then mutate only the chosen record.
+- If the prior turn intentionally contrasted multiple records that could all receive the requested mutation, a lone pronoun is ambiguous even when one record was listed first or looked more urgent.
+- If a follow-up mutation uses a bare pronoun and recentReferences contains a matching \`group.id\` with \`group.sameTypeSize\` greater than 1, the target is unresolved. The next code must ask for a grounded choice with \`loop.ask_user(...)\`; never call a mutation on one grouped path first.
+- For follow-up words like "other", "another", or "remaining" after the user selected one candidate from a previous choice, resolve within the active contrast from that choice and the user's answer. Exclude the selected item, preserve descriptors such as larger, smaller, next, older, different, or same status, and do not take the first leftover from a wider saved list when the contrast narrows the intended set.
+- Before any mutation, prove the target resolves to exactly one grounded record. If the request describes a set, category, relationship, prior result group, or other non-unique scope, gather the candidate records first; when more than one candidate remains, ask the user to choose before calling the action.
+- For ambiguous choice prompts before a mutation, every option that describes a different candidate must carry a distinct grounded record value/path. After the answer, do not fall back to the first candidate if matching fails; ask again or stop without mutating.
+- The [State] constants are prompt context, not runtime variables. Never reference \`savedData\`, \`recentReferences\`, \`workflowContext\`, \`workflowState\`, or \`capabilities\` as variables in generated code. When using a recent reference, copy its path string into code and fetch it with \`Class.get({ path: "..." })\`, or call \`heap.getEntry("...")\` when the class is not obvious.
+- Never write placeholder grounding code such as \`const path = null\`, \`const groundedPath = ""\`, or \`const recordPath = ""\`. If no saved reference is available, delete that branch entirely and execute the fallback lookup directly.
+- Never call \`.get({ path: "" })\`; an empty path is not a saved reference.
+- For ordinal references to earlier pages, slices, lists, or ranked results, use the saved list/recent references first. If no saved list is available, rerun the exact same ordered query and select the ordinal index from its returned \`items\`; never invent a record path from a label or ordinal.
+- \`.get({ path })\` returns \`null\` when a path is not found; it does not throw for normal misses. Check for null before using a search fallback.
+- If multiple recent references could satisfy the phrase and the action or target would materially differ, ask for a grounded choice before any confirmation or mutation.
+- If the entity, field, target, scope, ranking, or action is ambiguous, create 2 to 5 plausible interpretations.
+- Probe plausible interpretations with cheap read-only queries before deciding.
+- A zero-result first query is not enough to report failure for a human reference; continue in the same job with another grounded strategy such as partial search, owner/container grounding, or relationship traversal before reporting no match.
+- If a direct target search returns zero and the request contains a stable anchor such as a named related record or higher-level container, ground that anchor and inspect related records before reporting no match.
+- One strong match means proceed.
+- Several plausible matches means call \`loop.ask_user({ type: "choice", ... })\` with grounded choices.
+- No grounded match means ask for missing information.
+- For consequential changes, resolve first, confirm when needed, then act.
+- Do not ask the user to resend a request because you need to verify data. If the request needs verification, run a job that verifies it now. If a follow-up reference is not available, rerun the prior narrow grounding lookup or ask a specific grounded question.
+- If the user asks a read-only advisory question such as "Should we message the team?" and also says not to update/send/act yet, provide the recommendation from grounded data. Do not pause with \`loop.ask_user\` or \`loop.confirm\`.
+- If the user asks for specific fields, read those fields from the grounded record and include every requested value in the visible answer. If saved state identifies the record but does not include the requested fields, fetch the record before answering. Only say a field is unavailable after checking the documented field/property on the fetched record.
+- If the user asks for blocked work and sensitive/restricted work as separate things, keep those candidate sets separate. Exclude sensitive or restricted-workflow records from the ordinary blocked operational candidate unless the user explicitly asks for blocked sensitive work.
+
+Use exploratory probing when:
+- the user gives a human reference instead of an exact id or path
+- a noun could refer to multiple entity types
+- a name, number, label, date, or amount is given without a clear field
+- ranking words are used without a clear metric
+- a requested change has an unclear target
+- the first reasonable lookup returns zero results
+- the first reasonable lookup returns several plausible results
+
+Do not explore when:
+- the entity, field, filter, and action are explicit
+- the request is a general explanation
+- the request is unsupported by available capabilities
+- the next step is already a required workflow answer or confirmation
 
-\u2500\u2500\u2500 DOMAIN REFERENCE (from ./sandbox-tools) \u2500\u2500\u2500
-Import classes and effect functions from \`./sandbox-tools\` in generated code.
-Use the TypeScript declarations for exact signatures. When present, the generated usage notes below them show query patterns and examples.
+[Types]
+Import classes, helpers, and available actions from "./sandbox-tools".
+Use the domain contract below as the exact code-facing contract. Generated docs, relationship indexes, and action indexes are authoritative for valid fields, getters, actions, and filter shapes.
 
 ${domainBlock}
 
-\u2500\u2500\u2500 EXECUTION CHECKPOINT \u2500\u2500\u2500
+[Docs]
+Query policy:
+- Use filter, search, sort, count, page, list, and iterate on entity classes.
+- Push filtering and sorting into entity queries. Do not fetch a page only to filter or sort locally.
+- Valid filter fields are defined by each entity filter type.
+- Valid sort fields are defined by each entity sort field type.
+- Search is class-wide text retrieval, not a field-scoped operator.
+- Entity classes do not have a \`.search(...)\` method. Use \`.find({ search })\`, \`.page({ search, ... })\`, or \`.list({ search, ... })\`.
+- Entity \`.list(...)\` returns an array of records; use \`matches[0]\`, \`matches.length\`, and direct iteration. Entity \`.page(...)\` returns \`{ items, page, perPage, totalCount, hasMore }\`; only page results have \`.items\`.
+- For natural queue slices, infer pagination even when the user does not say "page": "first five" means \`page: 1, perPage: 5\`; a follow-up "next five" for the same queue means \`page: 2, perPage: 5\` with the same sort and grounded filter.
+- For first/next/top queue slices, page the target item class directly with a structured relationship filter. Relationship getters and local \`.slice(0, 5)\` are useful for exploration but do not prove runtime pagination.
+- Combine search and filter when both free-text matching and exact constraints are needed.
+- For exact categorical states, prefer positive filters with \`equal_to\` or \`in\`. Do not express a requested state through substring negation of a different state with \`not_contains\`; categorical labels can contain other labels and disappear from the result.
+- Do not use \`not_in\`; the runtime filter surface does not support it. Use \`in\` with explicit allowed values, or fetch a bounded candidate page and filter excluded values locally before showing the final slice.
+- Boolean filters use \`equal_to: true\` or \`equal_to: false\`.
+- Use \`equal_to\` on names only when you know the full stored value. A shortened name, first word, fragment, alias, or nickname is not an exact name; use search/contains first and then ground the exact record. If an exact-name query returns zero for a human-supplied name, retry with search/contains in the same job before reporting that nothing exists.
+- Keep full-text search strings short and distinctive. Prefer one concrete name/id or 1 to 3 salient terms, then use filters, relationships, or local ranking for the rest.
+- Do not search a target entity for only a related-record name while also filtering by that relationship. First ground the related record, then use a relationship filter/getter, and use target-entity search only for the target's own identifier, title, label, description, or other target-local fields.
+- When the user combines a concrete entity name with generic task words like a priority, workflow state, risk, summary, or requested outcome, do not put the whole phrase into one full-text search. Search/filter the concrete name first, then apply status, priority, relationship, amount, date, or ranking constraints.
+- Treat urgency as priority unless the domain explicitly documents urgent as a status. For an urgent operational item, do not require \`status = "urgent"\`; inspect status/blocker after grounding likely priority matches.
+- Do not sort a free-text priority, severity, or rank-like label field and assume the first row is most important. Rank candidates locally from explicit field values and continue paging or narrow the query when the result says more records exist.
+- When looking for blocked or blocking work, treat phrases such as "no blocker", "not blocked", "without blocker", "none", and "clear" as negative evidence. Do not select a record only because its summary/title contains the substring "block"; prefer explicit blocker/status fields and keep scanning for a true blocker.
+- For broad "open", "active", or "top" operational records, avoid guessing a tiny fixed status list unless the domain documents one. Prefer relationship grounding plus a supported positive filter/list, or locally exclude clearly terminal states such as resolved, closed, complete, completed, paid, canceled, or archived after fetching a bounded sorted candidate page.
+- When a requested object is normally reached through relationships, follow the declared relationship chain from the grounded parent or related record before giving up on a direct search. If the target entity type is named, prefer chains whose declared return types lead to that target type.
+- Prefer generated instance relationship getters from a grounded record over hand-written deep nested relationship filters.
+- When you have grounded a parent record and need its related records, call the declared parent getter such as \`parent.get_related_records()\` instead of writing a nested relationship filter on the target class.
+- When deciding whether a related object is still in a current state, traverse to the related evidence record and call its visible lookup/status action when available. Do not decide, stop, post, or treat the condition as false from only stored fields, the parent record's status/title/summary, or prior displayed text.
+- For queues owned by a higher-level record, ground that record and keep the exact query plan: target class, direct relationship path or getter chain, filters, sort, page, and perPage. Save the displayed page and reuse the same plan for follow-up pages instead of inventing a new relationship filter.
+- Relationship getters return exactly their named entity type. If you call a getter for units/sites, those are not operational items; call the next declared item/work getter on each unit/site, or query the item class directly before reading item fields.
+- Relationship getters return only their declared related entity type. Do not treat one relationship result as another entity type because the request mentions it; walk the declared relationship chain exactly, or use a grounded direct query for the target entity.
+- Only call relationship getters that are declared for the class of the record you currently have. If the needed target is not a direct getter on that class, walk through the declared intermediate getter first; never skip a relationship hop by inventing a convenience getter.
+- Relationship getters are async. Always \`await record.get_related_records()\` before checking whether the result is an array, iterating it, or reading fields from its records.
+- Relationship filter fields are selectors, not hydrated nested objects. To read a field from a related record, call the declared relationship getter and use the returned record; do not read \`record.relationship.someField\` from the original record.
+- Do not filter relationship fields with scalar text operators. For example, do not write \`related: { contains: "Example" }\` or pass a parent path into a child filter; ground the related record first, then use the correctly typed relationship getter or \`id\`/\`path\` filter.
+- Relationship path filters must use a path for the relationship's target type. If a target item has a related parent/container field and the user named a higher-level parent, first follow the parent's declared getter to the correct related record, then use that related record's \`_graphPath\`; never put the wrong record type's path into a child relationship filter.
+- Do not use a target record's local text fields to prove ownership by a named parent/container. A filter such as \`title/summary contains parentName\` is not a relationship. Ground the parent/container and traverse getters or use the documented relationship field.
+- Do not write transitive relationship filters such as \`container: { is: { parent: ... } }\` for queue slices. Use a direct relationship path filter from the already grounded related record, such as \`container: { path: container._graphPath }\`.
+- Do not invent broad relationship filter fields on a target class unless that field is present in the generated filter type. For owned queues, ground the parent first, use declared relationship getters to reach the owned related records, or use the exact documented relationship field.
+- Do not optional-chain relationship getters to guess at hidden relationships. If a getter is not declared in the TypeScript contract, it does not exist.
+- Generated relationship getters return arrays of related records, not page objects. Iterate the returned array directly; do not read \`.items\` from a relationship getter result.
+- If an explicit target entity is not found through an expected relationship chain, try a grounded direct query/search for that target entity before reporting that no target exists.
+- 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.
+- 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.
+- When deciding whether something is blocked, held, delayed, or still active, combine the fresh lookup result with relevant status, blocker, summary, checkpoint, reason, and latest update fields. Do not use a tiny hand-written status allowlist as the only authority; words such as hold, held, pending, delayed, awaiting, blocked, customs, review, and exception are blocking evidence unless the domain explicitly says otherwise.
+- One page does not prove there are no more records. For all, every, export, or broad scans, use iteration or page until there are no more results.
+- When selecting a single "best", "urgent", "top", or "most relevant" record from a broad page, do not assume the first returned page is complete if \`hasMore\` is true. Continue paging, use iteration, or add a stronger grounded filter before selecting.
+- For exploratory work, use count for totals and page with small perPage for samples; use iteration only after the interpretation is chosen.
+
+Lookup ladder:
+1. Check recent references and saved session data.
+2. Try exact id or path when the user gave an id-like value.
+3. If the request names a parent/container plus a target, ground the parent/container and traverse declared relationships to target candidates.
+4. Try exact filters on fields whose names or aliases match the user words.
+5. Try class-wide search with short target-local terms, not the whole user phrase.
+6. Try relationship filters when the user mentions connected concepts and the filter shape is documented.
+7. If the user names a parent/container and says the label may be approximate, inspect related target records before reporting no match.
+8. If still empty, try one small set of normalized, prefix, or fuzzy variants when search supports it.
+9. If still empty or ambiguous, ask the user for steering.
+
+Exploration budget:
+- For a simple ambiguous reference, try up to 3 strategies.
+- For a broad ambiguous task, try up to 5 strategies.
+- Probe with small pages.
+- Do not run exhaustive scans during probing unless the user explicitly asks for all records or the selected task requires aggregation.
+- Stop early when a strong unique match is found.
+
+Strong unique match:
+- exactly one record matches an exact id or path
+- exactly one record matches an exact filter on a likely identifier field
+- exactly one recent reference or saved value fits the request
+- one interpretation has results and all other reasonable interpretations have none
+
+Ask the user when:
+- multiple exact matches exist
+- several entity types match the same phrase
+- the best match comes only from broad search and other plausible matches exist
+- the ranking or metric is unclear
+- the target is unique but the requested action is unclear
+
+Relationship filters:
+- One-record relationships use \`is\`.
+- Multi-record relationships use \`some\`.
+- Never guess relationship cardinality from wording. Check the generated TypeScript filter type for the field before writing a relationship filter; if you are not sure, use declared relationship getters from already grounded records instead of a relationship filter.
+- If a relationship filter type or field is one-record/singular, never use \`some\` on that field. Match by \`id\`, \`path\`, or \`is\`, or fetch the related record and continue through declared getters when you need to traverse farther.
+- Do not invent nested operators under relationship fields. A one-record relationship filter accepts only its documented operators such as \`id\`, \`path\`, \`is\`, \`null\`, and \`not_null\`; deeper conditions must go under \`is\` or be handled by fetching records and following getters.
+- Never use \`some\` on one-record fields. If the generated TypeScript type says \`OneRelationFilter\`, valid operators are \`id\`, \`path\`, \`is\`, \`null\`, and \`not_null\`; \`some\` is invalid.
+- Use \`some\` only when the generated TypeScript type says \`ManyRelationFilter\`.
+- For a singular relationship that points to an intermediate record, nested filters still use \`is\` at the singular hop. Do not use \`some\` because the nested condition names another related record.
+- Use \`{ relationship: { id: "record_id" } }\` or \`{ relationship: { path: "class_record_id" } }\` when matching a known related record.
+- When you already fetched the related record, use \`{ relationship: { path: record._graphPath } }\` or \`{ relationship: { id: record.id } }\`; do not wrap a known id/path under \`is\`.
+- The path used in a relationship filter must be the path of the relationship target. For same-queue follow-ups from an item/batch/ticket, fetch that item's related unit/site/depot first and use the related unit/site/depot path; do not use the item path as a unit/site/depot path.
+- Use \`{ relationship: { is: { field: { equal_to: value } } } }\` only for nested field filters. Never put \`id\` or \`path\` inside \`is\`.
+- Do not write \`{ relationship: { some: ... } }\` unless the generated filter type for that exact relationship says it is a many/collection relationship. For one-record, parent, owner, or many-to-one relationships, use \`path\`, \`id\`, \`is\`, or getter traversal.
+- Do not pass a full record instance into a filter; if you already fetched a record, filter by its id or path instead.
+${domainSections.docs ? `
+Domain notes:
+${domainSections.docs}
+` : ""}
+
+Actions:
+${actionIndex}
+- 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.
+- Never call a record-level action as \`Class.action_name(...)\`; that method will not exist.
+- For action inputs, use the exact property names from the generated TypeScript method signature or the input schema shown in the action list. Do not invent synonym fields for required inputs.
+- Match user verbs to visible action names semantically. If a visible action clearly satisfies the user's requested operation, ground the target record and call that action instead of refusing because the wording differs.
+- When several visible actions or targets plausibly match the request, search/list the plausible grounded candidates, ask for a grounded choice when more than one remains, confirm if needed, then call only the selected visible action.
+- If the user asks to find records in a workflow state first, do not pre-filter away plausible records with unrelated secondary flags unless the ontology explicitly documents that relationship; gather the grounded candidates, ask when more than one remains, then confirm/action the selected record when appropriate.
+- If the user asks for an action that is not visible in the action list, refuse explicitly. Do not answer with only a read-only summary, do not ask for confirmation, and do not attempt hidden, guessed, or similarly named methods.
+- If the user asks to bypass permissions, skip a normal workflow, use a raw HTTP side channel, or export/send restricted data externally, do not ask for confirmation or missing details. Refuse and explain the allowed workflow boundary.
+- A restricted or denied referent stays restricted in follow-up turns. If the user later says "that same item", "fine then", or similar after a sensitive/bypass request, do not perform a mutation on that referent unless a visible allowed workflow explicitly authorizes it.
+- When summarizing records found by a query, include or display stable user-visible identifiers such as number, name, title, label, date, amount, or status. Do not answer only with counts when the user asked what you found.
+
+[State]
+${toolBlock}
+
+${sessionBlock}
+
 ${checkpointBlock}
 
-\u2500\u2500\u2500 WORKFLOW SNAPSHOT \u2500\u2500\u2500
 ${workflowBlock}
 
-\u2500\u2500\u2500 RECENT REFERENTS \u2500\u2500\u2500
 ${referentBlock}
 
-\u2500\u2500\u2500 SESSION HEAP \u2500\u2500\u2500
 ${heapBlock}
 
-\u2500\u2500\u2500 AGENT LOOP STATE \u2500\u2500\u2500
 ${loopBlock}
 
-\u2500\u2500\u2500 LOOP PLAYBOOK \u2500\u2500\u2500
-- Continue from the latest structured state. Treat WORKFLOW SNAPSHOT, EXECUTION CHECKPOINT, RECENT REFERENTS, SESSION HEAP, and AGENT LOOP STATE as the working memory for this request.
-- Use CAPABILITY SNAPSHOT to choose the next step, then use DOMAIN REFERENCE for exact signatures and query shapes.
-- Take the minimum next step that directly helps the user. Avoid duplicate work, speculative cleanup, or extra fetching that is not needed yet.
-- Use RECENT REFERENTS to resolve follow-up references across turns, such as "that invoice", "that customer", "those products", or "the other one".
-- Treat user-provided names, numbers, and labels as human references, not exact keys. Resolve them with code: check recent referents/heap first, then query the graph with the broadest supported \`search\` or \`filter\`, then retry with a few normalized/fuzzy/prefix variants when the first pass is empty or ambiguous. Only say a record does not exist after a reasonable lookup across the relevant class.
-- If one strong match exists, use it. If several plausible matches remain, use \`loop.ask_user({ type: 'choice', ... })\` with the grounded candidates instead of guessing.
-- If the request has more than one reasonable interpretation, ask the user to clarify instead of guessing.
-- For comparisons, rankings, selections, or summaries, first identify the rule you are using. If that rule is not clear from the user request and DOMAIN REFERENCE, ask the user before choosing anything.
-- When the ranking, comparison, or selection rule is unclear, the minimum next step is the clarification itself. Do not run a placeholder query for a provisional winner before asking.
-- If a user request matches both a domain type/effect and a loop helper, prioritize the domain type/effect. For example, if DOMAIN REFERENCE contains a \`Task\` class and the user asks to create a task, create the domain task record; do not call \`loop.create_task(...)\` unless you are only tracking your own workflow.
-- Reuse exact \`taskId\`, \`decisionId\`, and \`closureId\` values from AGENT LOOP STATE. Never invent or rewrite them.
-- If the request is ambiguous or clearly multi-step, create 2-4 short user-visible tasks and keep them updated as the workflow advances.
-- Use \`loop.ask_user({ type: 'choice', options: [...] })\` when you have a short, grounded shortlist the user can choose from. Otherwise use \`type: 'input'\`.
-- For an unclear ranking, comparison, or selection rule, prefer \`type: 'choice'\` when you can offer a short grounded list of plausible interpretations from the domain or nearby context.
-- When \`type: 'choice'\` fits, do not ask the same question as plain text with bullets such as "Common options:" or "Choose one of these:".
-- Use \`loop.confirm(...)\` for consequential approval unless the user already clearly instructed you to perform that exact action now.
-- Await \`loop.ask_user(...)\` and \`loop.confirm(...)\`. After the job resumes, continue in the same job whenever the answer is enough to act.
-- Use \`loop.open_decision(...)\` to persist grounded candidates, \`loop.close_decision(...)\` to resolve one, and \`loop.close_loop(...)\` when the workflow is completed, canceled, or blocked.
-- If you ask a new question in the current job, do not also close the loop in that same job.
+${knownFactsBlock}
 
-\u2500\u2500\u2500 LOOP HELPER REFERENCE \u2500\u2500\u2500
-- \`loop.ask_user(...)\`: pause the current job for missing input; use \`type: 'choice'\` only for a short grounded shortlist.
-- \`loop.confirm(...)\`: pause for yes/no approval before a consequential action, then branch on the returned boolean.
-- \`loop.open_decision(...)\`: save explicit candidates that later jobs can revisit; each candidate needs an \`id\`.
-- \`loop.close_decision(...)\`: resolve an open decision with a stored \`selectedId\` and optional rationale.
-- \`loop.create_task(...)\`, \`loop.update_task(...)\`, \`loop.complete_task(...)\`: keep a short resumable task list for the agent's workflow; these are not domain \`Task\` records.
-- \`loop.close_loop(...)\`: record the workflow outcome when it is completed, canceled, or blocked.
+[Request]
+${input.request?.trim() || "Use the latest user message in the conversation."}`;
+}
 
-\u2500\u2500\u2500 CODE RULES \u2500\u2500\u2500
-- Import from \`./sandbox-tools\`.
-- If you use \`heap\`, \`loop\`, \`agent_text_message\`, or \`agent_heap_objects\`, import them explicitly from \`./sandbox-tools\`.
-- Write top-level executable code with \`await\` at top level.
-- The generated job body must be plain runnable JavaScript. Do not use TypeScript-only syntax.
-- Follow the exact classes, methods, and parameter shapes in DOMAIN REFERENCE. Do not invent helpers or unsupported arguments.
-- Use \`ClassName.get({ path })\` only for known graph paths when you want a direct graph fetch.
-- Use \`ClassName.count()\` for totals, \`ClassName.page({ page, perPage, saveAs })\` when you need \`items\` plus \`totalCount\` or \`hasMore\`, \`ClassName.list({ page, perPage, saveAs })\` for one page of records, and \`ClassName.iterate({ perPage, maxItems })\` for large scans.
-- \`perPage\` defaults to \`100\` and is capped at \`100\`.
-- A single \`list(...)\` or \`page(...)\` call never proves there are no more records. For "all", "every", exports, broad scans, or exhaustive searches, use \`iterate(...)\` when available or loop \`page(...)\` until \`hasMore\` is false.
-- Push \`filter\`, \`search\`, and \`sort\` into graph queries instead of fetching a page and processing it locally.
-- A property appearing on a record does not make it valid in \`filter\` or \`sort\`; only use fields and operators that are explicitly exposed in DOMAIN REFERENCE.
-- Choose \`sort.field\` verbatim from the sortable fields listed in DOMAIN REFERENCE. Do not sort by relationship names, related-record collections, counts, totals, or other derived metrics unless they are explicitly listed as sortable.
-- If ordering alone answers the request, use \`sort\` without inventing a \`filter\`.
-- Do not invent proxy metrics, fallback heuristics, or made-up tie-breakers to resolve ambiguity. If the rule is unclear, ask the user with \`loop.ask_user(...)\`.
-- Do not fetch, sort, or show a provisional record just to have something to display while the real ranking or selection rule is still ambiguous.
-- Call instance methods on instances, static methods on classes, and global effects by name.
-- Use \`heap.getEntry(path)\` for remembered heap entries, \`heap.getList(name)\` for remembered lists, and \`heap.getVar(name)\` only for named variables.
-- Use \`heap.setVar(...)\` and \`heap.deleteVar(...)\` only when they help the next step.
-- Prefer \`heap.setVar(...)\` for scalars or one selected instance. Prefer \`ClassName.list({ saveAs })\` for reusable typed lists. Empty arrays are allowed.
-- Only store sandbox instances, typed lists, or scalars in the heap. If a helper returns plain JSON, keep it local or store only the chosen scalar.
-- Use the \`loop\` helpers to manage workflow state: \`ask_user\`, \`confirm\`, \`open_decision\`, \`close_decision\`, \`create_task\`, \`update_task\`, \`complete_task\`, and \`close_loop\`.
-- Use \`type: 'choice'\` only for short grounded options. Use \`type: 'input'\` when the answer should stay open-ended.
-- \`loop.confirm(...)\` is for consequential approval. Do not ask for approval in plain text.
-- After \`await loop.ask_user(...)\` or \`await loop.confirm(...)\`, continue in the same resumed job when the answer is enough to act.
-- Every job that answers the user must emit \`agent_text_message(...)\` and/or \`agent_heap_objects(...)\`.
-- Use \`agent_text_message(...)\` for user-visible text.
-- Use \`agent_heap_objects(...)\` for user-visible records. You may pass sandbox instances directly, or heap-backed \`entryPaths\`, \`listNames\`, and \`variableNames\` when you already have them. Use \`saveAs\` or \`heap.setVar(...)\` when you need a reusable named selection.
-- Do not rely on the final return value for UI output. Do not return ad-hoc \`reply\` / \`show\` payloads instead of explicit agent message calls.
-- Keep the code small and direct. Avoid speculative branches, broad casts, and raw JSON dumps unless the user asked for them.
-- Use \`console.log()\` only for intermediate diagnostics, not for the final user-facing answer.`;
+// src/openai-usage.ts
+var OPENAI_PRICING_SOURCE_URL = "https://developers.openai.com/api/docs/models/gpt-5.4/";
+var OPENAI_PRICING_EFFECTIVE_DATE = "2026-05-19";
+var OPENAI_MODEL_PRICING_USD_PER_MILLION = {
+  "gpt-5.4": {
+    provider: "openai",
+    model: "gpt-5.4",
+    currency: "USD",
+    inputUsdPerMillion: 2.5,
+    cachedInputUsdPerMillion: 0.25,
+    outputUsdPerMillion: 15,
+    sourceUrl: OPENAI_PRICING_SOURCE_URL,
+    effectiveDate: OPENAI_PRICING_EFFECTIVE_DATE
+  }
+};
+function asRecord5(value) {
+  return value && typeof value === "object" ? value : null;
+}
+function numberField(record, key) {
+  const value = record?.[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function microsPerMillion(usdPerMillion) {
+  return Math.round(usdPerMillion * 1e6);
+}
+function getOpenAIModelPricing(model) {
+  return OPENAI_MODEL_PRICING_USD_PER_MILLION[model] || null;
+}
+function normalizeOpenAIUsage(rawUsage) {
+  const usage = asRecord5(rawUsage);
+  if (!usage) {
+    return {
+      inputTokens: 0,
+      cachedInputTokens: 0,
+      uncachedInputTokens: 0,
+      outputTokens: 0,
+      reasoningTokens: 0,
+      totalTokens: 0
+    };
+  }
+  const inputTokens = numberField(usage, "prompt_tokens") || numberField(usage, "input_tokens");
+  const outputTokens = numberField(usage, "completion_tokens") || numberField(usage, "output_tokens");
+  const totalTokens = numberField(usage, "total_tokens") || inputTokens + outputTokens;
+  const inputDetails = asRecord5(usage.prompt_tokens_details) || asRecord5(usage.input_tokens_details);
+  const outputDetails = asRecord5(usage.completion_tokens_details) || asRecord5(usage.output_tokens_details);
+  const cachedInputTokens = Math.min(
+    inputTokens,
+    numberField(inputDetails, "cached_tokens") || numberField(inputDetails, "cached_input_tokens")
+  );
+  const reasoningTokens = numberField(outputDetails, "reasoning_tokens") || numberField(outputDetails, "reasoning_output_tokens");
+  return {
+    inputTokens,
+    cachedInputTokens,
+    uncachedInputTokens: Math.max(inputTokens - cachedInputTokens, 0),
+    outputTokens,
+    reasoningTokens,
+    totalTokens
+  };
+}
+function calculateOpenAITokenSpend(model, rawUsage) {
+  const pricing = getOpenAIModelPricing(model);
+  if (!pricing) return null;
+  const usage = normalizeOpenAIUsage(rawUsage);
+  const inputPricePerMillionMicros = microsPerMillion(
+    pricing.inputUsdPerMillion
+  );
+  const cachedInputPricePerMillionMicros = microsPerMillion(
+    pricing.cachedInputUsdPerMillion
+  );
+  const outputPricePerMillionMicros = microsPerMillion(
+    pricing.outputUsdPerMillion
+  );
+  const amountMicros = Math.round(
+    (usage.uncachedInputTokens * inputPricePerMillionMicros + usage.cachedInputTokens * cachedInputPricePerMillionMicros + usage.outputTokens * outputPricePerMillionMicros) / 1e6
+  );
+  return {
+    provider: "openai",
+    model,
+    inputTokens: usage.inputTokens,
+    cachedInputTokens: usage.cachedInputTokens,
+    uncachedInputTokens: usage.uncachedInputTokens,
+    outputTokens: usage.outputTokens,
+    reasoningTokens: usage.reasoningTokens,
+    totalTokens: usage.totalTokens,
+    amountMicros,
+    currency: "USD",
+    inputPricePerMillionMicros,
+    cachedInputPricePerMillionMicros,
+    outputPricePerMillionMicros,
+    pricingSource: pricing.sourceUrl,
+    pricingEffectiveAt: pricing.effectiveDate,
+    usage
+  };
 }
 
-export { Environment, EnvironmentSession, Granular, OntologyHandle, Session, WSClient, buildContinuationInstruction, buildGranularAgentCheckpointBlock, buildGranularAgentDomainBlock, buildGranularAgentHeapBlock, buildGranularAgentLoopBlock, buildGranularAgentReferentBlock, buildGranularAgentSessionBlock, buildGranularAgentSystemPrompt, buildGranularAgentToolBlock, buildGranularAgentWorkflowBlock, buildSessionTranscript, createHarnessVerifierSnapshot, evaluateContinuation, extractPromptTokens, getCurrentClosureId, getExclusivePromptTarget, hasOpenPrompt, invokeRegisteredEffect, isLocalApiUrl, normalizeEffectBehaviors, normalizePrompt, normalizePromptText, normalizePromptType, projectConversationReferentFocus, projectConversationReferentSummary, projectHeapSummary, projectLoopSummary, projectWorkflowFocus, projectWorkflowSummary, resolveApiUrl, resolveAuthTokenForApiUrl, resolveJobPresentation, resolvePromptAnswer, reviewGeneratedJobCode, scorePromptChoiceMatch };
+export { Environment, EnvironmentSession, Granular, OPENAI_MODEL_PRICING_USD_PER_MILLION, OntologyHandle, Session, WSClient, buildContinuationInstruction, buildGranularAgentCheckpointBlock, buildGranularAgentDomainBlock, buildGranularAgentHeapBlock, buildGranularAgentLoopBlock, buildGranularAgentReferentBlock, buildGranularAgentSessionBlock, buildGranularAgentSystemPrompt, buildGranularAgentToolBlock, buildGranularAgentWorkflowBlock, buildOpenAISpendEventId, buildSessionTranscript, calculateOpenAITokenSpend, consumeGranularReasoningOnlyChunk, consumeGranularReasoningTraceChunk, createHarnessVerifierSnapshot, evaluateContinuation, extractPromptTokens, getCurrentClosureId, getExclusivePromptTarget, getOpenAIModelPricing, hasOpenPrompt, invokeRegisteredEffect, isLocalApiUrl, normalizeEffectBehaviors, normalizeOpenAIUsage, normalizePrompt, normalizePromptChoiceOption, normalizePromptText, normalizePromptType, projectConversationReferentFocus, projectConversationReferentSummary, projectHeapSummary, projectLoopSummary, projectWorkflowFocus, projectWorkflowSummary, recordOpenAIUsageSpend, resolveApiUrl, resolveAuthTokenForApiUrl, resolveJobPresentation, resolvePromptAnswer, reviewGeneratedJobCode, scorePromptChoiceMatch, stripGranularReasoningTrace, toGranularHttpBase };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map