@granular-software/sdk 0.4.24 → 0.4.25

package/dist/cli/index.js

@@ -18160,6 +18160,7 @@ var Session = class {
   client;
   clientId;
   jobsMap = /* @__PURE__ */ new Map();
+  pendingAgentMessagesByJobId = /* @__PURE__ */ new Map();
   eventListeners = /* @__PURE__ */ new Map();
   toolHandlers = /* @__PURE__ */ new Map();
   /** Tracks which tools are instance methods (className set, not static) */
@@ -18317,6 +18318,15 @@ var Session = class {
       createdAt: Date.now()
     });
     this.jobsMap.set(result.jobId, job2);
+    const pendingAgentMessages = this.pendingAgentMessagesByJobId.get(
+      result.jobId
+    );
+    if (pendingAgentMessages && pendingAgentMessages.length > 0) {
+      this.pendingAgentMessagesByJobId.delete(result.jobId);
+      for (const message of pendingAgentMessages) {
+        job2.replayAgentMessage(message);
+      }
+    }
     return job2;
   }
   /**
@@ -18718,6 +18728,22 @@ import { ${allImports} } from "./sandbox-tools";
     this.client.on("job.status", (data) => {
       this.emit("job:status", data);
     });
+    this.client.on("job.agent_message", (data) => {
+      const normalized = normalizeJobAgentMessageEnvelope(data);
+      if (!normalized) return;
+      if (this.jobsMap.has(normalized.jobId)) return;
+      const pending = this.pendingAgentMessagesByJobId.get(normalized.jobId) || [];
+      if (normalized.message.messageId && pending.some(
+        (message) => message.messageId === normalized.message.messageId
+      )) {
+        return;
+      }
+      pending.push(normalized.message);
+      this.pendingAgentMessagesByJobId.set(
+        normalized.jobId,
+        pending.slice(-25)
+      );
+    });
     this.client.on("exec.completed", (data) => {
       this.emit("exec:completed", data);
     });
@@ -18842,6 +18868,22 @@ function sanitizeFeedbackValue(value, depth = 0, seen = /* @__PURE__ */ new Weak
   }
   return truncateFeedbackString(String(value));
 }
+function normalizeJobAgentMessageEnvelope(data) {
+  const d = data;
+  if (typeof d?.jobId !== "string" || !d.jobId) {
+    return null;
+  }
+  return {
+    jobId: d.jobId,
+    message: {
+      messageId: d.messageId,
+      kind: d.kind === "artifacts" ? "artifacts" : "text",
+      reply: typeof d.reply === "string" ? d.reply : "",
+      show: d.show,
+      timestamp: d.timestamp || Date.now()
+    }
+  };
+}
 var JobImplementation = class {
   id;
   client;
@@ -18850,6 +18892,8 @@ var JobImplementation = class {
   _resolveResult;
   _rejectResult;
   eventListeners = /* @__PURE__ */ new Map();
+  bufferedAgentMessages = [];
+  bufferedAgentMessageIds = /* @__PURE__ */ new Set();
   metadata;
   constructor(id, client, initialState) {
     this.id = id;
@@ -19008,14 +19052,9 @@ var JobImplementation = class {
       }
     });
     this.client.on("job.agent_message", (data) => {
-      const d = data;
-      if (d.jobId === id) {
-        this.emit("agentMessage", {
-          messageId: d.messageId,
-          reply: typeof d.reply === "string" ? d.reply : "",
-          show: d.show,
-          timestamp: d.timestamp || Date.now()
-        });
+      const normalized = normalizeJobAgentMessageEnvelope(data);
+      if (normalized?.jobId === id) {
+        this.captureAgentMessage(normalized.message);
       }
     });
   }
@@ -19042,6 +19081,14 @@ var JobImplementation = class {
       this.eventListeners.set(event, []);
     }
     this.eventListeners.get(event).push(handler);
+    if (event === "agentMessage" && this.bufferedAgentMessages.length > 0) {
+      for (const message of this.bufferedAgentMessages) {
+        handler(message);
+      }
+    }
+  }
+  replayAgentMessage(message) {
+    this.captureAgentMessage(message);
   }
   buildFeedbackMetadata() {
     const startedAt = this.metadata.startedAt;
@@ -19111,6 +19158,18 @@ var JobImplementation = class {
       handlers.forEach((h) => h(data));
     }
   }
