fix(agents): prefer sessionKey in sessions_send

openclaw-clownfish[bot] · vincentkoc · commit 115455ea2224 · 2026-04-28T23:06:57.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -19,6 +19,7 @@ Docs: https://docs.openclaw.ai
 - Plugin SDK: add tracked Discord component-message helpers and a Telegram account-resolution compatibility facade, so existing plugins using those subpaths resolve while new plugins stay on generic channel SDK contracts. Thanks @vincentkoc.
 - Shared labels: preserve Unicode combining marks and NFC-equivalent accented text in group/channel slug normalization so non-Latin labels no longer lose meaningful characters. Fixes #58932; carries forward #58942 and #58995. Thanks @fengqing-git, @Starhappysh, and @koen666.
 - Docs/Hetzner: clarify that SSH tunnel access requires `AllowTcpForwarding local` before running `ssh -L`, so hardened VPS sshd configs do not block loopback Gateway access. Fixes #54557; carries forward #54564; refs #54954. Thanks @satishkc7, @blackstrype, and @Aftabbs.
+- Agents/sessions: make `sessions_send` prefer explicit `sessionKey` inputs, including session id values, over redundant `label`/`agentId` hints so sends no longer reject when callers include stale label metadata. Fixes #64699; refs #41199; carries forward #59324 and supersedes #56203. Thanks @Mintalix and @RevisitMoon.
 - Gateway/shutdown: report structured shutdown warnings and HTTP close timeout warnings through `ShutdownResult` while preserving lifecycle hook hardening. Carries forward #41296. Thanks @edenfunf.
 - Plugins/QA: prebuild the private QA channel runtime before plugin gauntlet source runs so wrapper CPU/RSS measurements are not polluted by private QA dist rebuild work. Thanks @vincentkoc.
 - Gateway/reload: bound default restart deferral and SIGUSR1 restart drain to five minutes while preserving explicit `deferralTimeoutMs: 0` indefinite waits, so stale active work accounting cannot block config reloads forever. Thanks @vincentkoc.
