Stabilize A2A prompt cache metadata

sunjae-1 · sunjae-1 · commit 244289a2bf63 · 2026-06-11T00:26:10.000+09:00
A2A session routing identifiers are needed for delivery provenance, but concrete session keys in extraSystemPrompt make the agent system prompt vary between otherwise identical handoffs. Keep the model-facing system context stable by describing high-cardinality session slots with placeholders while retaining concrete values in inputProvenance. Channel names stay concrete: they are low-cardinality (discord/slack/webchat/...), so they do not meaningfully fragment the cache, and they inform reply formatting on the receiving agent.

Constraint: OpenClaw contributor PRs require focused behavior proof and tests for prompt/cache-facing changes.

Rejected: Removing routing metadata entirely | would weaken model context for requester/target roles.

Rejected: Placeholdering channel values too | drops model-visible formatting context for negligible cache benefit (reviewer feedback).

Confidence: medium

Scope-risk: narrow

Directive: Keep concrete session identifiers out of extraSystemPrompt; preserve them in structured provenance or payload fields. Low-cardinality channel labels may stay model-visible.

Tested: node scripts/run-vitest.mjs src/agents/tools/sessions-send-helpers.test.ts src/agents/openclaw-tools.sessions.test.ts

Tested: corepack pnpm exec oxfmt --check src/agents/tools/sessions-send-helpers.ts src/agents/tools/sessions-send-helpers.test.ts src/agents/openclaw-tools.sessions.test.ts

Tested: node scripts/run-oxlint.mjs src/agents/tools/sessions-send-helpers.ts src/agents/tools/sessions-send-helpers.test.ts src/agents/openclaw-tools.sessions.test.ts

Tested: git diff --check

Tested: live before/after provider cache trace (isolated local gateway, two A2A sends from distinct requester sessions; see PR Real behavior proof)
diff --git a/src/agents/openclaw-tools.sessions.test.ts b/src/agents/openclaw-tools.sessions.test.ts
@@ -185,6 +185,8 @@ type AgentCallParams = {
   inputProvenance?: {
     kind?: string;
     sourceSessionKey?: string;
+    sourceChannel?: string;
+    sourceTool?: string;
   };
 };
 
@@ -1118,6 +1120,24 @@ describe("sessions tools", () => {
           ),
       ),
     ).toBe(true);
+    const initialAgentCall = agentCalls.find((call) =>
+      agentParams(call).extraSystemPrompt?.includes("Agent-to-agent message context"),
+    );
+    const initialAgentParams = agentParams(initialAgentCall ?? {});
+    expect(initialAgentParams.extraSystemPrompt).toContain(
+      "Agent 1 (requester) session: <REQUESTER_SESSION>.",
+    );
+    expect(initialAgentParams.extraSystemPrompt).toContain("Agent 1 (requester) channel: discord.");
+    expect(initialAgentParams.extraSystemPrompt).toContain(
+      "Agent 2 (target) session: <TARGET_SESSION>.",
+    );
+    expect(initialAgentParams.extraSystemPrompt).not.toContain(requesterKey);
+    expect(initialAgentParams.inputProvenance).toMatchObject({
+      kind: "inter_session",
+      sourceSessionKey: requesterKey,
+      sourceChannel: "discord",
+      sourceTool: "sessions_send",
+    });
     expect(
       agentCalls.some(
         (call) =>
diff --git a/src/agents/tools/sessions-send-helpers.test.ts b/src/agents/tools/sessions-send-helpers.test.ts
@@ -1,7 +1,12 @@
 import { beforeEach, describe, expect, it } from "vitest";
 import { setActivePluginRegistry } from "../../plugins/runtime.js";
 import { createSessionConversationTestRegistry } from "../../test-utils/session-conversation-registry.js";
-import { resolveAnnounceTargetFromKey, resolvePingPongTurns } from "./sessions-send-helpers.js";
+import {
+  buildAgentToAgentMessageContext,
+  buildAgentToAgentReplyContext,
+  resolveAnnounceTargetFromKey,
+  resolvePingPongTurns,
+} from "./sessions-send-helpers.js";
 
 describe("resolveAnnounceTargetFromKey", () => {
   beforeEach(() => {
@@ -88,3 +93,38 @@ describe("resolvePingPongTurns", () => {
     ).toBe(20);
   });
 });
+
+describe("agent-to-agent prompt context", () => {
+  it("keeps volatile routing identifiers out of system prompt context", () => {
+    const context = buildAgentToAgentMessageContext({
+      requesterSessionKey: "agent:main:slack:channel:C123:thread:171.222",
+      requesterChannel: "slack",
+      targetSessionKey: "agent:worker:discord:channel:ops:run:run-123",
+    });
+
+    expect(context).toContain("Agent 1 (requester) session: <REQUESTER_SESSION>.");
+    expect(context).toContain("Agent 1 (requester) channel: slack.");
+    expect(context).toContain("Agent 2 (target) session: <TARGET_SESSION>.");
+    expect(context).not.toContain("agent:main:slack:channel:C123:thread:171.222");
+    expect(context).not.toContain("agent:worker:discord:channel:ops:run:run-123");
+  });
+
+  it("preserves optional session line shape with concrete channel values", () => {
+    const context = buildAgentToAgentReplyContext({
+      requesterSessionKey: "agent:requester:main",
+      targetSessionKey: "agent:target:main",
+      targetChannel: "telegram",
+      currentRole: "target",
+      turn: 2,
+      maxTurns: 5,
+    });
+
+    expect(context).toContain("Current agent: Agent 2 (target).");
+    expect(context).toContain("Agent 1 (requester) session: <REQUESTER_SESSION>.");
+    expect(context).not.toContain("Agent 1 (requester) channel:");
+    expect(context).toContain("Agent 2 (target) session: <TARGET_SESSION>.");
+    expect(context).toContain("Agent 2 (target) channel: telegram.");
+    expect(context).not.toContain("agent:requester:main");
+    expect(context).not.toContain("agent:target:main");
+  });
+});
diff --git a/src/agents/tools/sessions-send-helpers.ts b/src/agents/tools/sessions-send-helpers.ts
@@ -54,13 +54,14 @@ function buildAgentSessionLines(params: {
   targetChannel?: string;
 }): string[] {
   return [
-    params.requesterSessionKey
-      ? `Agent 1 (requester) session: ${params.requesterSessionKey}.`
-      : undefined,
+    // Session keys are high-cardinality (thread/run ids), so concrete values churn the
+    // system prompt and break provider prompt-cache reuse across A2A turns. Channels are
+    // low-cardinality and inform reply formatting, so they stay concrete.
+    params.requesterSessionKey ? "Agent 1 (requester) session: <REQUESTER_SESSION>." : undefined,
     params.requesterChannel
       ? `Agent 1 (requester) channel: ${params.requesterChannel}.`
       : undefined,
-    `Agent 2 (target) session: ${params.targetSessionKey}.`,
+    "Agent 2 (target) session: <TARGET_SESSION>.",
     params.targetChannel ? `Agent 2 (target) channel: ${params.targetChannel}.` : undefined,
   ].filter((line): line is string => Boolean(line));
 }
