The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix(adapters): inject execution contract once per fresh heartbeat (#9469)
Dottac8253e36412a
diff --git a/packages/adapter-utils/src/server-utils.test.ts b/packages/adapter-utils/src/server-utils.test.tsindex 7c7071030b..0b59b30919 100644--- a/packages/adapter-utils/src/server-utils.test.ts+++ b/packages/adapter-utils/src/server-utils.test.ts@@ -727,7 +727,7 @@ describe("renderPaperclipWakePrompt", () => {);});- it("adds the execution contract to scoped wake prompts", () => {+ it("leaves the execution contract to the heartbeat template on fresh scoped wake prompts", () => {const prompt = renderPaperclipWakePrompt({reason: "issue_assigned",issue: {@@ -746,11 +746,101 @@ describe("renderPaperclipWakePrompt", () => {});expect(prompt).toContain("## Paperclip Wake Payload");- expect(prompt).toContain("Execution contract: take concrete action in this heartbeat");- expect(prompt).toContain("clear final disposition");- expect(prompt).toContain("evidence, not valid liveness paths by themselves");- expect(prompt).toContain("Use child issues for long or parallel delegated work instead of polling");- expect(prompt).toContain("named unblock owner/action");+ expect(prompt).not.toContain("Execution contract:");+ expect(DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE).toContain("Execution contract:");+ });++ it("adds the execution contract to resume delta prompts and opted-in fresh prompts", () => {+ const payload = {+ reason: "issue_assigned",+ issue: {+ id: "issue-1",+ identifier: "PAP-1580",+ title: "Update prompts",+ status: "in_progress",+ },+ commentWindow: {+ requestedCount: 0,+ includedCount: 0,+ missingCount: 0,+ },+ comments: [],+ fallbackFetchNeeded: false,+ };++ for (const prompt of [+ renderPaperclipWakePrompt(payload, { resumedSession: true }),+ renderPaperclipWakePrompt(payload, { includeExecutionContract: true }),+ ]) {+ expect(prompt).toContain("Execution contract: take concrete action in this heartbeat");+ expect(prompt).toContain("clear final disposition");+ expect(prompt).toContain("evidence, not valid liveness paths by themselves");+ expect(prompt).toContain("Use child issues for long or parallel delegated work instead of polling");+ expect(prompt).toContain("named unblock owner/action");+ }+ });++ it("keeps exactly one execution contract in a composed fresh heartbeat prompt", () => {+ const wakePrompt = renderPaperclipWakePrompt({+ reason: "issue_assigned",+ issue: {+ id: "issue-1",+ identifier: "PAP-1580",+ title: "Update prompts",+ status: "in_progress",+ },+ commentWindow: {+ requestedCount: 0,+ includedCount: 0,+ missingCount: 0,+ },+ comments: [],+ fallbackFetchNeeded: false,+ });+ const composed = [wakePrompt, DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE].join("\n\n");+ expect(composed.match(/Execution contract/g)).toHaveLength(1);+ });++ it("trims comment-batch boilerplate on fresh wakes with zero pending comments", () => {+ const base = {+ reason: "issue_assigned",+ issue: {+ id: "issue-1",+ identifier: "PAP-1580",+ title: "Update prompts",+ status: "in_progress",+ },+ commentWindow: {+ requestedCount: 0,+ includedCount: 0,+ missingCount: 0,+ },+ comments: [],+ fallbackFetchNeeded: false,+ };++ const zeroCommentPrompt = renderPaperclipWakePrompt(base);+ expect(zeroCommentPrompt).not.toContain("acknowledge the latest comment");+ expect(zeroCommentPrompt).not.toContain("Only fetch the API thread");+ expect(zeroCommentPrompt).not.toContain("- pending comments:");+ expect(zeroCommentPrompt).not.toContain("- latest comment id:");+ expect(zeroCommentPrompt).toContain("- fallback fetch needed: no");++ const commentPrompt = renderPaperclipWakePrompt({+ ...base,+ reason: "issue_commented",+ commentWindow: { requestedCount: 1, includedCount: 1, missingCount: 0 },+ comments: [{ id: "comment-1", body: "Please fix", authorType: "user" }],+ latestCommentId: "comment-1",+ });+ expect(commentPrompt).toContain("acknowledge the latest comment");+ expect(commentPrompt).toContain("Only fetch the API thread");+ expect(commentPrompt).toContain("- pending comments: 1/1");+ expect(commentPrompt).toContain("- latest comment id: comment-1");++ const fallbackPrompt = renderPaperclipWakePrompt({ ...base, fallbackFetchNeeded: true });+ expect(fallbackPrompt).toContain("Only fetch the API thread");+ expect(fallbackPrompt).toContain("- fallback fetch needed: yes");});it("renders the execution workspace branch guard only on non-resumed sessions", () => {diff --git a/packages/adapter-utils/src/server-utils.ts b/packages/adapter-utils/src/server-utils.tsindex 5a4c1e04cf..5c5a9c5ee7 100644--- a/packages/adapter-utils/src/server-utils.ts+++ b/packages/adapter-utils/src/server-utils.ts@@ -1263,11 +1263,17 @@ export function readPaperclipIssueWorkModeFromContext(value: unknown): string |export function renderPaperclipWakePrompt(value: unknown,- options: { resumedSession?: boolean } = {},+ options: { resumedSession?: boolean; includeExecutionContract?: boolean } = {},): string {const normalized = normalizePaperclipWakePayload(value);if (!normalized) return "";const resumedSession = options.resumedSession === true;+ // The heartbeat prompt template already carries the execution contract on+ // fresh sessions; only resume deltas (which replace the template) and+ // template-less adapters need the wake-payload copy.+ const includeExecutionContract = resumedSession || options.includeExecutionContract === true;+ const hasWakeCommentBatch =+ normalized.comments.length > 0 || normalized.includedCount > 0 || normalized.requestedCount > 0;const executionStage = normalized.executionStage;const principalLabel = (principal: PaperclipWakeExecutionPrincipal | null) => {if (!principal || !principal.type) return "unknown";@@ -1294,6 +1300,23 @@ export function renderPaperclipWakePrompt(}};+ const executionContractLines = includeExecutionContract+ ? [+ "Execution contract: take concrete action in this heartbeat when the issue is actionable; do not stop at a plan unless planning was requested. Leave durable progress and then give the issue a clear final disposition before ending the heartbeat: `done`, `in_review` with a real reviewer/approval/interaction path, `blocked` with first-class blockers or a named unblock owner/action, delegated follow-up issues with blockers, or `in_progress` only when a live continuation path exists. Use child issues for long or parallel delegated work instead of polling. Comments, documents, screenshots, work products, and `Remaining` bullets are evidence, not valid liveness paths by themselves.",+ "",+ ]+ : [];+ const wakeSummaryLines = [+ `- reason: ${normalized.reason ?? "unknown"}`,+ `- issue: ${normalized.issue?.identifier ?? normalized.issue?.id ?? "unknown"}${normalized.issue?.title ? ` ${normalized.issue.title}` : ""}`,+ ...(hasWakeCommentBatch+ ? [+ `- pending comments: ${normalized.includedCount}/${normalized.requestedCount}`,+ `- latest comment id: ${normalized.latestCommentId ?? "unknown"}`,+ ]+ : []),+ `- fallback fetch needed: ${normalized.fallbackFetchNeeded ? "yes" : "no"}`,+ ];const lines = resumedSession? ["## Paperclip Resume Delta",@@ -1303,30 +1326,24 @@ export function renderPaperclipWakePrompt("Focus on the new wake delta below and continue the current task without restating the full heartbeat boilerplate.","Fetch the API thread only when `fallbackFetchNeeded` is true or you need broader history than this batch.","",- "Execution contract: take concrete action in this heartbeat when the issue is actionable; do not stop at a plan unless planning was requested. Leave durable progress and then give the issue a clear final disposition before ending the heartbeat: `done`, `in_review` with a real reviewer/approval/interaction path, `blocked` with first-class blockers or a named unblock owner/action, delegated follow-up issues with blockers, or `in_progress` only when a live continuation path exists. Use child issues for long or parallel delegated work instead of polling. Comments, documents, screenshots, work products, and `Remaining` bullets are evidence, not valid liveness paths by themselves.",- "",- `- reason: ${normalized.reason ?? "unknown"}`,- `- issue: ${normalized.issue?.identifier ?? normalized.issue?.id ?? "unknown"}${normalized.issue?.title ? ` ${normalized.issue.title}` : ""}`,- `- pending comments: ${normalized.includedCount}/${normalized.requestedCount}`,- `- latest comment id: ${normalized.latestCommentId ?? "unknown"}`,- `- fallback fetch needed: ${normalized.fallbackFetchNeeded ? "yes" : "no"}`,+ ...executionContractLines,+ ...wakeSummaryLines,]: ["## Paperclip Wake Payload","","Treat this wake payload as the highest-priority change for the current heartbeat.","This heartbeat is scoped to the issue below. Do not switch to another issue until you have handled this wake.",- "Before generic repo exploration or boilerplate heartbeat updates, acknowledge the latest comment and explain how it changes your next action.",+ ...(hasWakeCommentBatch+ ? ["Before generic repo exploration or boilerplate heartbeat updates, acknowledge the latest comment and explain how it changes your next action."]+ : []),"Use this inline wake data first before refetching the issue thread.",- "Only fetch the API thread when `fallbackFetchNeeded` is true or you need broader history than this batch.",- "",- "Execution contract: take concrete action in this heartbeat when the issue is actionable; do not stop at a plan unless planning was requested. Leave durable progress and then give the issue a clear final disposition before ending the heartbeat: `done`, `in_review` with a real reviewer/approval/interaction path, `blocked` with first-class blockers or a named unblock owner/action, delegated follow-up issues with blockers, or `in_progress` only when a live continuation path exists. Use child issues for long or parallel delegated work instead of polling. Comments, documents, screenshots, work products, and `Remaining` bullets are evidence, not valid liveness paths by themselves.",+ ...(hasWakeCommentBatch || normalized.fallbackFetchNeeded+ ? ["Only fetch the API thread when `fallbackFetchNeeded` is true or you need broader history than this batch."]+ : []),"",- `- reason: ${normalized.reason ?? "unknown"}`,- `- issue: ${normalized.issue?.identifier ?? normalized.issue?.id ?? "unknown"}${normalized.issue?.title ? ` ${normalized.issue.title}` : ""}`,- `- pending comments: ${normalized.includedCount}/${normalized.requestedCount}`,- `- latest comment id: ${normalized.latestCommentId ?? "unknown"}`,- `- fallback fetch needed: ${normalized.fallbackFetchNeeded ? "yes" : "no"}`,+ ...executionContractLines,+ ...wakeSummaryLines,];if (normalized.issue?.status) {diff --git a/packages/adapters/openclaw-gateway/src/server/execute.ts b/packages/adapters/openclaw-gateway/src/server/execute.tsindex 91bef0081e..ab84aa7de0 100644--- a/packages/adapters/openclaw-gateway/src/server/execute.ts+++ b/packages/adapters/openclaw-gateway/src/server/execute.ts@@ -1084,7 +1084,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecconst wakePayload = buildWakePayload(ctx);const paperclipEnv = buildPaperclipEnvForWake(ctx, wakePayload);- const structuredWakePrompt = renderPaperclipWakePrompt(ctx.context.paperclipWake);+ // No heartbeat prompt template is sent over the gateway, so the wake prompt+ // must carry the execution contract itself.+ const structuredWakePrompt = renderPaperclipWakePrompt(ctx.context.paperclipWake, {+ includeExecutionContract: true,+ });const structuredWakeJson = stringifyPaperclipWakePayload(ctx.context.paperclipWake);const wakeText = buildWakeText(wakePayload,diff --git a/server/src/__tests__/codex-local-execute.test.ts b/server/src/__tests__/codex-local-execute.test.tsindex 3281834470..cdadb2f45c 100644--- a/server/src/__tests__/codex-local-execute.test.ts+++ b/server/src/__tests__/codex-local-execute.test.ts@@ -959,7 +959,9 @@ describe("codex execute", () => {expect(capture.prompt).toContain("## Paperclip Wake Payload");expect(capture.prompt).toContain("Do not switch to another issue until you have handled this wake.");expect(capture.prompt).toContain("- issue: PAP-1201 Fix gallery opening for inline images");- expect(capture.prompt).toContain("- pending comments: 0/0");+ expect(capture.prompt).not.toContain("- pending comments:");+ expect(capture.prompt).not.toContain("acknowledge the latest comment");+ expect(capture.prompt).not.toContain("Execution contract:");expect(capture.prompt).toContain("- issue status: in_progress");expect(capture.prompt).toContain("- checkout: already claimed by the harness for this run");expect(capture.prompt).toContain("The harness already checked out this issue for the current run.");