@granular-software/sdk 0.4.21 → 0.4.23

package/dist/agent-harness.mjs

@@ -24,7 +24,8 @@ function uniqueStrings(values, maxCount) {
 }
 function formatScalar(value) {
   if (typeof value === "string") return JSON.stringify(value);
-  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
   if (value === null) return "null";
   return "unknown";
 }
@@ -32,7 +33,9 @@ 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 = asArray(entry.fields).filter((field) => field?.name && field.name !== "_realId" && field.name !== "real_id").slice(0, previewFieldLimit).map((field) => `${field.name}=${formatScalar(field.value)}`).join(", ");
+  const preview = asArray(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 hashString(value) {
@@ -48,7 +51,9 @@ 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);
+  const callMatches = segment.matchAll(
+    /await\s+([A-Za-z0-9_$.]+)\.([A-Za-z0-9_]+)\s*\(/g
+  );
   for (const match of callMatches) {
     const receiver = match[1] || "";
     const method = match[2] || "";
@@ -80,9 +85,16 @@ function reviewGeneratedJobCode(code) {
     /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(");
+    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",
@@ -92,9 +104,16 @@ function reviewGeneratedJobCode(code) {
     }
   }
   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(");
+    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",
@@ -175,7 +194,9 @@ function getLatestClosure(liveDoc) {
     if (!record) continue;
     closures.push({ ...record, closureId });
   }
-  closures.sort((left, right) => (Number(right.createdAt) || 0) - (Number(left.createdAt) || 0));
+  closures.sort(
+    (left, right) => (Number(right.createdAt) || 0) - (Number(left.createdAt) || 0)
+  );
   return closures[0] || null;
 }
 function getWorkflowBoundary(liveDoc, options) {
@@ -213,7 +234,9 @@ function getJobRecords(liveDoc) {
     if (!record) continue;
     jobs.push({ ...record, jobId });
   }
-  jobs.sort((left, right) => getJobTimestamp(right) - getJobTimestamp(left));
+  jobs.sort(
+    (left, right) => getJobTimestamp(right) - getJobTimestamp(left)
+  );
   return jobs;
 }
 function getPromptRecordsFromJobs(liveDoc) {
@@ -221,7 +244,9 @@ function getPromptRecordsFromJobs(liveDoc) {
 }
 function projectWorkflowFocus(liveDoc, pendingPrompts = [], options) {
   const boundary = getWorkflowBoundary(liveDoc, options);
-  const jobs = getJobRecords(liveDoc).filter((job) => getJobTimestamp(job) >= boundary.timestamp).slice(0, 6).reverse();
+  const jobs = getJobRecords(liveDoc).filter(
+    (job) => getJobTimestamp(job) >= boundary.timestamp
+  ).slice(0, 6).reverse();
   const actionSummaryLines = [];
   const variableNames = [];
   const listNames = [];
@@ -273,7 +298,9 @@ function projectWorkflowFocus(liveDoc, pendingPrompts = [], options) {
       return updatedAt >= boundary.timestamp;
     }
     return status !== "completed" && status !== "canceled" ? true : updatedAt >= boundary.timestamp;
-  }).sort((left, right) => (Number(right.updatedAt) || Number(right.createdAt) || 0) - (Number(left.updatedAt) || Number(left.createdAt) || 0));
+  }).sort(
+    (left, right) => (Number(right.updatedAt) || Number(right.createdAt) || 0) - (Number(left.updatedAt) || Number(left.createdAt) || 0)
+  );
   for (const task of tasks.slice(0, 4)) {
     if (typeof task.taskId === "string") {
       activeTaskIds.push(task.taskId);
@@ -285,7 +312,9 @@ function projectWorkflowFocus(liveDoc, pendingPrompts = [], options) {
       return updatedAt >= boundary.timestamp;
     }
     return decision.status === "open" || updatedAt >= boundary.timestamp;
-  }).sort((left, right) => (Number(right.updatedAt) || Number(right.createdAt) || 0) - (Number(left.updatedAt) || Number(left.createdAt) || 0));
+  }).sort(
+    (left, right) => (Number(right.updatedAt) || Number(right.createdAt) || 0) - (Number(left.updatedAt) || Number(left.createdAt) || 0)
+  );
   for (const decision of decisions.slice(0, 3)) {
     if (typeof decision.decisionId === "string" && decision.status === "open") {
       openDecisionIds.push(decision.decisionId);
@@ -364,11 +393,15 @@ function projectWorkflowSummary(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.");
+    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(
+      "- No prior closed loop recorded; use the latest user request as the boundary."
+    );
   }
   lines.push("", "Recent Actions:");
   if (focus.recentActionSummary.length === 0) {
@@ -437,12 +470,17 @@ function projectLoopSummary(liveDoc, pendingPrompts = [], options) {
       return updatedAt >= boundary.timestamp;
     }
     return status !== "completed" && status !== "canceled" ? true : updatedAt >= boundary.timestamp;
-  }).sort((left, right) => (Number(right.updatedAt) || 0) - (Number(left.updatedAt) || 0));
+  }).sort(
+    (left, right) => (Number(right.updatedAt) || 0) - (Number(left.updatedAt) || 0)
+  );
   const activeTasks = tasks.filter((task) => {
     const status = typeof task.status === "string" ? task.status : "pending";
     return status !== "completed" && status !== "canceled";
   });
