fix(agents): prefer sessionKey in sessions_send by Mintalix · Pull Request #59324 · openclaw/openclaw

Mintalix · 2026-04-02T01:25:19Z

Summary

Problem: sessions_send rejected requests that included both sessionKey and label, even when the caller already had the exact target session.
Why it matters: some callers can retain a stale label while still passing the authoritative sessionKey, which caused unnecessary send failures.
What changed: when sessionKey is present, sessions_send now ignores label, sends directly to the resolved session, adds a regression test, and documents the precedence rule.
What did NOT change (scope boundary): label-only resolution behavior is unchanged, and no other session routing behavior was modified.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes Agent-to-Agent Communication Tools Have Parameter Conflicts #41199
Related #
This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

Root cause: sessions_send treated sessionKey and label as mutually exclusive in src/agents/tools/sessions-send-tool.ts, even though sessionKey is already the authoritative target.
Missing detection / guardrail: there was no regression test covering the mixed sessionKey + label input path.
Prior context (git blame, prior PR, issue, or refactor if known): Unknown.
Why this regressed now: callers can retain label metadata while already providing the exact session key.
If unknown, what was ruled out: label-only resolution behavior was left unchanged.

Regression Test Plan (if applicable)

Coverage level that should have caught this:
- Unit test
- Seam / integration test
- End-to-end test
- Existing coverage already sufficient
Target test or file: src/agents/tools/sessions.test.ts
Scenario the test should lock in: when both sessionKey and label are provided, sessions_send should accept the request, use sessionKey, and skip sessions.resolve.
Why this is the smallest reliable guardrail: the regression is entirely in parameter precedence inside the tool.
Existing test that already covers this (if any): None.
If no new test is added, why not: N/A.

User-visible / Behavior Changes

sessions_send now prefers sessionKey over label when both are present, instead of returning an error.

Diagram (if applicable)

Before:
[sessions_send(sessionKey + label)] -> [validation error]

After:
[sessions_send(sessionKey + label)] -> [use sessionKey] -> [agent request accepted]

Security Impact (required)

New permissions/capabilities? (No)
Secrets/tokens handling changed? (No)
New/changed network calls? (No)
Command/tool execution surface changed? (Yes)
Data access scope changed? (No)

If any Yes, explain risk + mitigation: this only changes precedence for an already-authoritative sessionKey; a regression test verifies the tool skips label resolution and uses the provided session directly.

Repro + Verification

Environment

OS: macOS
Runtime/container: Node 22.21.1
Model/provider: N/A
Integration/channel (if any): N/A
Relevant config (redacted): default local test config

Steps

Call sessions_send with both sessionKey and label.
Observe behavior before this change.
Re-run after this patch.

Expected

The request should use sessionKey and continue successfully.

Actual

Before: the tool returned an error for mixed sessionKey and label.
After: the tool accepts the request and skips label resolution.

Evidence

Failing test/log before + passing after

Human Verification (required)

Verified scenarios: ran pnpm test -- src/agents/tools/sessions.test.ts and confirmed the new regression test passes.
Edge cases checked: verified the mixed-input path does not call sessions.resolve.
What you did not verify: full pnpm build && pnpm check && pnpm test, and a complete codex review --base origin/main run.

Review Conversations

I replied to or resolved every bot review conversation I addressed in this PR.
I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

Backward compatible? (Yes)
Config/env changes? (No)
Migration needed? (No)

If yes, exact upgrade steps: N/A

Risks and Mitigations

Risk: callers that accidentally send both fields will now proceed instead of erroring.
Mitigation: sessionKey is treated as authoritative, the change is narrow, and regression coverage locks in the intended precedence.

greptile-apps · 2026-04-02T01:28:07Z

Greptile Summary

This PR fixes sessions_send to prefer sessionKey over label when both are supplied, rather than returning an error. The change is a one-liner in parameter resolution — labelParam is short-circuited to undefined when sessionKey is present — with no effect on any other routing or security path (visibility guard and a2a policy checks still execute). A focused regression test and a Chinese-docs note are included.

Confidence Score: 5/5

Safe to merge — the change is minimal, all downstream security guards are preserved, and a regression test locks in the new behaviour.
No P0 or P1 findings. The fix is a single conditional short-circuit; the visibility guard, a2a policy, and session-reference resolution all remain on the happy path. The regression test correctly asserts that sessions.resolve is skipped and the agent call proceeds.
No files require special attention.

_{Reviews (1): Last reviewed commit: "fix(agents): prefer sessionKey in sessio..." | Re-trigger Greptile}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fbadf07850

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copilot

Pull request overview

Fixes sessions_send parameter precedence so callers can pass a stale label alongside an authoritative sessionKey without triggering a rejection, improving robustness of agent-to-agent messaging.