diff --git a/src/agents/tool-description-presets.ts b/src/agents/tool-description-presets.ts
@@ -27,7 +27,7 @@ export function describeSessionsHistoryTool(): string {
 
 export function describeSessionsSendTool(): string {
   return [
-    "Send a message into another visible session by sessionKey or label.",
+    "Send a message into another visible session by sessionKey or label; sessionKey accepts a full session key or session id and takes precedence over label/agentId when both are present.",
     "Use this to delegate follow-up work to an existing session; waits for the target run and returns the updated assistant reply when available.",
   ].join(" ");
 }
diff --git a/src/agents/tools/sessions-send-tool.ts b/src/agents/tools/sessions-send-tool.ts
@@ -106,13 +106,6 @@ export function createSessionsSendTool(opts?: {
       const sessionKeyParam = readStringParam(params, "sessionKey");
       const labelParam = normalizeOptionalString(readStringParam(params, "label"));
       const labelAgentIdParam = normalizeOptionalString(readStringParam(params, "agentId"));
-      if (sessionKeyParam && labelParam) {
-        return jsonResult({
-          runId: crypto.randomUUID(),
-          status: "error",
-          error: "Provide either sessionKey or label (not both).",
-        });
-      }
 
       let sessionKey = sessionKeyParam;
       if (!sessionKey && labelParam) {
diff --git a/src/agents/tools/sessions.test.ts b/src/agents/tools/sessions.test.ts
@@ -644,6 +644,97 @@ describe("sessions_send gating", () => {
     expect(callGatewayMock.mock.calls[0]?.[0]).toMatchObject({ method: "sessions.resolve" });
   });
 
+  it("prefers sessionKey over a redundant label", async () => {
+    const tool = createMainSessionsSendTool();
+
+    const result = await tool.execute("call-session-key-label", {
+      sessionKey: MAIN_AGENT_SESSION_KEY,
+      label: "stale-label",
+      message: "hi",
+      timeoutSeconds: 0,
+    });
+
+    expect(result.details).toMatchObject({
+      status: "accepted",
+      sessionKey: MAIN_AGENT_SESSION_KEY,
+    });
+    expect(callGatewayMock).toHaveBeenCalledTimes(2);
+    expect(callGatewayMock.mock.calls[0]?.[0]).toMatchObject({ method: "sessions.list" });
+    expect(callGatewayMock.mock.calls[1]?.[0]).toMatchObject({
+      method: "agent",
+      params: {
+        sessionKey: MAIN_AGENT_SESSION_KEY,
+      },
+    });
+    expect(callGatewayMock.mock.calls).not.toContainEqual([
+      expect.objectContaining({
+        method: "sessions.resolve",
+        params: expect.objectContaining({ label: "stale-label" }),
+      }),
+    ]);
+  });
+
+  it("prefers a sessionId-shaped sessionKey over redundant label and agentId hints", async () => {
+    loadConfigMock.mockReturnValue({
+      session: { scope: "per-sender", mainKey: "main" },
+      tools: {
+        agentToAgent: { enabled: false },
+        sessions: { visibility: "all" },
+      },
+    });
+    const sessionId = "11111111-1111-4111-8111-111111111111";
+    const resolvedSessionKey = "agent:main:subagent:worker";
+    callGatewayMock.mockImplementation(async (opts: unknown) => {
+      const request = opts as { method?: string; params?: Record<string, unknown> };
+      if (request.method === "sessions.resolve" && request.params?.sessionId === sessionId) {
+        return { key: resolvedSessionKey };
+      }
+      if (request.method === "agent") {
+        return { runId: "run-session-id-send" };
+      }
+      return {};
+    });
+    const tool = createMainSessionsSendTool();
+
+    const result = await tool.execute("call-session-id-label-agent", {
+      sessionKey: sessionId,
+      label: "stale-label",
+      agentId: "other",
+      message: "hi",
+      timeoutSeconds: 0,
+    });
+
+    expect(result.details).toMatchObject({
+      status: "accepted",
+      sessionKey: resolvedSessionKey,
+    });
+    expect(callGatewayMock).toHaveBeenCalledTimes(3);
+    expect(callGatewayMock.mock.calls[0]?.[0]).toMatchObject({
+      method: "sessions.resolve",
+      params: { key: sessionId },
+    });
+    expect(callGatewayMock.mock.calls[1]?.[0]).toMatchObject({
+      method: "sessions.resolve",
+      params: {
+        sessionId,
+        includeGlobal: true,
+        includeUnknown: true,
+      },
+    });
+    expect(callGatewayMock.mock.calls[2]?.[0]).toMatchObject({
+      method: "agent",
+      params: {
+        sessionKey: resolvedSessionKey,
+      },
+    });
+    expect(callGatewayMock.mock.calls).not.toContainEqual([
+      expect.objectContaining({
+        method: "sessions.resolve",
+        params: expect.objectContaining({ label: "stale-label" }),
+      }),
+    ]);
+  });
+
   it("blocks cross-agent sends when tools.agentToAgent.enabled is false", async () => {
     const tool = createMainSessionsSendTool();
 

Original file line number	Diff line number	Diff line change
`@@ -27,7 +27,7 @@ export function describeSessionsHistoryTool(): string {`
`27`	`27`
`28`	`28`	`export function describeSessionsSendTool(): string {`
`29`	`29`	`return [`
`30`		`- "Send a message into another visible session by sessionKey or label.",`
	`30`	`+ "Send a message into another visible session by sessionKey or label; sessionKey accepts a full session key or session id and takes precedence over label/agentId when both are present.",`
`31`	`31`	`"Use this to delegate follow-up work to an existing session; waits for the target run and returns the updated assistant reply when available.",`
`32`	`32`	`].join(" ");`
`33`	`33`	`}`