-  const visibleTasks = (activeTasks.length > 0 ? activeTasks : tasks).slice(0, 5);
+  const visibleTasks = (activeTasks.length > 0 ? activeTasks : tasks).slice(
+    0,
+    5
+  );
   const hiddenTaskCount = Math.max(0, activeTasks.length - visibleTasks.length);
   lines.push("Tasks:");
   if (visibleTasks.length === 0) {
@@ -466,8 +504,12 @@ function projectLoopSummary(liveDoc, pendingPrompts = [], options) {
       return updatedAt >= boundary.timestamp;
     }
     return decision.status === "open" || updatedAt >= boundary.timestamp;
-  }).sort((left, right) => (Number(right.updatedAt) || Number(right.createdAt) || 0) - (Number(left.updatedAt) || Number(left.createdAt) || 0));
-  const openDecisions = decisions.filter((decision) => decision.status === "open");
+  }).sort(
+    (left, right) => (Number(right.updatedAt) || Number(right.createdAt) || 0) - (Number(left.updatedAt) || Number(left.createdAt) || 0)
+  );
+  const openDecisions = decisions.filter(
+    (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) {
@@ -486,7 +528,9 @@ function projectLoopSummary(liveDoc, pendingPrompts = [], options) {
           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}` : ""}`);
+        lines.push(
+          `- [open] ${title} (${decisionId})${candidatePreview ? ` \u2014 candidates: ${candidatePreview}` : ""}`
+        );
       } else {
         const selected = asRecord(decision.selected);
         const label = typeof selected?.label === "string" ? selected.label : typeof selected?.id === "string" ? selected.id : "unknown";
@@ -501,13 +545,17 @@ function projectLoopSummary(liveDoc, pendingPrompts = [], options) {
       title: prompt.title,
       message: prompt.message
     })),
