@granular-software/sdk 0.4.24 → 0.4.26

package/dist/agent-harness.d.mts

@@ -82,7 +82,7 @@ interface BuildGranularAgentSystemPromptInput {
     checkpoint?: GranularAgentExecutionCheckpoint | null;
 }
 interface GeneratedJobCodeIssue {
-    code: "commonjs_require" | "placeholder_after_confirm" | "placeholder_after_ask_user" | "disambiguation_requires_choice" | "missing_user_reply";
+    code: "commonjs_require" | "placeholder_after_confirm" | "placeholder_after_ask_user" | "disambiguation_requires_choice" | "missing_user_reply" | "return_show_not_for_ui";
     severity: "error";
     message: string;
 }

package/dist/agent-harness.d.ts

@@ -82,7 +82,7 @@ interface BuildGranularAgentSystemPromptInput {
     checkpoint?: GranularAgentExecutionCheckpoint | null;
 }
 interface GeneratedJobCodeIssue {
-    code: "commonjs_require" | "placeholder_after_confirm" | "placeholder_after_ask_user" | "disambiguation_requires_choice" | "missing_user_reply";
+    code: "commonjs_require" | "placeholder_after_confirm" | "placeholder_after_ask_user" | "disambiguation_requires_choice" | "missing_user_reply" | "return_show_not_for_ui";
     severity: "error";
     message: string;
 }

package/dist/agent-harness.js

@@ -139,14 +139,22 @@ function reviewGeneratedJobCode(code) {
       }
     }
   }
-  const hasConversationalReturn = /return\s+[`'"]/.test(normalized) || /\breply\s*:/.test(normalized) || /\bagent_message\s*\(/.test(normalized);
+  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) {
     issues.push({
       code: "missing_user_reply",
       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 use agent_message({ reply, show }). Do not end with bare structured JSON."
+      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."
+    });
+  }
+  if (returnsShowPayload) {
+    issues.push({
+      code: "return_show_not_for_ui",
+      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."
     });
   }
   return issues;
@@ -996,7 +1004,7 @@ ${loopBlock}
 
 \u2500\u2500\u2500 CODE RULES \u2500\u2500\u2500
 - Import from \`./sandbox-tools\`.
-- If you use \`heap\`, \`loop\`, or \`agent_message\`, import them explicitly from \`./sandbox-tools\`.
+- If you use \`heap\`, \`loop\`, \`agent_text_message\`, \`agent_heap_objects\`, or legacy \`agent_message\`, 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.
@@ -1038,14 +1046,17 @@ ${loopBlock}
   - \`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.
-- 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.
+- 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.
 - Use \`console.log()\` only for intermediate diagnostics, not for the final user-facing answer.`;