@granular-software/sdk 0.4.29 → 0.4.31

package/dist/agent-harness.js

@@ -123,21 +123,6 @@ function reviewGeneratedJobCode(code) {
         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."
       });
     }
-    const askUserCalls = normalized.match(/await\s+loop\.ask_user\s*\(\s*\{[\s\S]*?\}\s*\)/g) || [];
-    for (const call of askUserCalls) {
-      const usesChoiceType = /type\s*:\s*['"]choice['"]/.test(call);
-      const usesInputType = /type\s*:\s*['"]input['"]/.test(call);
-      const hasDisambiguationLanguage = /(which|choose|pick|select)/i.test(call) && /(invoice|order|shipment|request|case|work[\s_-]?order)/i.test(call);
-      const includesShortlistOptions = /options\s*:\s*\[/.test(call);
-      if (!usesChoiceType && (usesInputType || hasDisambiguationLanguage || includesShortlistOptions)) {
-        issues.push({
-          code: "disambiguation_requires_choice",
-          severity: "error",
-          message: "When asking the user to choose between known concrete records such as invoices, orders, shipments, requests, cases, or work orders, use loop.ask_user({ type: 'choice', options: [...] }) with a short explicit shortlist instead of a free-text input."
-        });
-        break;
-      }
-    }
   }
   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);
@@ -183,6 +168,184 @@ function extractFocusHintsFromActionSummary(actionSummaryLines) {
     entryPaths: uniqueStrings(entryPaths, 8)
   };
 }