Changes:

Update sessions_send runtime parameter handling to ignore label when sessionKey is provided.
Add a regression test ensuring mixed sessionKey + label inputs bypass sessions.resolve and proceed to send.
Document the precedence rule in the Chinese tools index.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
src/agents/tools/sessions-send-tool.ts	Adjusts parameter precedence: `sessionKey` wins and `label` is ignored.
src/agents/tools/sessions.test.ts	Adds regression coverage for mixed `sessionKey + label` inputs.
docs/zh-CN/tools/index.md	Documents that `sessionKey`/`sessionId` should take precedence over `label`.

….com/Mintalix/openclaw into fix/sessions-send-prefer-session-key

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

src/agents/tools/sessions-send-tool.ts:118

This change makes sessionKey take precedence by ignoring label when sessionKey is present, but the tool description string still says “Use sessionKey or label” without stating the precedence/ignore behavior. To match the new behavior (and the PR description), update the sessions_send description/docs to explicitly say that if sessionKey is provided, label/agentId are ignored (and label-based resolution only happens when sessionKey is absent).

    parameters: SessionsSendToolSchema,
    execute: async (_toolCallId, args) => {
      const params = args as Record<string, unknown>;

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

clawsweeper · 2026-04-28T02:07:16Z

Codex automated review: keeping this open.

Current main still has the reported sessions_send behavior: calls with both sessionKey and label return Provide either sessionKey or label (not both). before reaching the send path. This PR remains a viable narrow implementation candidate, and the related open PRs are not merged or clearly canonical superseders.

Best possible solution:

Keep this PR open as an implementation candidate. The best maintainer path is to land one canonical sessions_send fix that treats sessionKey as authoritative when present, ignores label and agentId only for that path, preserves the existing session visibility and A2A policy checks, updates the tool-facing description/schema, and includes the regression test asserting sessions.resolve is skipped. After that lands, close the overlapping PRs and keep any separate message tool work from #41199 tracked separately.

What I checked:

current_main_still_rejects_mixed_selectors: At current main, createSessionsSendTool reads sessionKey, label, and agentId, then immediately returns an error when sessionKeyParam && labelParam, before session reference resolution or dispatch can use the authoritative sessionKey. (src/agents/tools/sessions-send-tool.ts:105, 5828dcdb05aa)
current_tests_do_not_lock_precedence: The current sessions_send gating tests cover missing targets, failed label resolution, cross-agent gating, and stale reply handling, but there is no regression test for accepting sessionKey plus label and skipping sessions.resolve. (src/agents/tools/sessions.test.ts:607, 5828dcdb05aa)
current_tool_description_still_lacks_precedence_rule: The public tool description still says sessions_send targets by sessionKey or label; current main does not document that sessionKey wins or that label/agentId are ignored when it is present. (src/agents/tool-description-presets.ts:28, 5828dcdb05aa)
pr_diff_matches_remaining_bug: The provided PR diff removes the early mixed-parameter rejection and adds a focused regression test asserting sessionKey is preferred while sessions.resolve is not called, which directly addresses the sessions_send portion of Agent-to-Agent Communication Tools Have Parameter Conflicts #41199. (src/agents/tools/sessions-send-tool.ts:108, 2d09476a4d3e)
security_review_no_supply_chain_surface: The provided PR changes only src/agents/tools/sessions-send-tool.ts and src/agents/tools/sessions.test.ts; it does not touch workflows, package metadata, lockfiles, dependency sources, release scripts, downloaded artifacts, or secret handling. The sensitive behavior change is limited to a tool-execution path, and current main’s downstream guard path resolves the session and checks visibility/A2A policy before dispatch. (src/agents/tools/sessions-send-tool.ts:202, 5828dcdb05aa)
related_items_not_superseding: The provided context shows Agent-to-Agent Communication Tools Have Parameter Conflicts #41199 remains open with the same error/reproduction, and overlapping PRs fix: prefer sessionKey over label in sessions_send #39551, fix: prefer sessionKey over label in sessions_send instead of rejecting both #41255, and fix(sessions_send): prefer sessionKey over label when both are present (AI-assisted) #56203 are also open rather than merged. None is a shipped or maintainer-selected superseder that would justify closing this PR now.

Remaining risk / open question:

The final patch changes a tool-execution path, so review should confirm the mixed-parameter path still reaches resolveSessionReference, resolveVisibleSessionReference, and the visibility/A2A guard before dispatch.
The PR review comments about documenting sessionKey precedence and agentId being ignored when sessionKey is present should be resolved before landing.
There are multiple open overlapping PRs for the same sessions_send behavior; maintainers should choose one canonical fix, land it with regression coverage, then close the duplicates.

Codex Review notes: model gpt-5.5, reasoning high; reviewed against 5828dcdb05aa.

openclaw-clownfish · 2026-04-29T02:49:37Z

ProjectClownfish could not safely update this branch, so it opened a narrow replacement PR instead.

Replacement PR: #74009
Source PR: #59324
Contributor credit is preserved in the replacement PR body and changelog plan.

fix(agents): prefer sessionKey in sessions_send

fbadf07

Copilot AI review requested due to automatic review settings April 2, 2026 01:25

openclaw-barnacle Bot added docs Improvements or additions to documentation agents Agent runtime and tooling size: XS labels Apr 2, 2026

Copilot started reviewing on behalf of Mintalix April 2, 2026 01:25 View session

chatgpt-codex-connector Bot reviewed Apr 2, 2026

View reviewed changes

Comment thread docs/zh-CN/tools/index.md Outdated

Copilot AI reviewed Apr 2, 2026

View reviewed changes

Comment thread src/agents/tools/sessions-send-tool.ts

Comment thread src/agents/tools/sessions-send-tool.ts

Comment thread docs/zh-CN/tools/index.md Outdated

Mintalix added 2 commits April 2, 2026 09:36

docs: revert manual zh-CN sessions_send note

ad8b982

style(agents): inline sessions_send label fallback

7c575d0

openclaw-barnacle Bot removed the docs Improvements or additions to documentation label Apr 2, 2026

Merge branch 'main' into fix/sessions-send-prefer-session-key

f845b52

Mintalix requested a review from Copilot April 2, 2026 12:31

Mintalix and others added 2 commits April 2, 2026 20:31

docs(agents): document sessions_send parameter precedence

c40748b

Merge branch 'main' into fix/sessions-send-prefer-session-key

21311d9

Copilot started reviewing on behalf of Mintalix April 2, 2026 12:32 View session

Merge branch 'fix/sessions-send-prefer-session-key' of https://github…

4c44f86

….com/Mintalix/openclaw into fix/sessions-send-prefer-session-key

openclaw-barnacle Bot added size: S and removed size: XS labels Apr 2, 2026

Copilot AI reviewed Apr 2, 2026

View reviewed changes

Merge branch 'main' into fix/sessions-send-prefer-session-key

2fdfe08

Mintalix requested a review from Copilot April 2, 2026 12:35

Copilot started reviewing on behalf of Mintalix April 2, 2026 12:36 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

Mintalix added 3 commits April 2, 2026 23:46

Merge branch 'main' into fix/sessions-send-prefer-session-key

f1f54bc

Merge branch 'main' into fix/sessions-send-prefer-session-key

121ad49

Merge branch 'main' into fix/sessions-send-prefer-session-key

26027fb

This was referenced Apr 27, 2026

fix: prefer sessionKey over label in sessions_send instead of rejecting both #41255

Closed

Agent-to-Agent Communication Tools Have Parameter Conflicts #41199

Open

Mintalix added 2 commits April 27, 2026 22:22

Merge branch 'main' into fix/sessions-send-prefer-session-key

c19b45e

Merge branch 'main' into fix/sessions-send-prefer-session-key

2d09476

clawsweeper Bot mentioned this pull request Apr 28, 2026

fix: prefer sessionKey over label in sessions_send #39551

Closed

18 tasks

openclaw-clownfish Bot mentioned this pull request Apr 29, 2026

fix(agents): prefer sessionKey in sessions_send #74009

Closed

openclaw-clownfish Bot closed this Apr 29, 2026

clawsweeper Bot mentioned this pull request Apr 29, 2026

[Bug]: sessions_send unexpectedly injects label, causing mutual-exclusion error with sessionKey #64699

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(agents): prefer sessionKey in sessions_send#59324

fix(agents): prefer sessionKey in sessions_send#59324
Mintalix wants to merge 13 commits into
openclaw:mainfrom
Mintalix:fix/sessions-send-prefer-session-key

Mintalix commented Apr 2, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Apr 2, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

clawsweeper Bot commented Apr 28, 2026 •

edited

Loading

Uh oh!

openclaw-clownfish Bot commented Apr 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Mintalix commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Root Cause / Regression History (if applicable)

Regression Test Plan (if applicable)

User-visible / Behavior Changes

Diagram (if applicable)

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Review Conversations

Compatibility / Migration

Risks and Mitigations

Uh oh!

greptile-apps Bot commented Apr 2, 2026

Greptile Summary

Confidence Score: 5/5

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

clawsweeper Bot commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openclaw-clownfish Bot commented Apr 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Mintalix commented Apr 2, 2026 •

edited

Loading

clawsweeper Bot commented Apr 28, 2026 •

edited

Loading