+  captureAgentMessage(message) {
+    if (message.messageId && this.bufferedAgentMessageIds.has(message.messageId)) {
+      return;
+    }
+    if (message.messageId) {
+      this.bufferedAgentMessageIds.add(message.messageId);
+    }
+    this.bufferedAgentMessages = [...this.bufferedAgentMessages, message].slice(
+      -25
+    );
+    this.emit("agentMessage", message);
+  }
 };
 
 // src/effect-runtime.ts

package/dist/{client-CQFKsCTd.d.mts → client-BeKRGMoT.d.mts}

@@ -1254,6 +1254,7 @@ declare class Session {
     protected client: WSClient;
     private clientId;
     private jobsMap;
+    private pendingAgentMessagesByJobId;
     private eventListeners;
     private toolHandlers;
     /** Tracks which tools are instance methods (className set, not static) */

package/dist/{client-CQFKsCTd.d.ts → client-BeKRGMoT.d.ts}

@@ -1254,6 +1254,7 @@ declare class Session {
     protected client: WSClient;
     private clientId;
     private jobsMap;
+    private pendingAgentMessagesByJobId;
     private eventListeners;
     private toolHandlers;
     /** Tracks which tools are instance methods (className set, not static) */

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { E as EndpointMode, T as ToolWithHandler, a as EffectHandlerContext, M as ManifestEffectMetamodelSpec, R as ResolvedEffectBehaviors, S as SessionHeapEntry, b as SessionHeapList, c as SessionHeapSnapshot, P as Prompt } from './client-CQFKsCTd.mjs';
-export { b1 as APIError, A as AccessTokenProvider, u as Assignment, v as AssignmentListResponse, K as Build, N as BuildListResponse, B as BuildPolicy, J as BuildStatus, C as ConnectOptions, m as ConversationSessionInfo, y as CreateEnvironmentData, s as CreatePermissionProfileData, o as CreateSandboxData, aw as DefineRelationshipOptions, b2 as DeleteResponse, D as DomainState, a8 as EffectHandler, a5 as EffectInfo, a0 as EffectInvocationMetadata, $ as EffectInvocationMode, a1 as EffectSchema, a2 as EffectWithHandler, a7 as EffectsChangedEvent, d as Environment, x as EnvironmentData, z as EnvironmentListResponse, aG as EnvironmentRecordImportSummary, G as Granular, j as GranularAuth, i as GranularOptions, b0 as GraphQLResult, a9 as InstanceEffectHandler, I as InstanceToolHandler, ah as Job, ae as JobFeedbackInput, ad as JobFeedbackMetadata, af as JobFeedbackRecord, ab as JobFeedbackSentiment, ac as JobFeedbackToolCall, aa as JobStatus, ag as JobSubmitResult, F as Manifest, aS as ManifestApprovalRequiredSpec, a$ as ManifestContent, aQ as ManifestDryRunSpec, aV as ManifestEffectDeclaration, aU as ManifestEffectSchema, aJ as ManifestEnumRuleSpec, aX as ManifestEventStreamDef, aW as ManifestEventTypeDef, aK as ManifestFilterBySpec, aZ as ManifestImport, H as ManifestListResponse, aY as ManifestOperation, aP as ManifestPostConditionSpec, aH as ManifestPropertySpec, aT as ManifestRelationshipDef, aR as ManifestReverseSpec, aO as ManifestStateMachineSpec, aM as ManifestStateMachineStateSpec, aN as ManifestStateMachineTransitionSpec, aI as ManifestValidationOperator, aL as ManifestValidationRuleSpec, a_ as ManifestVolume, au as ModelRef, r as PermissionProfile, t as PermissionProfileListResponse, q as PermissionRules, a3 as PublishEffectsResult, g as PublishToolsResult, ao as RPCRequest, ar as RPCRequestFromServer, ap as RPCResponse, aF as RecordImport, aE as RecordImportItem, aC as RecordImportItemStatus, aD as RecordImportStats, aB as RecordImportStatus, ax as RecordObjectOptions, ay as RecordObjectResult, az as RecordObjectsChunkInfo, aA as RecordObjectsOptions, k as RecordUserOptions, av as RelationshipInfo, _ as ResolvedEffectApprovalRequired, Y as ResolvedEffectDryRun, X as ResolvedEffectPostCondition, Z as ResolvedEffectReverse, n as Sandbox, p as SandboxListResponse, Q as SemanticVersionDiff, O as SemanticVersionDiffEntry, e as Session, ai as SessionHeapFieldType, aj as SessionHeapFieldValue, ak as SessionHeapVariable, b3 as StreamEvent, b5 as StreamStats, b4 as StreamSubscription, l as Subject, aq as SyncMessage, h as ToolHandler, a4 as ToolInfo, as as ToolInvokeParams, at as ToolResultParams, f as ToolSchema, a6 as ToolsChangedEvent, U as User, L as Version, w as VersionTag, V as VersionTracking, W as WSClient, an as WSClientOptions, al as WSDisconnectInfo, am as WSReconnectErrorInfo } from './client-CQFKsCTd.mjs';
+import { E as EndpointMode, T as ToolWithHandler, a as EffectHandlerContext, M as ManifestEffectMetamodelSpec, R as ResolvedEffectBehaviors, S as SessionHeapEntry, b as SessionHeapList, c as SessionHeapSnapshot, P as Prompt } from './client-BeKRGMoT.mjs';
+export { b1 as APIError, A as AccessTokenProvider, u as Assignment, v as AssignmentListResponse, K as Build, N as BuildListResponse, B as BuildPolicy, J as BuildStatus, C as ConnectOptions, m as ConversationSessionInfo, y as CreateEnvironmentData, s as CreatePermissionProfileData, o as CreateSandboxData, aw as DefineRelationshipOptions, b2 as DeleteResponse, D as DomainState, a8 as EffectHandler, a5 as EffectInfo, a0 as EffectInvocationMetadata, $ as EffectInvocationMode, a1 as EffectSchema, a2 as EffectWithHandler, a7 as EffectsChangedEvent, d as Environment, x as EnvironmentData, z as EnvironmentListResponse, aG as EnvironmentRecordImportSummary, G as Granular, j as GranularAuth, i as GranularOptions, b0 as GraphQLResult, a9 as InstanceEffectHandler, I as InstanceToolHandler, ah as Job, ae as JobFeedbackInput, ad as JobFeedbackMetadata, af as JobFeedbackRecord, ab as JobFeedbackSentiment, ac as JobFeedbackToolCall, aa as JobStatus, ag as JobSubmitResult, F as Manifest, aS as ManifestApprovalRequiredSpec, a$ as ManifestContent, aQ as ManifestDryRunSpec, aV as ManifestEffectDeclaration, aU as ManifestEffectSchema, aJ as ManifestEnumRuleSpec, aX as ManifestEventStreamDef, aW as ManifestEventTypeDef, aK as ManifestFilterBySpec, aZ as ManifestImport, H as ManifestListResponse, aY as ManifestOperation, aP as ManifestPostConditionSpec, aH as ManifestPropertySpec, aT as ManifestRelationshipDef, aR as ManifestReverseSpec, aO as ManifestStateMachineSpec, aM as ManifestStateMachineStateSpec, aN as ManifestStateMachineTransitionSpec, aI as ManifestValidationOperator, aL as ManifestValidationRuleSpec, a_ as ManifestVolume, au as ModelRef, r as PermissionProfile, t as PermissionProfileListResponse, q as PermissionRules, a3 as PublishEffectsResult, g as PublishToolsResult, ao as RPCRequest, ar as RPCRequestFromServer, ap as RPCResponse, aF as RecordImport, aE as RecordImportItem, aC as RecordImportItemStatus, aD as RecordImportStats, aB as RecordImportStatus, ax as RecordObjectOptions, ay as RecordObjectResult, az as RecordObjectsChunkInfo, aA as RecordObjectsOptions, k as RecordUserOptions, av as RelationshipInfo, _ as ResolvedEffectApprovalRequired, Y as ResolvedEffectDryRun, X as ResolvedEffectPostCondition, Z as ResolvedEffectReverse, n as Sandbox, p as SandboxListResponse, Q as SemanticVersionDiff, O as SemanticVersionDiffEntry, e as Session, ai as SessionHeapFieldType, aj as SessionHeapFieldValue, ak as SessionHeapVariable, b3 as StreamEvent, b5 as StreamStats, b4 as StreamSubscription, l as Subject, aq as SyncMessage, h as ToolHandler, a4 as ToolInfo, as as ToolInvokeParams, at as ToolResultParams, f as ToolSchema, a6 as ToolsChangedEvent, U as User, L as Version, w as VersionTag, V as VersionTracking, W as WSClient, an as WSClientOptions, al as WSDisconnectInfo, am as WSReconnectErrorInfo } from './client-BeKRGMoT.mjs';
 export { BuildGranularAgentSystemPromptInput, GeneratedJobCodeIssue, GranularAgentExecutionCheckpoint, GranularAgentHeapSummaryOptions, GranularAgentSessionContext, GranularAgentToolInfo, GranularAgentWorkflowFocus, HarnessContinuationDecision, HarnessControllerBudgets, HarnessProjectionOptions, HarnessPromptLike, HarnessVerifierSnapshot, HarnessVerifierSnapshotInput, buildContinuationInstruction, buildGranularAgentCheckpointBlock, buildGranularAgentDomainBlock, buildGranularAgentHeapBlock, buildGranularAgentLoopBlock, buildGranularAgentSessionBlock, buildGranularAgentSystemPrompt, buildGranularAgentToolBlock, buildGranularAgentWorkflowBlock, createHarnessVerifierSnapshot, evaluateContinuation, getCurrentClosureId, getExclusivePromptTarget, hasOpenPrompt, projectHeapSummary, projectLoopSummary, projectWorkflowFocus, projectWorkflowSummary, reviewGeneratedJobCode } from './agent-harness.mjs';
 import '@automerge/automerge';
 import '@automerge/automerge/slim';
@@ -34,12 +34,14 @@ interface JobPresentation {
     lists: SessionHeapList[];
     changedEntries: SessionHeapEntry[];
     changedLists: SessionHeapList[];
+    hasExplicitArtifacts: boolean;
 }
-declare function resolveJobPresentation({ jobId, result, stdout, sessionHeap, }: {
+declare function resolveJobPresentation({ jobId, result, stdout, sessionHeap, allowExplicitArtifacts, }: {
     jobId: string;
     result: unknown;
     stdout?: string[];
     sessionHeap: SessionHeapSnapshot;
+    allowExplicitArtifacts?: boolean;
 }): JobPresentation;
 
 declare function normalizePromptText(value: string): string;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { E as EndpointMode, T as ToolWithHandler, a as EffectHandlerContext, M as ManifestEffectMetamodelSpec, R as ResolvedEffectBehaviors, S as SessionHeapEntry, b as SessionHeapList, c as SessionHeapSnapshot, P as Prompt } from './client-CQFKsCTd.js';
-export { b1 as APIError, A as AccessTokenProvider, u as Assignment, v as AssignmentListResponse, K as Build, N as BuildListResponse, B as BuildPolicy, J as BuildStatus, C as ConnectOptions, m as ConversationSessionInfo, y as CreateEnvironmentData, s as CreatePermissionProfileData, o as CreateSandboxData, aw as DefineRelationshipOptions, b2 as DeleteResponse, D as DomainState, a8 as EffectHandler, a5 as EffectInfo, a0 as EffectInvocationMetadata, $ as EffectInvocationMode, a1 as EffectSchema, a2 as EffectWithHandler, a7 as EffectsChangedEvent, d as Environment, x as EnvironmentData, z as EnvironmentListResponse, aG as EnvironmentRecordImportSummary, G as Granular, j as GranularAuth, i as GranularOptions, b0 as GraphQLResult, a9 as InstanceEffectHandler, I as InstanceToolHandler, ah as Job, ae as JobFeedbackInput, ad as JobFeedbackMetadata, af as JobFeedbackRecord, ab as JobFeedbackSentiment, ac as JobFeedbackToolCall, aa as JobStatus, ag as JobSubmitResult, F as Manifest, aS as ManifestApprovalRequiredSpec, a$ as ManifestContent, aQ as ManifestDryRunSpec, aV as ManifestEffectDeclaration, aU as ManifestEffectSchema, aJ as ManifestEnumRuleSpec, aX as ManifestEventStreamDef, aW as ManifestEventTypeDef, aK as ManifestFilterBySpec, aZ as ManifestImport, H as ManifestListResponse, aY as ManifestOperation, aP as ManifestPostConditionSpec, aH as ManifestPropertySpec, aT as ManifestRelationshipDef, aR as ManifestReverseSpec, aO as ManifestStateMachineSpec, aM as ManifestStateMachineStateSpec, aN as ManifestStateMachineTransitionSpec, aI as ManifestValidationOperator, aL as ManifestValidationRuleSpec, a_ as ManifestVolume, au as ModelRef, r as PermissionProfile, t as PermissionProfileListResponse, q as PermissionRules, a3 as PublishEffectsResult, g as PublishToolsResult, ao as RPCRequest, ar as RPCRequestFromServer, ap as RPCResponse, aF as RecordImport, aE as RecordImportItem, aC as RecordImportItemStatus, aD as RecordImportStats, aB as RecordImportStatus, ax as RecordObjectOptions, ay as RecordObjectResult, az as RecordObjectsChunkInfo, aA as RecordObjectsOptions, k as RecordUserOptions, av as RelationshipInfo, _ as ResolvedEffectApprovalRequired, Y as ResolvedEffectDryRun, X as ResolvedEffectPostCondition, Z as ResolvedEffectReverse, n as Sandbox, p as SandboxListResponse, Q as SemanticVersionDiff, O as SemanticVersionDiffEntry, e as Session, ai as SessionHeapFieldType, aj as SessionHeapFieldValue, ak as SessionHeapVariable, b3 as StreamEvent, b5 as StreamStats, b4 as StreamSubscription, l as Subject, aq as SyncMessage, h as ToolHandler, a4 as ToolInfo, as as ToolInvokeParams, at as ToolResultParams, f as ToolSchema, a6 as ToolsChangedEvent, U as User, L as Version, w as VersionTag, V as VersionTracking, W as WSClient, an as WSClientOptions, al as WSDisconnectInfo, am as WSReconnectErrorInfo } from './client-CQFKsCTd.js';
+import { E as EndpointMode, T as ToolWithHandler, a as EffectHandlerContext, M as ManifestEffectMetamodelSpec, R as ResolvedEffectBehaviors, S as SessionHeapEntry, b as SessionHeapList, c as SessionHeapSnapshot, P as Prompt } from './client-BeKRGMoT.js';
+export { b1 as APIError, A as AccessTokenProvider, u as Assignment, v as AssignmentListResponse, K as Build, N as BuildListResponse, B as BuildPolicy, J as BuildStatus, C as ConnectOptions, m as ConversationSessionInfo, y as CreateEnvironmentData, s as CreatePermissionProfileData, o as CreateSandboxData, aw as DefineRelationshipOptions, b2 as DeleteResponse, D as DomainState, a8 as EffectHandler, a5 as EffectInfo, a0 as EffectInvocationMetadata, $ as EffectInvocationMode, a1 as EffectSchema, a2 as EffectWithHandler, a7 as EffectsChangedEvent, d as Environment, x as EnvironmentData, z as EnvironmentListResponse, aG as EnvironmentRecordImportSummary, G as Granular, j as GranularAuth, i as GranularOptions, b0 as GraphQLResult, a9 as InstanceEffectHandler, I as InstanceToolHandler, ah as Job, ae as JobFeedbackInput, ad as JobFeedbackMetadata, af as JobFeedbackRecord, ab as JobFeedbackSentiment, ac as JobFeedbackToolCall, aa as JobStatus, ag as JobSubmitResult, F as Manifest, aS as ManifestApprovalRequiredSpec, a$ as ManifestContent, aQ as ManifestDryRunSpec, aV as ManifestEffectDeclaration, aU as ManifestEffectSchema, aJ as ManifestEnumRuleSpec, aX as ManifestEventStreamDef, aW as ManifestEventTypeDef, aK as ManifestFilterBySpec, aZ as ManifestImport, H as ManifestListResponse, aY as ManifestOperation, aP as ManifestPostConditionSpec, aH as ManifestPropertySpec, aT as ManifestRelationshipDef, aR as ManifestReverseSpec, aO as ManifestStateMachineSpec, aM as ManifestStateMachineStateSpec, aN as ManifestStateMachineTransitionSpec, aI as ManifestValidationOperator, aL as ManifestValidationRuleSpec, a_ as ManifestVolume, au as ModelRef, r as PermissionProfile, t as PermissionProfileListResponse, q as PermissionRules, a3 as PublishEffectsResult, g as PublishToolsResult, ao as RPCRequest, ar as RPCRequestFromServer, ap as RPCResponse, aF as RecordImport, aE as RecordImportItem, aC as RecordImportItemStatus, aD as RecordImportStats, aB as RecordImportStatus, ax as RecordObjectOptions, ay as RecordObjectResult, az as RecordObjectsChunkInfo, aA as RecordObjectsOptions, k as RecordUserOptions, av as RelationshipInfo, _ as ResolvedEffectApprovalRequired, Y as ResolvedEffectDryRun, X as ResolvedEffectPostCondition, Z as ResolvedEffectReverse, n as Sandbox, p as SandboxListResponse, Q as SemanticVersionDiff, O as SemanticVersionDiffEntry, e as Session, ai as SessionHeapFieldType, aj as SessionHeapFieldValue, ak as SessionHeapVariable, b3 as StreamEvent, b5 as StreamStats, b4 as StreamSubscription, l as Subject, aq as SyncMessage, h as ToolHandler, a4 as ToolInfo, as as ToolInvokeParams, at as ToolResultParams, f as ToolSchema, a6 as ToolsChangedEvent, U as User, L as Version, w as VersionTag, V as VersionTracking, W as WSClient, an as WSClientOptions, al as WSDisconnectInfo, am as WSReconnectErrorInfo } from './client-BeKRGMoT.js';
 export { BuildGranularAgentSystemPromptInput, GeneratedJobCodeIssue, GranularAgentExecutionCheckpoint, GranularAgentHeapSummaryOptions, GranularAgentSessionContext, GranularAgentToolInfo, GranularAgentWorkflowFocus, HarnessContinuationDecision, HarnessControllerBudgets, HarnessProjectionOptions, HarnessPromptLike, HarnessVerifierSnapshot, HarnessVerifierSnapshotInput, buildContinuationInstruction, buildGranularAgentCheckpointBlock, buildGranularAgentDomainBlock, buildGranularAgentHeapBlock, buildGranularAgentLoopBlock, buildGranularAgentSessionBlock, buildGranularAgentSystemPrompt, buildGranularAgentToolBlock, buildGranularAgentWorkflowBlock, createHarnessVerifierSnapshot, evaluateContinuation, getCurrentClosureId, getExclusivePromptTarget, hasOpenPrompt, projectHeapSummary, projectLoopSummary, projectWorkflowFocus, projectWorkflowSummary, reviewGeneratedJobCode } from './agent-harness.js';
 import '@automerge/automerge';
 import '@automerge/automerge/slim';
@@ -34,12 +34,14 @@ interface JobPresentation {
     lists: SessionHeapList[];
     changedEntries: SessionHeapEntry[];
     changedLists: SessionHeapList[];
+    hasExplicitArtifacts: boolean;
 }
-declare function resolveJobPresentation({ jobId, result, stdout, sessionHeap, }: {
+declare function resolveJobPresentation({ jobId, result, stdout, sessionHeap, allowExplicitArtifacts, }: {
     jobId: string;
     result: unknown;
     stdout?: string[];
     sessionHeap: SessionHeapSnapshot;
+    allowExplicitArtifacts?: boolean;
 }): JobPresentation;
 
 declare function normalizePromptText(value: string): string;

package/dist/index.js

@@ -4567,6 +4567,7 @@ var Session = class {
   client;
   clientId;
   jobsMap = /* @__PURE__ */ new Map();
+  pendingAgentMessagesByJobId = /* @__PURE__ */ new Map();
   eventListeners = /* @__PURE__ */ new Map();
   toolHandlers = /* @__PURE__ */ new Map();
   /** Tracks which tools are instance methods (className set, not static) */
@@ -4724,6 +4725,15 @@ var Session = class {
       createdAt: Date.now()
     });
     this.jobsMap.set(result.jobId, job);
+    const pendingAgentMessages = this.pendingAgentMessagesByJobId.get(
+      result.jobId
+    );
+    if (pendingAgentMessages && pendingAgentMessages.length > 0) {
+      this.pendingAgentMessagesByJobId.delete(result.jobId);
+      for (const message of pendingAgentMessages) {
+        job.replayAgentMessage(message);
+      }
+    }
     return job;
   }
   /**
@@ -5125,6 +5135,22 @@ import { ${allImports} } from "./sandbox-tools";
     this.client.on("job.status", (data) => {
       this.emit("job:status", data);
     });
+    this.client.on("job.agent_message", (data) => {
+      const normalized = normalizeJobAgentMessageEnvelope(data);
+      if (!normalized) return;
+      if (this.jobsMap.has(normalized.jobId)) return;
+      const pending = this.pendingAgentMessagesByJobId.get(normalized.jobId) || [];
+      if (normalized.message.messageId && pending.some(
+        (message) => message.messageId === normalized.message.messageId
+      )) {
+        return;
+      }
+      pending.push(normalized.message);
+      this.pendingAgentMessagesByJobId.set(
+        normalized.jobId,
+        pending.slice(-25)
+      );
+    });
     this.client.on("exec.completed", (data) => {
       this.emit("exec:completed", data);
     });
@@ -5249,6 +5275,22 @@ function sanitizeFeedbackValue(value, depth = 0, seen = /* @__PURE__ */ new Weak
   }
   return truncateFeedbackString(String(value));
 }
+function normalizeJobAgentMessageEnvelope(data) {
+  const d = data;
+  if (typeof d?.jobId !== "string" || !d.jobId) {
+    return null;
+  }
+  return {
+    jobId: d.jobId,
+    message: {
+      messageId: d.messageId,
+      kind: d.kind === "artifacts" ? "artifacts" : "text",
+      reply: typeof d.reply === "string" ? d.reply : "",
+      show: d.show,
+      timestamp: d.timestamp || Date.now()
+    }
+  };
+}
 var JobImplementation = class {
   id;
   client;
@@ -5257,6 +5299,8 @@ var JobImplementation = class {
   _resolveResult;
   _rejectResult;
   eventListeners = /* @__PURE__ */ new Map();
+  bufferedAgentMessages = [];
+  bufferedAgentMessageIds = /* @__PURE__ */ new Set();
   metadata;
   constructor(id, client, initialState) {
     this.id = id;
@@ -5415,14 +5459,9 @@ var JobImplementation = class {
       }
     });
     this.client.on("job.agent_message", (data) => {
-      const d = data;
-      if (d.jobId === id) {
-        this.emit("agentMessage", {
-          messageId: d.messageId,
-          reply: typeof d.reply === "string" ? d.reply : "",
-          show: d.show,
-          timestamp: d.timestamp || Date.now()
-        });
+      const normalized = normalizeJobAgentMessageEnvelope(data);
+      if (normalized?.jobId === id) {
+        this.captureAgentMessage(normalized.message);
       }
     });
   }
@@ -5449,6 +5488,14 @@ var JobImplementation = class {
       this.eventListeners.set(event, []);
     }
     this.eventListeners.get(event).push(handler);
+    if (event === "agentMessage" && this.bufferedAgentMessages.length > 0) {
+      for (const message of this.bufferedAgentMessages) {
+        handler(message);
+      }
+    }
+  }
+  replayAgentMessage(message) {
+    this.captureAgentMessage(message);
   }
   buildFeedbackMetadata() {
     const startedAt = this.metadata.startedAt;
@@ -5518,6 +5565,18 @@ var JobImplementation = class {
       handlers.forEach((h) => h(data));
     }
   }
+  captureAgentMessage(message) {
+    if (message.messageId && this.bufferedAgentMessageIds.has(message.messageId)) {
+      return;
+    }
+    if (message.messageId) {
+      this.bufferedAgentMessageIds.add(message.messageId);
+    }
+    this.bufferedAgentMessages = [...this.bufferedAgentMessages, message].slice(
+      -25
+    );
+    this.emit("agentMessage", message);
+  }
 };
 
 // src/endpoints.ts
@@ -13572,14 +13631,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;
@@ -14429,7 +14496,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.
@@ -14471,21 +14538,31 @@ ${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.`;
 }
 
 // src/job-presentation.ts
-var RESPONSE_KEYS = ["reply", "response", "text", "message", "summary", "answer"];
+var RESPONSE_KEYS = [
+  "reply",
+  "response",
+  "text",
+  "message",
+  "summary",
+  "answer"
+];
 var ENTRY_KEY_CANDIDATES = ["entryPath", "path"];
 var ENTRY_ARRAY_KEY_CANDIDATES = ["entryPaths", "paths"];
 var LIST_KEY_CANDIDATES = ["listName"];
@@ -14527,15 +14604,22 @@ function pushStringArray(target, value) {
   }
 }
 function collectReferencesFromRecord(record, refs) {
-  for (const key of ENTRY_KEY_CANDIDATES) pushString(refs.entryPaths, record[key]);
-  for (const key of ENTRY_ARRAY_KEY_CANDIDATES) pushStringArray(refs.entryPaths, record[key]);
-  for (const key of LIST_KEY_CANDIDATES) pushString(refs.listNames, record[key]);
-  for (const key of LIST_ARRAY_KEY_CANDIDATES) pushStringArray(refs.listNames, record[key]);
-  for (const key of VARIABLE_KEY_CANDIDATES) pushString(refs.variableNames, record[key]);
-  for (const key of VARIABLE_ARRAY_KEY_CANDIDATES) pushStringArray(refs.variableNames, record[key]);
+  for (const key of ENTRY_KEY_CANDIDATES)
+    pushString(refs.entryPaths, record[key]);
+  for (const key of ENTRY_ARRAY_KEY_CANDIDATES)
+    pushStringArray(refs.entryPaths, record[key]);
+  for (const key of LIST_KEY_CANDIDATES)
+    pushString(refs.listNames, record[key]);
+  for (const key of LIST_ARRAY_KEY_CANDIDATES)
+    pushStringArray(refs.listNames, record[key]);
+  for (const key of VARIABLE_KEY_CANDIDATES)
+    pushString(refs.variableNames, record[key]);
+  for (const key of VARIABLE_ARRAY_KEY_CANDIDATES)
+    pushStringArray(refs.variableNames, record[key]);
 }
 function scanForHeapReferences(value, heap, refs, depth = 0, seen = /* @__PURE__ */ new Set()) {
-  if (value === null || value === void 0 || depth > 4 || seen.has(value)) return;
+  if (value === null || value === void 0 || depth > 4 || seen.has(value))
+    return;
   if (typeof value === "string") {
     const trimmed = value.trim();
     if (heap.entriesByPath?.[trimmed]) refs.entryPaths.add(trimmed);
@@ -14631,12 +14715,16 @@ function fallbackResponseText(entries, lists) {
 }
 function getJobRelatedEntries(heap, jobId) {
   return sortEntries(
-    Object.values(heap.entriesByPath || {}).filter((entry) => entry.relatedJobIds?.includes(jobId))
+    Object.values(heap.entriesByPath || {}).filter(
+      (entry) => entry.relatedJobIds?.includes(jobId)
+    )
   );
 }
 function getJobRelatedLists(heap, jobId) {
   return sortLists(
-    Object.values(heap.listsByName || {}).filter((list) => list.relatedJobIds?.includes(jobId))
+    Object.values(heap.listsByName || {}).filter(
+      (list) => list.relatedJobIds?.includes(jobId)
+    )
   );
 }
 function entriesFromLists(lists, heap) {
@@ -14653,15 +14741,18 @@ function resolveJobPresentation({
   jobId,
   result,
   stdout = [],
-  sessionHeap
+  sessionHeap,
+  allowExplicitArtifacts = true
 }) {
   const refs = {
     entryPaths: /* @__PURE__ */ new Set(),
     listNames: /* @__PURE__ */ new Set(),
     variableNames: /* @__PURE__ */ new Set()
   };
-  scanForHeapReferences(result, sessionHeap, refs);
-  resolveVariablesToReferences(refs.variableNames, sessionHeap, refs);
+  if (allowExplicitArtifacts) {
+    scanForHeapReferences(result, sessionHeap, refs);
+    resolveVariablesToReferences(refs.variableNames, sessionHeap, refs);
+  }
   const referencedLists = sortLists(
     [...refs.listNames].map((name) => sessionHeap.listsByName?.[name]).filter((list) => Boolean(list))
   );
@@ -14674,20 +14765,22 @@ function resolveJobPresentation({
     ...jobEntries,
     ...entriesFromLists(jobLists, sessionHeap)
   ]);
-  const lists = dedupeLists([...referencedLists, ...jobLists]);
-  const entries = dedupeEntries([
+  const explicitLists = dedupeLists(referencedLists);
+  const explicitEntries = dedupeEntries([
     ...referencedEntries,
-    ...entriesFromLists(referencedLists, sessionHeap),
-    ...jobEntries,
-    ...entriesFromLists(jobLists, sessionHeap)
+    ...entriesFromLists(referencedLists, sessionHeap)
   ]);
+  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);
   return {
     responseText,
     entries,
     lists,
     changedEntries,
-    changedLists: jobLists
+    changedLists: jobLists,
+    hasExplicitArtifacts
   };
 }