@granular-software/sdk 0.4.58 → 0.4.60

package/dist/agent-harness.d.mts

@@ -111,7 +111,7 @@ interface BuildGranularAgentSystemPromptInput {
     manualActionSummary?: string;
     tools?: GranularAgentToolInfo[];
     checkpoint?: GranularAgentExecutionCheckpoint | null;
-    outputMode?: "agentMessages" | "returnValue";
+    outputMode?: "feed" | "returnValue";
 }
 type HarnessTemplateStatus = "draft" | "candidate" | "release-candidate" | "stable" | "deprecated";
 interface HarnessTemplateManifest {
@@ -163,12 +163,12 @@ interface HarnessTemplateSelectionOptions {
     strict?: boolean;
 }
 interface GeneratedJobCodeIssue {
-    code: "commonjs_require" | "process_exit" | "dynamic_import_in_job" | "syntax_error_in_job" | "nested_template_literal_in_job" | "undefined_template_identifier" | "object_spread_in_job" | "deprecated_runtime_import" | "deprecated_runtime_helper" | "runtime_namespace_import" | "runtime_import_contract" | "runtime_api_contract" | "missing_runtime_import" | "missing_loop_import" | "bare_loop_helper_import" | "loop_helper_contract" | "stdout_json_reply" | "return_chat_payload";
+    code: "commonjs_require" | "process_exit" | "dynamic_import_in_job" | "syntax_error_in_job" | "nested_template_literal_in_job" | "undefined_template_identifier" | "object_spread_in_job" | "deprecated_runtime_import" | "unknown_runtime_import" | "unsupported_runtime_helper" | "runtime_namespace_import" | "runtime_import_contract" | "runtime_api_contract" | "missing_runtime_import" | "missing_loop_import" | "bare_loop_helper_import" | "loop_helper_contract" | "stdout_json_reply" | "return_chat_payload";
     severity: "error";
     message: string;
 }
 interface ReviewGeneratedJobCodeOptions {
-    outputMode?: "agentMessages" | "returnValue";
+    outputMode?: "feed" | "returnValue";
     request?: string;
     tools?: GranularAgentToolInfo[];
     reply?: string;

package/dist/agent-harness.d.ts

@@ -111,7 +111,7 @@ interface BuildGranularAgentSystemPromptInput {
     manualActionSummary?: string;
     tools?: GranularAgentToolInfo[];
     checkpoint?: GranularAgentExecutionCheckpoint | null;
-    outputMode?: "agentMessages" | "returnValue";
+    outputMode?: "feed" | "returnValue";
 }
 type HarnessTemplateStatus = "draft" | "candidate" | "release-candidate" | "stable" | "deprecated";
 interface HarnessTemplateManifest {
@@ -163,12 +163,12 @@ interface HarnessTemplateSelectionOptions {
     strict?: boolean;
 }
 interface GeneratedJobCodeIssue {
-    code: "commonjs_require" | "process_exit" | "dynamic_import_in_job" | "syntax_error_in_job" | "nested_template_literal_in_job" | "undefined_template_identifier" | "object_spread_in_job" | "deprecated_runtime_import" | "deprecated_runtime_helper" | "runtime_namespace_import" | "runtime_import_contract" | "runtime_api_contract" | "missing_runtime_import" | "missing_loop_import" | "bare_loop_helper_import" | "loop_helper_contract" | "stdout_json_reply" | "return_chat_payload";
+    code: "commonjs_require" | "process_exit" | "dynamic_import_in_job" | "syntax_error_in_job" | "nested_template_literal_in_job" | "undefined_template_identifier" | "object_spread_in_job" | "deprecated_runtime_import" | "unknown_runtime_import" | "unsupported_runtime_helper" | "runtime_namespace_import" | "runtime_import_contract" | "runtime_api_contract" | "missing_runtime_import" | "missing_loop_import" | "bare_loop_helper_import" | "loop_helper_contract" | "stdout_json_reply" | "return_chat_payload";
     severity: "error";
     message: string;
 }
 interface ReviewGeneratedJobCodeOptions {
-    outputMode?: "agentMessages" | "returnValue";
+    outputMode?: "feed" | "returnValue";
     request?: string;
     tools?: GranularAgentToolInfo[];
     reply?: string;

package/dist/agent-harness.js

@@ -527,7 +527,7 @@ function hasNamedModuleImport(source, moduleName, name) {
   const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const imports = source.matchAll(
     new RegExp(
-      `import\\s*\\{([\\s\\S]*?)\\}\\s*from\\s*['"]${escapedModule}['"]`,
+      `import\\s*\\{([^}]*)\\}\\s*from\\s*['"]${escapedModule}['"]`,
       "g"
     )
   );
@@ -536,6 +536,22 @@ function hasNamedModuleImport(source, moduleName, name) {
   }
   return false;
 }
+function namedModuleImports(source, moduleName) {
+  const escapedModule = moduleName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const names = /* @__PURE__ */ new Set();
+  for (const match of source.matchAll(
+    new RegExp(
+      `import\\s*\\{([^}]*)\\}\\s*from\\s*['"]${escapedModule}['"]`,
+      "g"
+    )
+  )) {
+    for (const specifier of match[1].split(",")) {
+      const imported = specifier.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0]?.trim();
+      if (imported) names.add(imported);
+    }
+  }
+  return [...names];
+}
 function hasNamedAgentImport(source, name) {
   return hasNamedModuleImport(source, HARNESS_V3_AGENT_MODULE, name);
 }
@@ -596,18 +612,54 @@ function reviewGeneratedJobCode(code, _options = {}) {
       message: "Generated jobs must not call process.exit(...). Return from the job or emit a runtime message instead."
     });
   }
+  const supportedAgentExports = /* @__PURE__ */ new Set([
+    "actions",
+    "artifacts",
+    "feedback",
+    "formatBlockers",
+    "relativeTime",
+    "replyToUser",
+    "showAgentResponse",
+    "showObjects",
+    "table",
+    "transientFeedback"
+  ]);
+  for (const imported of namedModuleImports(
+    normalized,
+    HARNESS_V3_AGENT_MODULE
+  )) {
+    if (!supportedAgentExports.has(imported)) {
+      issues.push({
+        code: "unknown_runtime_import",
+        severity: "error",
+        message: `Generated code imports unknown runtime value \`${imported}\` from ${HARNESS_V3_AGENT_MODULE}. Import only values listed in [Runtime Imports] and [Types].`
+      });
+    }
+  }
+  const removedAgentHelpers = [
+    ["agent", "text", "message"].join("_"),
+    ["agent", "heap", "objects"].join("_"),
+    ["agent", "message"].join("_")
+  ];
+  for (const name of removedAgentHelpers) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (new RegExp(`\\b${escaped}\\s*\\(`).test(normalized)) {
+      issues.push({
+        code: "unsupported_runtime_helper",
+        severity: "error",
+        message: `Generated code calls removed runtime helper \`${name}\`. Import and call only the canonical feed helpers listed for ${HARNESS_V3_AGENT_MODULE}.`
+      });
+    }
+  }
   for (const [name, replacement, pattern] of [
-    ["agent_text_message", "replyToUser", /\bagent_text_message\s*\(/],
-    ["agent_heap_objects", "showObjects", /\bagent_heap_objects\s*\(/],
-    ["agent_message", "showAgentResponse", /\bagent_message\s*\(/],
     ["heap", "groundedObjects", /\bheap\./],
     ["loop", "userInteraction or work", /\bloop\./]
   ]) {
     if (pattern.test(normalized)) {
       issues.push({
-        code: "deprecated_runtime_helper",
+        code: "unsupported_runtime_helper",
         severity: "error",
-        message: `Generated code uses legacy runtime helper \`${name}\`. Use Harness v3 helper \`${replacement}\` from the modules listed in [Runtime Imports].`
+        message: `Generated code uses unsupported runtime helper \`${name}\`. Use \`${replacement}\` from the modules listed in [Runtime Imports].`
       });
     }
   }
@@ -776,116 +828,7 @@ function normalizeActionSummaryForPrompt(line) {
 }
 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;
-    const entryPaths = uniqueStrings(asArray(show.entryPaths));
-    const entryClassCounts = /* @__PURE__ */ new Map();
-    const entryMetadata = entryPaths.map((entryPath) => {
-      const entry = asRecord(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,
-        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
-      });
-    }
-    for (const listName of uniqueStrings(asArray(show.listNames))) {
-      const list = asRecord(listsByName[listName]);
-      pushReferent({
-        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,
-        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,
-        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,
-        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;
+  return asArray(conversation?.referents).map((value) => asRecord(value)).filter((value) => Boolean(value)).slice().sort((left, right) => (right.ts || 0) - (left.ts || 0));
 }
 function projectConversationReferentFocus(liveDoc) {
   const heap = asRecord(liveDoc?.heap);
@@ -1679,13 +1622,7 @@ function extractRuntimeContractExports(domainBlock) {
   }
   const actionPattern = /export\s+declare\s+function\s+([A-Za-z_$][\w$]*)/g;
   for (const match of domainBlock.matchAll(actionPattern)) {
-    const name = match[1];
-    if (["agent_text_message", "agent_heap_objects", "agent_message"].includes(
-      name
-    )) {
-      continue;
-    }
-    actions.add(name);
+    actions.add(match[1]);
   }
   return {
     classes: Array.from(classes).sort(),
@@ -1742,7 +1679,7 @@ function buildGranularAgentRuntimeImportsBlock(input) {
         importStyle: "named ESM imports only",
         exports: ["replyToUser", "showObjects", "showAgentResponse"],
         contains: "User-facing Harness response helpers for text, grounded object displays, and combined responses.",
-        rule: "Import reply/display helpers from this module; do not use deprecated side-channel helpers."
+        rule: "Import reply/display helpers from this module; only the listed exports are available."
       },
       [HARNESS_V3_SESSION_MODULE]: {
         importStyle: "named ESM imports only",
@@ -2020,9 +1957,9 @@ function splitDomainDocumentation(domainDocumentation) {
   return { types: normalized, docs: "" };
 }
 var DOMAIN_HELPER_FUNCTION_NAMES = /* @__PURE__ */ new Set([
-  "agent_heap_objects",
-  "agent_message",
-  "agent_text_message"
+  "replyToUser",
+  "showAgentResponse",
+  "showObjects"
 ]);
 function inferGlobalActionToolsFromDomainTypes(domainTypes) {
   const inferred = [];
@@ -2158,7 +2095,7 @@ function buildKnownFactsFromCheckpoint(checkpoint) {
   return facts.slice(0, 8);
 }
 function buildGranularAgentSystemPrompt(input) {
-  const outputMode = input.outputMode || "agentMessages";
+  const outputMode = input.outputMode || "feed";
   const promptCapabilities = resolvePromptCapabilities(input.capabilities);
   const domainSections = splitDomainDocumentation(input.domainDocumentation);
   const promptTools = resolvePromptTools(input.tools, domainSections.types);
@@ -2191,7 +2128,7 @@ function buildGranularAgentSystemPrompt(input) {
 - 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 grounded 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.
-- Use \`replyToUser(...)\`, \`showObjects(...)\`, or \`showAgentResponse(...)\` from \`@granular/agent\` when the host exposes job output helpers; do not call deprecated side-channel helpers.` : `- End every user-facing job by returning a short natural-language string.` : promptCapabilities.showRecords ? `- Every job that answers the user must emit \`replyToUser(...)\`, \`showObjects(...)\`, and/or \`showAgentResponse(...)\` from \`@granular/agent\`.
+- Use \`replyToUser(...)\`, \`showObjects(...)\`, or \`showAgentResponse(...)\` from \`@granular/agent\` when the host exposes job output helpers.` : `- End every user-facing job by returning a short natural-language string.` : promptCapabilities.showRecords ? `- Every job that answers the user must emit \`replyToUser(...)\`, \`showObjects(...)\`, and/or \`showAgentResponse(...)\` from \`@granular/agent\`.
 - \`replyToUser(...)\` 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 \`replyToUser(...)\` updates as useful milestones are reached so the user can see what is happening instead of waiting in silence.
   - Write \`replyToUser(...)\` 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.
@@ -2201,11 +2138,10 @@ function buildGranularAgentSystemPrompt(input) {
   - Do not use \`showObjects({ entries: [...] })\` or \`showObjects({ saveAs, entries })\`. Save ordered pages, queues, search results, or ranked lists with \`groundedObjects.save(...)\`, then call \`showObjects({ variableNames: [...] })\` once.
   - Use \`showAgentResponse({ reply, show: [record, action] })\` when one assistant message should combine text, grounded records, files, prepared actions, or action suggestions. The \`action\` can be a state handle such as \`record.lifecycle.approved\` or an action handle such as \`record.lifecycle.approved.reach()\`.
   - Pass grounded records directly in \`show\` when the default record presentation answers the request. When the user asks for particular columns, comparisons, or computed values, import \`table\` (and \`relativeTime\` when useful) from \`@granular/agent\` and call \`showAgentResponse({ reply, show: table(records, [{ label: "Object", value: record => record.label }, { label: "When", value: record => relativeTime(record.timestamp) }]) })\`. Column callbacks must be synchronous and return a scalar, \`Date\`, or \`relativeTime(...)\`; they run inside the job and only resolved cells are persisted.
-  - Do not use deprecated side-channel helpers such as \`agent_text_message(...)\`, \`agent_heap_objects(...)\`, or \`agent_message(...)\` unless the generated types expose no Harness v3 helper alternative.
   - When the user asks to show, list, display, open, or "show them" for records you found, call \`showObjects(...)\`; 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 \`replyToUser(...)\` only. Do not call \`showObjects(...)\`, \`saveAs\`, or \`groundedObjects.save(...)\` unless the user also asked to see records or a later requested action needs a reusable record selection.
   - Use stable saved list names that preserve 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 \`replyToUser(...)\` from \`@granular/agent\`.
+  - Do not rely on the final return value for UI output. Do not return ad-hoc \`reply\` / \`show\` payloads instead of explicit canonical feed calls.` : `- Every job that answers the user must emit \`replyToUser(...)\` from \`@granular/agent\`.
 - \`replyToUser(...)\` 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 \`replyToUser(...)\` updates as useful milestones are reached so the user can see what is happening instead of waiting in silence.
 - Write \`replyToUser(...)\` 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.