Skip to content

Fix/agent session key normalization#15707

Merged
Takhoffman merged 2 commits intoopenclaw:mainfrom
rodrigouroz:fix/agent-session-key-normalization
Feb 15, 2026
Merged

Fix/agent session key normalization#15707
Takhoffman merged 2 commits intoopenclaw:mainfrom
rodrigouroz:fix/agent-session-key-normalization

Conversation

@rodrigouroz
Copy link
Contributor

@rodrigouroz rodrigouroz commented Feb 13, 2026 •
edited by greptile-apps bot
Loading

Summary

This PR hardens gateway agent session-key validation so malformed agent-prefixed keys are rejected early and consistently.

Problem

Malformed values like agent:main were not being rejected up front in some agent paths.
Instead, they could flow deeper into runtime/workspace resolution and fail later with UNAVAILABLE-style errors, which made the issue look like infra/runtime instability
instead of request validation.

Why this matters

  • agent:* keys have a strict shape and malformed values are client input errors.
  • Returning INVALID_REQUEST early gives clients a stable, actionable contract.
  • It prevents noisy downstream failures and reduces misleading error signals.

Root Cause / Context

  • agent handler accepted sessionKey strings and trimmed them, but did not explicitly reject malformed agent:* shapes before execution.
  • agent.identity.get similarly derived agent identity from sessionKey without an explicit malformed-shape guard.
  • Main already contains a separate sessions-path compatibility fix (fix(sessions): normalize absolute sessionFile paths for v2026.2.12 compatibility), but that does not cover
    malformed agent:* request validation in these handlers.

Fix

src/gateway/server-methods/agent.ts

  • In agent:

    • added early guard using classifySessionKeyShape(...)
    • if shape is malformed_agent, return:
      • INVALID_REQUEST
      • message: invalid agent params: malformed session key "<key>"

  • In agent.identity.get:

    • added equivalent malformed-shape guard
    • returns:
      • INVALID_REQUEST
      • message: invalid agent.identity.get params: malformed session key "<key>"

Tests

src/gateway/server-methods/agent.test.ts

  • added unit test: rejects malformed agent session keys early in agent
  • added unit test: rejects malformed session keys in agent.identity.get

src/gateway/server.agent.gateway-server-agent-a.e2e.test.ts

  • added e2e test: agent rejects malformed agent-prefixed session keys
  • verifies:
    • request fails
    • error mentions malformed session key
    • command dispatch is not executed

Verification run

  • pnpm test src/gateway/server-methods/agent.test.ts
  • pnpm vitest run --config vitest.e2e.config.ts src/gateway/server.agent.gateway-server-agent-a.e2e.test.ts -t "agent rejects malformed agent-prefixed session keys"

Risk / Compatibility

Low risk:

  • only affects malformed agent:* inputs
  • valid session keys and existing behavior remain unchanged
  • change is additive validation + tests

Greptile Overview

Greptile Summary

This PR adds early validation to the gateway agent and agent.identity.get handlers to reject malformed agent:* session keys using classifySessionKeyShape(...), returning INVALID_REQUEST instead of allowing downstream failures.

It also adds unit + e2e coverage to ensure malformed agent:-prefixed keys (e.g. agent:main) fail fast and do not dispatch agentCommand.

Confidence Score: 4/5

  • This PR is largely safe to merge, with one correctness edge case around session-key prefix casing.
  • The change is small and well-covered by tests for the malformed agent:main case. However, session-key shape classification relies on parseAgentSessionKey, which currently treats the agent prefix as case-sensitive, so keys like Agent:... will be rejected as malformed by the new guards even though they are structurally valid elsewhere in the codebase that lowercases agent keys.
  • src/sessions/session-key-utils.ts (parseAgentSessionKey casing)

Last reviewed commit: dc3a0fa

@openclaw-barnacle openclaw-barnacle bot added gateway Gateway runtime size: S trusted-contributor Contributor with 4+ merged PRs labels Feb 13, 2026
greptile-apps[bot]
greptile-apps bot reviewed Feb 13, 2026
View reviewed changes
Copy link
Contributor

@greptile-apps greptile-apps bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

3 files reviewed, 1 comment

Edit Code Review Agent Settings | Greptile

@greptile-apps
Copy link
Contributor

greptile-apps bot commented Feb 13, 2026

Additional Comments (1)

src/sessions/session-key-utils.ts
Case-sensitive parseAgentSessionKey

parseAgentSessionKey checks parts[0] !== "agent" using the original casing, but classifySessionKeyShape treats any raw.toLowerCase().startsWith("agent:") as malformed_agent. This means inputs like Agent:main:main will be misclassified as malformed and rejected by the new guards, even though the rest of the key is structurally valid (and other code paths lowercase agent keys, e.g. toAgentStoreSessionKey). Consider normalizing parts[0] (and/or all parts) to lowercase before comparison so valid agent-prefixed keys aren’t rejected just due to casing.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: src/sessions/session-key-utils.ts
Line: 17:20

Comment:
**Case-sensitive parseAgentSessionKey**

`parseAgentSessionKey` checks `parts[0] !== "agent"` using the original casing, but `classifySessionKeyShape` treats any `raw.toLowerCase().startsWith("agent:")` as `malformed_agent`. This means inputs like `Agent:main:main` will be misclassified as malformed and rejected by the new guards, even though the rest of the key is structurally valid (and other code paths lowercase agent keys, e.g. `toAgentStoreSessionKey`). Consider normalizing `parts[0]` (and/or all `parts`) to lowercase before comparison so valid agent-prefixed keys aren’t rejected just due to casing.

How can I resolve this? If you propose a fix, please make it concise.

@rodrigouroz rodrigouroz force-pushed the fix/agent-session-key-normalization branch 2 times, most recently from 3075d5a to ab0a699 Compare February 15, 2026 14:09
@Takhoffman Takhoffman force-pushed the fix/agent-session-key-normalization branch from ab0a699 to 2b9b5b3 Compare February 15, 2026 15:45
@Takhoffman Takhoffman merged commit df95ddc into openclaw:main Feb 15, 2026
8 of 9 checks passed
@Takhoffman
Copy link
Contributor

Takhoffman commented Feb 15, 2026 •
edited
Loading

PR #15707 - Fix/agent session key normalization (#15707)

Merged via squash.

  • Merge commit: df95ddc

  • Verified: pnpm build, pnpm check, pnpm test:macmini

  • Changes made:
    M CHANGELOG.md
    M src/gateway/server-methods/agent.test.ts
    M src/gateway/server-methods/agent.ts
    M src/gateway/server.agent.gateway-server-agent-a.e2e.test.ts

  • Changelog: CHANGELOG.md updated=true required=true opt_out=false

Thanks @rodrigouroz!

@Takhoffman Takhoffman self-assigned this Feb 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer

@greptile-apps greptile-apps[bot] greptile-apps[bot] left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

@Takhoffman Takhoffman

Labels

gateway Gateway runtime size: S trusted-contributor Contributor with 4+ merged PRs

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@rodrigouroz @Takhoffman

Comments