-    ...Object.values(asRecord(asRecord(liveDoc?.jobs)?.byId) || {}).flatMap((job) => Object.values(asRecord(asRecord(job)?.prompts) || {})).map((prompt) => asRecord(prompt)).filter((prompt) => Boolean(prompt && prompt.status === "open"))
+    ...Object.values(asRecord(asRecord(liveDoc?.jobs)?.byId) || {}).flatMap((job) => Object.values(asRecord(asRecord(job)?.prompts) || {})).map((prompt) => asRecord(prompt)).filter(
+      (prompt) => Boolean(prompt && prompt.status === "open")
+    )
   ];
   const visiblePrompts = boundary.reason === "request_start" ? openPrompts.filter((prompt) => {
     const promptRecord = asRecord(prompt);
     const openedAt = Number(promptRecord?.openedAt) || 0;
     const promptId = typeof promptRecord?.id === "string" ? promptRecord.id : typeof prompt.id === "string" ? prompt.id : null;
-    return openedAt >= boundary.timestamp || (promptId ? pendingPrompts.some((pendingPrompt) => pendingPrompt.id === promptId) : false);
+    return openedAt >= boundary.timestamp || (promptId ? pendingPrompts.some(
+      (pendingPrompt) => pendingPrompt.id === promptId
+    ) : false);
   }) : openPrompts;
   lines.push("", "Open Prompts:");
   if (visiblePrompts.length === 0) {
@@ -538,9 +586,15 @@ function projectHeapSummary(heap, options) {
   const entriesByPath = asRecord(heapRecord.entriesByPath) || {};
   const listsByName = asRecord(heapRecord.listsByName) || {};
   const variablesByName = asRecord(heapRecord.variablesByName) || {};
-  const focusedVariableNames = new Set(uniqueStrings(options?.focus?.variableNames || []));
-  const focusedListNames = new Set(uniqueStrings(options?.focus?.listNames || []));
-  const focusedEntryPaths = new Set(uniqueStrings(options?.focus?.entryPaths || []));
+  const focusedVariableNames = new Set(
+    uniqueStrings(options?.focus?.variableNames || [])
+  );
+  const focusedListNames = new Set(
+    uniqueStrings(options?.focus?.listNames || [])
+  );
+  const focusedEntryPaths = new Set(
+    uniqueStrings(options?.focus?.entryPaths || [])
+  );
   const hasFocus = focusedVariableNames.size > 0 || focusedListNames.size > 0 || focusedEntryPaths.size > 0;
   const suppressRecentFallback = Boolean(options?.focus) && !hasFocus;
   const maxVariables = options?.maxVariables ?? (hasFocus ? 4 : 6);
@@ -552,20 +606,26 @@ function projectHeapSummary(heap, options) {
     return rightFocused - leftFocused || (right.updatedAt || 0) - (left.updatedAt || 0);
   }).filter((variable, index) => {
     if (index < maxVariables) return true;
-    return Boolean(variable.name && focusedVariableNames.has(variable.name));
+    return Boolean(
+      variable.name && focusedVariableNames.has(variable.name)
+    );
   }).slice(0, maxVariables);
   const referencedPaths = /* @__PURE__ */ new Set();
   for (const variable of variables) {
     if (variable.entryPath) referencedPaths.add(variable.entryPath);
     if (variable.listName) {
-      const list = asRecord(listsByName[variable.listName]);
+      const list = asRecord(
+        listsByName[variable.listName]
+      );
       for (const path of list?.paths || []) referencedPaths.add(path);
     }
   }
   for (const path of focusedEntryPaths) {
     referencedPaths.add(path);
   }
-  const visibleLists = Object.values(listsByName).map((value) => asRecord(value)).filter((value) => Boolean(value)).filter((list) => variables.some((variable) => variable.listName === list.name) || Boolean(list.name && focusedListNames.has(list.name))).sort((left, right) => (right.updatedAt || 0) - (left.updatedAt || 0)).slice(0, maxLists);
+  const visibleLists = Object.values(listsByName).map((value) => asRecord(value)).filter((value) => Boolean(value)).filter(
+    (list) => variables.some((variable) => 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) => asRecord(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:");
@@ -574,16 +634,24 @@ function projectHeapSummary(heap, options) {
   } else {
     for (const variable of variables) {
       if (variable.kind === "scalar") {
-        lines.push(`- ${variable.name}: scalar = ${formatScalar(variable.value)}`);
+        lines.push(
+          `- ${variable.name}: scalar = ${formatScalar(variable.value)}`
+        );
         continue;
       }
       if (variable.kind === "entry") {
-        const entry = variable.entryPath ? asRecord(entriesByPath[variable.entryPath]) : null;
-        lines.push(`- ${variable.name}: entry<${variable.className || entry?.className || "unknown"}> -> ${entry ? describeHeapEntry(entry) : variable.entryPath || "missing"}`);
+        const entry = variable.entryPath ? asRecord(
+          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 ? asRecord(listsByName[variable.listName]) : null;
-      lines.push(`- ${variable.name}: list<${variable.className || list?.className || "unknown"}> -> ${(list?.paths || []).length} item(s)`);
+      lines.push(
+        `- ${variable.name}: list<${variable.className || list?.className || "unknown"}> -> ${(list?.paths || []).length} item(s)`
+      );
     }
   }
   lines.push("", "Named Lists:");
@@ -591,7 +659,9 @@ function projectHeapSummary(heap, options) {
     lines.push("- none");
   } else {
     for (const list of visibleLists) {
-      lines.push(`- ${list.name}: ${list.className || "unknown"}[${(list.paths || []).length}]`);
+      lines.push(
+        `- ${list.name}: ${list.className || "unknown"}[${(list.paths || []).length}]`
+      );
     }
   }
   lines.push("", "Active Entries:");
@@ -605,11 +675,19 @@ function projectHeapSummary(heap, options) {
   return lines.join("\n");
 }
 function createHarnessVerifierSnapshot(input) {
-  const workflowFocus = projectWorkflowFocus(input.liveDoc, [], input.projectionOptions);
-  const heapDigest = hashString(projectHeapSummary(asRecord(input.liveDoc?.heap), {
-    focus: workflowFocus
-  })) || "00000000";
-  const loopDigest = hashString(projectWorkflowSummary(input.liveDoc, [], input.projectionOptions)) || "00000000";
+  const workflowFocus = projectWorkflowFocus(
+    input.liveDoc,
+    [],
+    input.projectionOptions
+  );
+  const heapDigest = hashString(
+    projectHeapSummary(asRecord(input.liveDoc?.heap), {
+      focus: workflowFocus
+    })
+  ) || "00000000";
+  const loopDigest = hashString(
+    projectWorkflowSummary(input.liveDoc, [], input.projectionOptions)
+  ) || "00000000";
   return {
     codeDigest: hashString(input.finalCode?.trim()),
     resultDigest: hashString(input.resultPreview?.trim()),
@@ -739,8 +817,12 @@ function buildGranularAgentToolBlock(tools) {
     return "No live effects are available in this session yet.";
   }
   const globalTools = normalizedTools.filter((tool) => !tool.className);
-  const staticTools = normalizedTools.filter((tool) => Boolean(tool.className && tool.static));
-  const instanceTools = normalizedTools.filter((tool) => Boolean(tool.className && !tool.static));
+  const staticTools = normalizedTools.filter(
+    (tool) => Boolean(tool.className && tool.static)
+  );
+  const instanceTools = normalizedTools.filter(
+    (tool) => Boolean(tool.className && !tool.static)
+  );
   const lines = [
     "Treat this block as the planning map. Use DOMAIN TYPES below for exact signatures."
   ];
@@ -955,7 +1037,10 @@ ${loopBlock}
 - 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.
 - If the user expects an answer after the job runs, the final \`return\` value must be either a short natural-language string or an object with a top-level \`reply\` string.
+- You may call \`agent_message(...)\` multiple times in one job to post several assistant messages while the job is still running.
 - Prefer \`agent_message({ reply, show })\` when you want to leave a user-facing answer and optionally show heap-backed records in the UI.
+- \`agent_message(...)\` also accepts \`content\`, \`message\`, or \`text\` instead of \`reply\`.
+- \`agent_message({ show })\` may receive explicit refs or sandbox instances and arrays of sandbox instances. The runtime will convert those into UI references.
 - When it helps the UI show specific heap-backed results, you may instead return:
   \`{ reply: string, show: { entryPaths?: string[], listNames?: string[], variableNames?: string[] } }\`
 - If you create or load objects the user should see, save them in the heap and return references to them through \`show\` instead of serializing full objects.