+function normalizeActionSummaryForPrompt(line) {
+  return line.replace(/\blimit=/g, "perPage=").replace(/\blimit:/g, "perPage:");
+}
+function collectConversationReferents(liveDoc) {
+  const conversation = asRecord(liveDoc?.conversation);
+  const persistedReferents = asArray(conversation?.referents).map((value) => asRecord(value)).filter((value) => Boolean(value));
+  if (persistedReferents.length > 0) {
+    return persistedReferents.slice().sort((left, right) => (right.ts || 0) - (left.ts || 0));
+  }
+  const heap = asRecord(liveDoc?.heap);
+  const entriesByPath = asRecord(heap?.entriesByPath) || {};
+  const listsByName = asRecord(heap?.listsByName) || {};
+  const variablesByName = asRecord(heap?.variablesByName) || {};
+  const messages = asArray(conversation?.messages).map((value) => asRecord(value)).filter((value) => Boolean(value)).slice().sort((left, right) => (Number(right.ts) || 0) - (Number(left.ts) || 0));
+  const referents = [];
+  const seen = /* @__PURE__ */ new Set();
+  const pushReferent = (referent) => {
+    if (!referent?.kind || !referent.ref) return;
+    const key = `${referent.kind}:${referent.ref}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    referents.push(referent);
+  };
+  for (const message of messages) {
+    if (message.role !== "assistant") continue;
+    const show = asRecord(message.show);
+    if (!show) continue;
+    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(asArray(show.entryPaths))) {
+      const entry = asRecord(entriesByPath[entryPath]);
+      pushReferent({
+        id: `entry:${entryPath}`,
+        kind: "entry",
+        ref: entryPath,
+        entryPath,
+        className: typeof entry?.className === "string" ? entry.className : void 0,
+        label: typeof entry?.label === "string" && entry.label.trim() ? entry.label.trim() : typeof entry?.id === "string" && entry.id.trim() ? entry.id.trim() : entryPath,
+        messageId,
+        jobId,
+        ts
+      });
+    }
+    for (const listName of uniqueStrings(asArray(show.listNames))) {
+      const list = asRecord(listsByName[listName]);
+      pushReferent({
+        id: `list:${listName}`,
+        kind: "list",
+        ref: listName,
+        listName,
+        className: typeof list?.className === "string" ? list.className : void 0,
+        count: Array.isArray(list?.paths) ? list.paths.length : null,
+        messageId,
+        jobId,
+        ts
+      });
+    }
+    for (const variableName of uniqueStrings(
+      asArray(show.variableNames)
+    )) {
+      const variable = asRecord(variablesByName[variableName]);
+      const entryPath = typeof variable?.entryPath === "string" ? variable.entryPath : void 0;
+      const listName = typeof variable?.listName === "string" ? variable.listName : void 0;
+      const entry = entryPath ? asRecord(entriesByPath[entryPath]) : null;
+      const list = listName ? asRecord(listsByName[listName]) : null;
+      pushReferent({
+        id: `variable:${variableName}`,
+        kind: "variable",
+        ref: variableName,
+        variableName,
+        variableKind: typeof variable?.kind === "string" ? variable.kind : void 0,
+        entryPath,
+        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,
+        count: variable?.kind === "list" && Array.isArray(list?.paths) ? list.paths.length : null,
+        scalarValue: variable?.kind === "scalar" && (typeof variable.value === "string" || typeof variable.value === "number" || typeof variable.value === "boolean" || variable.value === null) ? variable.value : void 0,
+        messageId,
+        jobId,
+        ts
+      });
+    }
+  }
+  return referents;
+}
+function projectConversationReferentFocus(liveDoc) {
+  const heap = asRecord(liveDoc?.heap);
+  const listsByName = asRecord(heap?.listsByName) || {};
+  const referents = collectConversationReferents(liveDoc);
+  const entryPaths = [];
+  const listNames = [];
+  const variableNames = [];
+  for (const referent of referents.slice(0, 8)) {
+    if (referent.kind === "entry" && typeof referent.entryPath === "string") {
+      entryPaths.push(referent.entryPath);
+      continue;
+    }
+    if (referent.kind === "list" && typeof referent.listName === "string") {
+      listNames.push(referent.listName);
+      const list = asRecord(listsByName[referent.listName]);
+      entryPaths.push(...asArray(list?.paths).slice(0, 4));
+      continue;
+    }
+    if (referent.kind === "variable" && typeof referent.variableName === "string") {
+      variableNames.push(referent.variableName);
+      if (typeof referent.entryPath === "string") {
+        entryPaths.push(referent.entryPath);
+      }
+      if (typeof referent.listName === "string") {
+        listNames.push(referent.listName);
+        const list = asRecord(listsByName[referent.listName]);
+        entryPaths.push(...asArray(list?.paths).slice(0, 4));
+      }
+    }
+  }
+  return {
+    entryPaths: uniqueStrings(entryPaths, 8),
+    listNames: uniqueStrings(listNames, 4),
+    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 = [];
+  for (const referent of referents) {
+    if (referent.kind === "entry" && referent.entryPath) {
+      const label = referent.label || referent.entryPath;
+      const classLabel = referent.className || "unknown";
+      entryLines.push(`- ${label} <${referent.entryPath}> [${classLabel}]`);
+      continue;
+    }
+    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;
+    }
+    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}`);
+    }
+  }
+  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");
+}
 function getCurrentClosureId(liveDoc) {
   const loop = asRecord(liveDoc?.loop);
   return typeof loop?.currentClosureId === "string" ? loop.currentClosureId : null;
@@ -395,7 +558,9 @@ function projectWorkflowFocus(liveDoc, pendingPrompts = [], options) {
     variableNames: uniqueStrings(variableNames, 4),
     listNames: uniqueStrings(listNames, 4),
     entryPaths: uniqueStrings(entryPaths, 6),
-    recentActionSummary: uniqueStrings(actionSummaryLines, 8)
+    recentActionSummary: uniqueStrings(actionSummaryLines, 8).map(
+      normalizeActionSummaryForPrompt
+    )
   };
 }
 function projectWorkflowSummary(liveDoc, pendingPrompts = [], options) {
@@ -792,17 +957,14 @@ ${resultPreview}` : null
   ].filter(Boolean).join("\n\n");
 }
 function buildGranularAgentDomainBlock(domainDocumentation) {
-  return domainDocumentation?.trim() || "No domain types available. The graph may not be ready yet.";
+  return domainDocumentation?.trim() || "No domain reference 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],
-    ["userId", sessionContext.userId],
-    ["granularId", sessionContext.granularId],
-    ["userName", sessionContext.userName],
-    ["domainRevision", sessionContext.domainRevision]
+    ["userName", sessionContext.userName]
   ];
   const activeRows = rows.filter(([, value]) => Boolean(value));
   if (activeRows.length === 0) return "No session metadata available.";
@@ -811,6 +973,9 @@ function buildGranularAgentSessionBlock(sessionContext) {
 function buildGranularAgentHeapBlock(heapSummary) {
   return heapSummary?.trim() || "Heap is empty for this session.";
 }
+function buildGranularAgentReferentBlock(referentSummary) {
+  return referentSummary?.trim() || "No recent referents recorded from prior assistant replies.";
+}
 function buildGranularAgentLoopBlock(loopSummary) {
   return loopSummary?.trim() || "No active loop state recorded for this session.";
 }
@@ -834,7 +999,7 @@ function buildGranularAgentToolBlock(tools) {
     (tool) => Boolean(tool.className && !tool.static)
   );
   const lines = [
-    "Treat this block as the planning map. Use DOMAIN TYPES below for exact signatures."
+    "Treat this block as the planning map. Use DOMAIN REFERENCE below for exact signatures and query examples."
   ];
   const appendGroup = (title, group) => {
     lines.push(`- ${title}:`);
@@ -882,7 +1047,10 @@ function buildGranularAgentCheckpointBlock(checkpoint) {
   if (Array.isArray(checkpoint.latestActionSummary) && checkpoint.latestActionSummary.length > 0) {
     lines.push("latestActionSummary:");
     for (const line of checkpoint.latestActionSummary.slice(0, 8)) {
-      lines.push(line.startsWith("- ") ? line : `- ${line}`);
+      const normalizedLine = normalizeActionSummaryForPrompt(line);
+      lines.push(
+        normalizedLine.startsWith("- ") ? normalizedLine : `- ${normalizedLine}`
+      );
     }
   }
   if (checkpoint.latestJobResult?.trim()) {
@@ -898,9 +1066,10 @@ function buildGranularAgentSystemPrompt(input) {
   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 TypeScript code.
+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.
 
 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.
@@ -909,6 +1078,8 @@ When you call \`execute_code\`, additional assistant text must be either:
 - 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.
 
 \u2500\u2500\u2500 STREAMING COMMENT RULES \u2500\u2500\u2500
@@ -928,6 +1099,7 @@ Do not include any other kind of commentary when calling \`execute_code\`.
 - 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.
 
@@ -937,9 +1109,9 @@ ${sessionBlock}
 \u2500\u2500\u2500 CAPABILITY SNAPSHOT \u2500\u2500\u2500
 ${toolBlock}
 
-\u2500\u2500\u2500 DOMAIN TYPES (TypeScript declarations from ./sandbox-tools) \u2500\u2500\u2500
+\u2500\u2500\u2500 DOMAIN REFERENCE (from ./sandbox-tools) \u2500\u2500\u2500
 Import classes and effect functions from \`./sandbox-tools\` in generated code.
-Published effects appear as instance or static methods on the classes below, or as top-level \`export declare function\` entries for global effects.
+Use the TypeScript declarations for exact signatures. When present, the generated usage notes below them show query patterns and examples.
 
 ${domainBlock}
 
@@ -949,6 +1121,9 @@ ${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}
 
@@ -956,109 +1131,54 @@ ${heapBlock}
 ${loopBlock}
 
 \u2500\u2500\u2500 LOOP PLAYBOOK \u2500\u2500\u2500
-- A single user request may span several assistant turns and several jobs. Continue from the latest structured session state instead of restarting.
-- Treat WORKFLOW SNAPSHOT, EXECUTION CHECKPOINT, SESSION HEAP, and AGENT LOOP STATE as the authoritative working memory for the current request.
-- Use CAPABILITY SNAPSHOT to choose the next step quickly, then use DOMAIN TYPES to write exact valid code.
-- Use WORKFLOW SNAPSHOT to understand the current boundary, recent actions, and working set before fetching more data.
-- If the user names a concrete customer, case, order, shipment, or other record that is not already in the heap, fetch it from the graph. "Not in the current context" is not a sufficient reason to stop.
-- Treat user-provided names as human references, not exact database keys. If the user says "Northwind", "the Alpine compressor case", or another shorthand, prefer sensible case-insensitive partial matching across likely records before concluding that nothing matches.
-- If exactly one strong partial-name match exists, use it. If several plausible partial matches exist, ask the user to choose instead of failing on an exact-equality lookup.
-- Take the minimum next step that directly advances the user's request. Do not do speculative cleanup, enrichment, or bookkeeping.
-- Reuse exact \`taskId\`, \`decisionId\`, and \`closureId\` values from the AGENT LOOP STATE block. Never guess or slugify IDs.
-- If the request is ambiguous or clearly multi-step, start by creating 2-4 meaningful user-visible tasks. Do not create a detailed internal checklist.
-- Keep tasks updated as the workflow advances. Complete tasks as soon as they are actually done.
-- Write the smallest straightforward code that fits the current step. Avoid defensive branches for hypothetical states that are not currently true.
-- Before asking a new question, check whether the answer is already present in the current heap, open decisions, or checkpoint.
-- If the previous step made no progress, prefer a different concrete action, a narrower fetch, or a user question instead of repeating equivalent code.
-- Use \`loop.open_decision(...)\` in one job to store grounded candidates, then \`loop.close_decision(...)\` in a later job to pick one stored candidate with \`selectedId\`.
-- Use \`loop.ask_user({ type: 'input', ... })\` only for open-ended preferences or missing free-form text that cannot be represented as a short explicit shortlist.
-- If you already have a short concrete shortlist, usually 2-7 candidates, generate code and call \`loop.ask_user({ type: 'choice', ... })\`. Do not downgrade that to a text input.
-- If multiple concrete records match a singular user reference such as "the invoice", "the order", "the shipment", or "the request", do not silently choose one by heuristic. Ask the user to choose unless the request already uniquely identifies the record.
-- For disambiguation between concrete known records, prefer \`type: 'choice'\` over \`type: 'input'\`. This is especially important for invoices, orders, shipments, requests, work orders, and cases.
-- For \`type: 'choice'\` prompts, make the options directly pickable by a human: use a stable value and a readable label that includes the identifier or title they are likely to recognize.
-- If a shortlist already exists, do not ask the user to type an exact database key or identifier manually. Present the shortlist as clickable choices instead.
-- When reasoning about free-form status strings, do not use brittle substring checks such as \`status.includes("paid")\` because values like \`"unpaid"\` would be misclassified. Prefer explicit positive matches such as \`unpaid\`, \`open\`, or \`overdue\`, or exact normalized comparisons.
-- When multiple concrete records match and \`loop.ask_user(...)\` is available, do not stop with a plain-text question like "Which invoice do you mean?". Persist the live workflow and ask through \`await loop.ask_user(...)\` instead.
-- If the user could reasonably answer with a partial identifier such as \`abcd\` for \`INV-abcd\`, that is another sign the question should be a \`type: 'choice'\` prompt with visible options rather than a free-text input.
-- Never ask for approval in plain text when \`loop.confirm(...)\` is available. Use \`loop.confirm(...)\` for consequential approval.
-- When the correct next step is a loop helper action, generate code and call that helper. Do not replace it with a conversational reply.
-- If you ask the user a new question in the current job, do not also call \`loop.close_loop(...)\` in that same job.
-- When you need user input or approval, await \`loop.ask_user(...)\` or \`loop.confirm(...)\`. The job will pause until the user answers, then resume from that awaited call.
-- It is valid to branch on the value returned by \`await loop.ask_user(...)\` or \`await loop.confirm(...)\` after the job resumes.
-- After \`await loop.ask_user(...)\` returns a concrete choice, continue the workflow in the same resumed job whenever that answer is enough to act. Do not stop with placeholder text such as "I can do that next" or "I'm ready to continue".
-- After \`await loop.confirm(...)\` returns \`true\`, execute the approved mutation in that same resumed job before returning. Do not end with placeholder text like "Approved, ready to make the change next."
-- Only stop immediately after a resumed prompt when the user declined, the workflow is now blocked, or you truly still need another missing piece of information.
-- If the user says stop, enough, or no further action, close the loop and end cleanly without asking another question.
-- If one clear item is already selected and the next step matters, prefer \`loop.confirm(...)\` over another exploratory question.
-- If one clear item is already selected and the only missing input is approval to proceed, use \`loop.confirm(...)\` rather than \`loop.ask_user(...)\`.
-- If the user already gave a usable scheduling window such as "Tuesday morning", treat that as enough to choose a reasonable concrete slot. Do not open another menu just to choose between nearby sub-slots unless a real conflict or hard business rule forces that follow-up.
-- For schedule changes, prefer one grounded recommendation plus one approval prompt. Avoid a second prompt for optional time-window micro-choices when you can pick a sensible default that still satisfies the user request.
-- If the user explicitly instructs you to perform a consequential action now, that instruction counts as approval. Do not add an extra confirmation step unless the user expressed hesitation, ambiguity, or asked you not to execute yet.
-- Direct imperatives such as "cancel this order", "send the reminder now", "approve this refund", or "charge it now" already authorize that exact step. Execute them directly instead of inserting \`loop.confirm(...)\`.
-- If the user says not to do anything irreversible yet, stop at recommendation, review, or approval. Do not collect checkout-only details like quantity, delivery notes, gift message, or optional preferences unless the user explicitly asks to move closer to purchase.
-- Once you have one solid recommendation, prefer summarizing it and asking for approval over gathering more optional preferences.
-- Prefer asking the user for the next missing input over fetching extra related data they did not ask for yet.
-- Avoid serial menus. After one clarifying choice, prefer acting on it, asking one short text question, or confirming rather than opening another menu.
-- When the user asks for a summary "including" concrete records such as unpaid invoices, open cases, orders, or shipments, include the actual identifiers or titles of those records in the reply, not just aggregate counts.
-- Call \`loop.close_loop(...)\` before stopping whenever the current workflow is completed, canceled, or clearly blocked.
+- 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.
+- If the user names a record that is not already in the heap, fetch it from the graph instead of saying it is not in context.
+- Treat user-provided names as human references, not exact keys. If one strong partial match exists, use it. If several plausible matches exist, ask the user to choose.
+- Use RECENT REFERENTS to resolve follow-up references across turns, such as "that invoice", "that customer", "those products", or "the other one".
+- 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.
+- 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.
 
 \u2500\u2500\u2500 CODE RULES \u2500\u2500\u2500
 - Import from \`./sandbox-tools\`.
-- If you use \`heap\`, \`loop\`, \`agent_text_message\`, \`agent_heap_objects\`, or legacy \`agent_message\`, import them explicitly 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. The DOMAIN TYPES block is only a reference for shapes and available methods.
-- Do not write TypeScript-only syntax in executable code: no type annotations, no interfaces, no enums, no \`as Type\` casts, no \`satisfies\`, and no generic type parameters in code.
-- Generated code must be valid against the DOMAIN TYPES block above.
-- Only use classes, methods, and parameter shapes that are explicitly declared in those typedefs.
-- Never invent helper methods such as \`find(...)\` or unsupported parameters such as \`id\` when the typedefs require \`path\`.
-- Use \`ClassName.get({ path })\` only when you already know an object's graph path.
-- Use \`ClassName.count()\` when you only need a total.
-- Use \`ClassName.page({ page, perPage, saveAs })\` when you need both records and pagination metadata like \`totalCount\` or \`hasMore\`. \`perPage\` defaults to \`100\` and larger values are clamped to \`100\`.
-- Use \`ClassName.list({ page, perPage, saveAs })\` to load one typed page of records. \`limit\` is only a legacy alias for \`perPage\`, \`perPage\` defaults to \`100\`, and larger values are clamped to \`100\`.
-- Use \`for await (const item of ClassName.iterate({ perPage, maxItems }))\` for large batch jobs so you do not materialize the whole result set at once. \`perPage\` defaults to \`100\` and larger values are clamped to \`100\`.
-- Instance methods: \`await instance.method_name(params)\`.
-- Static methods: \`await ClassName.static_method(params)\`.
-- Global effects: \`await effect_name(params)\`.
-- When a child record has sparse fields, identify it through nearby graph context instead of only string-matching that child\u2019s local fields. Prefer traversing linked customer, case, work order, part request, and shipment records over broad guesswork.
-- For blocker, delay, ETA, or "what is holding this up?" questions, do not stop at a parent status like \`in_progress\` or \`scheduled\` if linked dependencies exist. Trace into the likely dependency chain first: approval -> work order -> part request -> shipment -> carrier update.
-- A generic parent status is not a sufficient blocker explanation when a linked part request, approval, shipment, customs hold, or vendor delay may be the real cause.
-- If a case summary or latest customer message mentions a part, shipment, ETA, customs, vendor, approval, regulator, kit, or delay, treat that as a strong hint to inspect the linked dependency records before answering.
-- When you already found the correct parent case, inspect its linked child records even if the child summaries use different wording. Do not require a work order, part request, or shipment description to repeat the exact phrase that identified the parent case.
-- Status fields are free-form operational strings, not strict enums. Normalize spelling mentally and do not rely on brittle hard-coded sets that miss variants like \`in-progress\`, \`in_progress\`, \`awaiting-part\`, or \`approval-submitted\`.
-- Do not discard a case, work order, part request, or shipment only because its status string does not match your preferred "open" spelling. If the record is otherwise the clear match, inspect it.
-- Reuse \`heap.getVar(name)\`, \`heap.setVar(name, value)\`, and \`heap.deleteVar(name)\` only when it clearly helps the next step. Do not mirror data into the heap just for completeness.
-- Prefer \`heap.setVar(name, value)\` for scalars or one selected instance. Prefer \`ClassName.list({ page, perPage, saveAs })\` for reusable list pages instead of \`heap.setVar(name, array)\`.
-- Never write an empty array into the heap. If a filtered list is empty, keep it local or clear the previous heap value with \`heap.deleteVar(name)\`.
-- Prefer heap-backed state that represents the current choice or recommendation. Avoid storing extra scalar bookkeeping unless it is needed for the next concrete step.
-- Only store true sandbox instances, typed lists of sandbox instances, or scalars in the heap. Results returned by static effects like availability/search helpers are often plain JSON, not sandbox instances.
-- If a helper returns plain JSON candidates, keep them local, store only a scalar like the chosen id, or resolve the matching sandbox instance before writing it into the heap.
-- When reading heap values, prefer generated generic typings such as \`await heap.getVar<Book[]>("my_books")\` or \`await heap.getVar<Book>("selected_book")\`.
-- If a focused heap variable already points to a known class, read it with that exact generic type and act on it directly. Do not use \`heap.getVar<any>(...)\` or cast through \`any\` when the class is already clear from the prompt. For example, prefer \`await heap.getVar<Order>("selected_order")\` over \`await heap.getVar<any>("selected_order")\`.
-- Use the injected \`loop\` helpers when you need to manage the workflow itself:
-  \`loop.ask_user(...)\`, \`loop.confirm(...)\`, \`loop.open_decision(...)\`, \`loop.close_decision(...)\`,
-  \`loop.create_task(...)\`, \`loop.update_task(...)\`, \`loop.complete_task(...)\`, and \`loop.close_loop(...)\`.
-- Loop helper semantics:
-  - \`loop.open_decision(...)\`: store explicit candidates from the current job so a later job can revisit the same decision. Keep and reuse the returned \`decisionId\`.
-  - \`loop.close_decision(...)\`: resolve an open decision by choosing one stored candidate with \`selectedId\` and recording why. Candidates may be any JSON objects, but each one must have an \`id\`.
-  - \`loop.ask_user(...)\`: pause the job and ask the user for missing input. Default to \`type: 'input'\`; use \`type: 'choice'\` only for a short explicit shortlist. Write \`const answer = await loop.ask_user(...)\`, then continue the same job once the user answers.
-  - \`loop.confirm(...)\`: pause the job for approval before a consequential action. Do not simulate confirmation in plain text. Write \`const approved = await loop.confirm(...)\`, then branch on that approval once the job resumes.
-  - \`loop.create_task(...)\`, \`loop.update_task(...)\`, \`loop.complete_task(...)\`: keep a short task list that later jobs can continue and finish.
-  - \`loop.close_loop(...)\`: record the current workflow outcome with a short summary before stopping. Do not call it in the same job that opens a new user prompt unless the workflow is explicitly blocked. This does not end the session forever.
-- Avoid \`as any\` and other broad casts when the DOMAIN TYPES block already tells you the correct class or list type.
-- Prefer manipulating heap-backed instances and typed lists instead of returning raw JSON blobs or object IDs unless the user explicitly asks for them.
-- Every job that intends to answer the user must emit at least one explicit UI message with \`agent_text_message(...)\` and/or \`agent_heap_objects(...)\`.
-- Use \`agent_text_message("...")\` for all user-visible text shown in the UI.
-- Use \`agent_heap_objects(...)\` only when you want the UI to render heap-backed records or lists.
-- If you want to show both text and records, call \`agent_text_message(...)\` and \`agent_heap_objects(...)\` separately in whatever order fits the interaction.
-- \`agent_text_message(...)\` should be used with a plain text string in normal generated code.
-- \`agent_heap_objects(...)\` should point at heap-backed values: explicit \`entryPaths\` / \`listNames\` / \`variableNames\`, a named list saved with \`saveAs\`, or values read back from \`heap.getVar(...)\`.
-- If you just fetched records and want to show them in the UI, save or reference them through the heap first, then call \`agent_heap_objects(...)\`. Do not try to hand-build UI payloads in job code.
-- Do not assume heap changes will be displayed automatically. If records should appear in the UI, you must call \`agent_heap_objects(...)\`.
-- Never write \`return { reply, show }\` or \`return { show: ... }\` for UI. If you want the UI to render records or lists, call \`agent_heap_objects(...)\` instead.
-- Do not rely on the final return value for user-visible output. A plain return value is not considered a displayed UI answer.
-- \`agent_message(...)\` remains available as a legacy compatibility alias, but prefer \`agent_text_message(...)\` and \`agent_heap_objects(...)\` in new code.
-- Do not return bare structured JSON, low-level diagnostics, or database-shaped payloads as the final answer unless the user explicitly asks for them.
-- Prefer simple executable JavaScript over clever interpolation. Avoid nested template literals or unusually dense inline expressions when a small temporary variable or string concatenation would be clearer and safer.
+- 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\`.
+- 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.`;
 }
 
