fix(agents): preserve heartbeat hook ordering

vincentkoc · vincentkoc · commit 98c7ac090b24 · 2026-06-24T11:54:42.000+08:00
diff --git a/src/agents/harness/prompt-compaction-hook-helpers.test.ts b/src/agents/harness/prompt-compaction-hook-helpers.test.ts
@@ -90,6 +90,47 @@ describe("resolveAgentHarnessBeforePromptBuildResult", () => {
     expect(result.developerInstructions).toBe("base instructions");
   });
 
+  it("runs heartbeat contributions before other prompt-build hooks", async () => {
+    const calls: string[] = [];
+    initializeGlobalHookRunner(
+      createMockPluginRegistry([
+        {
+          hookName: "heartbeat_prompt_contribution",
+          handler: () => {
+            calls.push("heartbeat");
+            return { prependContext: "heartbeat context" };
+          },
+        },
+        {
+          hookName: "before_prompt_build",
+          handler: () => {
+            calls.push("before_prompt_build");
+            return { prependContext: "prompt context" };
+          },
+        },
+        {
+          hookName: "before_agent_start",
+          handler: () => {
+            calls.push("before_agent_start");
+            return { prependContext: "agent-start context" };
+          },
+        },
+      ]),
+    );
+
+    const result = await resolveAgentHarnessBeforePromptBuildResult({
+      prompt: "hello",
+      developerInstructions: "base instructions",
+      messages: [],
+      ctx: { trigger: "heartbeat", agentId: "agent-1", sessionKey: "session-1" },
+    });
+
+    expect(calls).toEqual(["heartbeat", "before_prompt_build", "before_agent_start"]);
+    expect(result.prompt).toBe(
+      "heartbeat context\n\nprompt context\n\nagent-start context\n\nhello",
+    );
+  });
+
   it("skips heartbeat_prompt_contribution off a heartbeat turn", async () => {
     const handler = vi.fn(() => ({ prependContext: "should not appear" }));
     initializeGlobalHookRunner(
diff --git a/src/agents/harness/prompt-compaction-hook-helpers.ts b/src/agents/harness/prompt-compaction-hook-helpers.ts
@@ -60,6 +60,25 @@ export async function resolveAgentHarnessBeforePromptBuildResult(params: {
     messages: params.messages,
   };
 
+  // Match the embedded runner's lifecycle order: heartbeat contributions are
+  // collected before prompt-build hooks so hook side effects stay deterministic.
+  const heartbeatResult =
+    hasHeartbeatContribution && hookRunner
+      ? await hookRunner
+          .runHeartbeatPromptContribution(
+            {
+              sessionKey: params.ctx.sessionKey,
+              agentId: params.ctx.agentId,
+              heartbeatName: "heartbeat",
+            },
+            hookCtx,
+          )
+          .catch((error: unknown) => {
+            log.warn(`heartbeat_prompt_contribution hook failed: ${String(error)}`);
+            return undefined;
+          })
+      : undefined;
+
   // Support the newer before_prompt_build hook plus the deprecated
   // before_agent_start hook during the prompt-build migration window.
   const promptBuildResult = hookRunner?.hasHooks("before_prompt_build")
@@ -81,26 +100,6 @@ export async function resolveAgentHarnessBeforePromptBuildResult(params: {
         })
       : undefined;
 
-  // heartbeat_prompt_contribution runs only on heartbeat turns. Mirrors the
-  // embedded runner (resolvePromptBuildHookResult): the contribution is merged
-  // ahead of the before_prompt_build / before_agent_start contributions.
-  const heartbeatResult =
-    hasHeartbeatContribution && hookRunner
-      ? await hookRunner
-          .runHeartbeatPromptContribution(
-            {
-              sessionKey: params.ctx.sessionKey,
-              agentId: params.ctx.agentId,
-              heartbeatName: "heartbeat",
-            },
-            hookCtx,
-          )
-          .catch((error: unknown) => {
-            log.warn(`heartbeat_prompt_contribution hook failed: ${String(error)}`);
-            return undefined;
-          })
-      : undefined;
-
   const systemPrompt = resolvePromptBuildSystemPrompt({
     developerInstructions: params.developerInstructions,
     promptBuildResult,