@@ -1067,6 +1187,7 @@ exports.buildGranularAgentCheckpointBlock = buildGranularAgentCheckpointBlock;
 exports.buildGranularAgentDomainBlock = buildGranularAgentDomainBlock;
 exports.buildGranularAgentHeapBlock = buildGranularAgentHeapBlock;
 exports.buildGranularAgentLoopBlock = buildGranularAgentLoopBlock;
+exports.buildGranularAgentReferentBlock = buildGranularAgentReferentBlock;
 exports.buildGranularAgentSessionBlock = buildGranularAgentSessionBlock;
 exports.buildGranularAgentSystemPrompt = buildGranularAgentSystemPrompt;
 exports.buildGranularAgentToolBlock = buildGranularAgentToolBlock;
@@ -1076,6 +1197,8 @@ exports.evaluateContinuation = evaluateContinuation;
 exports.getCurrentClosureId = getCurrentClosureId;
 exports.getExclusivePromptTarget = getExclusivePromptTarget;
 exports.hasOpenPrompt = hasOpenPrompt;
+exports.projectConversationReferentFocus = projectConversationReferentFocus;
+exports.projectConversationReferentSummary = projectConversationReferentSummary;
 exports.projectHeapSummary = projectHeapSummary;
 exports.projectLoopSummary = projectLoopSummary;
 exports.projectWorkflowFocus = projectWorkflowFocus;