gateway: support user-role chat.inject with idempotent replays by aaronclawrsl-bot · Pull Request #81513 · openclaw/openclaw

aaronclawrsl-bot · 2026-05-13T19:28:33Z

Summary

extend chat.inject params with optional role (assistant | user) and idempotencyKey
preserve existing assistant injection behavior as default
add a user-role transcript append path through the shared transcript append pipeline
make idempotent chat.inject replays return { ok: true, deduped: true } instead of failing
add unit coverage for injected user transcript append

Why

Telegram relay hooks need a first-class Gateway RPC to append user-role messages into a session transcript without triggering a model run.

Notes

backward compatible: existing chat.inject calls without role remain assistant injections
no scope changes required (still under existing chat.inject authorization)

Real behavior proof

Behavior or issue addressed: chat.inject must support user-role transcript append and idempotent replay should not fail.
Real environment tested: Live OpenClaw Gateway on Linux host, local operator runtime, real session transcript files under ~/.openclaw/agents/*/sessions/*.jsonl.
Exact steps or command run after this patch:
1. openclaw gateway call chat.inject --json --timeout 30000 --params '{"sessionKey":"agent:druck:telegram:group:-1003846579956:topic:1","role":"user","message":"REAL_PROOF_ROLE_USER_2026-05-13","idempotencyKey":"real-proof-user-20260513-c"}'
2. Repeat same command with same idempotencyKey.
3. rg -n 'real-proof-user-20260513-c|REAL_PROOF_ROLE_USER_2026-05-13' /home/aaron/.openclaw/agents/druck/sessions/d0b805cb-c944-4079-9351-3d9b620a76d2-topic-1.jsonl && rg -c 'real-proof-user-20260513-c' /home/aaron/.openclaw/agents/druck/sessions/d0b805cb-c944-4079-9351-3d9b620a76d2-topic-1.jsonl
Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output):

$ openclaw gateway call chat.inject --json --timeout 30000 --params '{"sessionKey":"agent:druck:telegram:group:-1003846579956:topic:1","role":"user","message":"REAL_PROOF_ROLE_USER_2026-05-13","idempotencyKey":"real-proof-user-20260513-c"}'
{
  "ok": true,
  "messageId": "c7b247bc"
}

$ openclaw gateway call chat.inject --json --timeout 30000 --params '{"sessionKey":"agent:druck:telegram:group:-1003846579956:topic:1","role":"user","message":"REAL_PROOF_ROLE_USER_2026-05-13","idempotencyKey":"real-proof-user-20260513-c"}'
{
  "ok": true,
  "deduped": true
}

$ rg -n 'real-proof-user-20260513-c|REAL_PROOF_ROLE_USER_2026-05-13' /home/aaron/.openclaw/agents/druck/sessions/d0b805cb-c944-4079-9351-3d9b620a76d2-topic-1.jsonl
827:{"type":"message","id":"c7b247bc",...,"message":{"role":"user","content":[{"type":"text","text":"REAL_PROOF_ROLE_USER_2026-05-13"}],...,"idempotencyKey":"real-proof-user-20260513-c"}}

$ rg -c 'real-proof-user-20260513-c' /home/aaron/.openclaw/agents/druck/sessions/d0b805cb-c944-4079-9351-3d9b620a76d2-topic-1.jsonl
1

Observed result after fix: First call appends a user-role transcript message; second call with same idempotencyKey returns deduped success; transcript persists exactly one matching entry.
What was not tested: Full end-to-end Telegram channel mention loop was not re-run as part of this proof block.
Before evidence (optional but encouraged): Before this patch, replaying the same idempotency key returned failed to write transcript: unknown error for this flow.

Hardening: race-safe idempotency (commit `9ea70b8`)

Third-party review flagged that the original transcriptHasIdempotencyKey precheck happened before acquiring the per-transcript queue+write lock — a TOCTOU window where two concurrent identical requests could both pass the check and persist duplicates. Fixed by moving the dedupe scan inside the locked critical section in appendSessionTranscriptMessage and threading idempotencyKey through as a first-class parameter. Result is returned with deduped: true and the canonical existing messageId, so duplicate broadcasts are suppressed too.

Concurrent replay test (added in this PR)

src/gateway/server-methods/chat.inject.parentid.test.ts — 16-way Promise.all of identical idempotent injects:

✓  gateway-methods  src/gateway/server-methods/chat.inject.parentid.test.ts (5 tests) 837ms
   ✓ dedupes concurrent identical idempotent injects (race-safe)

Asserts: messageIds.size === 1, dedupedCount === concurrency - 1, and the on-disk transcript contains exactly one entry with the matching idempotencyKey.

Live concurrent evidence (8-way, hot-patched runtime)

$ IDEM="race-final-1778710992"
$ for i in 1..8; do (openclaw gateway call chat.inject \
    --params '{"sessionKey":"...","role":"user","message":"race final","idempotencyKey":"'$IDEM'"}' \
    </dev/null >/tmp/race-$i.out 2>&1) & done; wait

[1] {"ok":true,"deduped":true}
[2] {"ok":true,"deduped":true}
[3] {"ok":true,"deduped":true}
[4] {"ok":true,"deduped":true}
[5] {"ok":true,"deduped":true}
[6] {"ok":true,"deduped":true}
[7] {"ok":true,"deduped":true}
[8] {"ok":true,"deduped":true}

# disk-state invariant: at-most-once persistence
$ grep -c "$IDEM" $TRANSCRIPT
1
$ grep "$IDEM" $TRANSCRIPT | jq -r .id | sort -u | wc -l
1

The on-disk invariant — at most one persisted entry per (transcriptPath, idempotencyKey) — holds under true concurrency.

Post-update verification (2026-05-15)

Additional in-depth edge-case coverage was added after initial hardening:

no-idempotency-key path does not dedupe (two writes persist)
deduped replay does not emit duplicate transcript-update events
assistant-role inject dedupes correctly by idempotency key
distinct idempotency keys remain isolated (no cross-key collision)

Updated local test results on branch head 0d8ea32769:

✓  plugins  src/plugins/registry.runtime-config.test.ts (1 test)
✓  gateway-client  src/gateway/server-methods/chat.inject.parentid.test.ts (10 tests)
✓  gateway-methods  src/gateway/server-methods/chat.inject.parentid.test.ts (10 tests)
Tests  21 passed (21)

clawsweeper · 2026-05-13T19:31:51Z

Codex review: found issues before merge. Reviewed July 3, 2026, 11:51 PM ET / 03:51 UTC.

Summary
The PR adds optional role and idempotencyKey handling to chat.inject, adds user-role transcript append and replay dedupe paths, updates generated Swift, and expands focused gateway transcript tests.

PR surface: Source +43, Tests +270, Other +8. Total +321 across 7 files.

Reproducibility: yes. Source inspection shows current main and v2026.6.11 still reject role and public idempotencyKey on chat.inject, while the handler still appends through the assistant path only.

Review metrics: 1 noteworthy metric.

Public chat.inject params: 2 params added; 1 current generated field omitted; 1 stale schema path touched. This public Gateway RPC contract needs schema, generated clients, docs, and upgrade behavior reconciled before merge.

Stored data model
Persistent data-model change detected: serialized state: src/config/sessions/transcript-append.ts, serialized state: src/gateway/server-methods/chat.inject.parentid.test.ts, unknown-data-model-change: src/config/sessions/transcript-append.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #79820
Summary: This PR is a candidate implementation for the canonical user-role/idempotent chat.inject request; adjacent chat.inject metadata work overlaps the schema surface but does not replace this work.

Members:

canonical: chat.inject needs user-role replay and stable caller IDs for synthetic turns #79820 - The issue asks for user-role replay, stable caller IDs/idempotency, and parent-chain behavior for synthetic turns, matching this PR's central purpose.
partial_overlap: feat(gateway): allow chat.inject to override provider attribution via originAgent #79959 - That open PR touches the same closed chat.inject schema surface for origin-agent attribution but does not implement user-role replay or stable replay IDs.
partial_overlap: Expose chat.inject metadata for plugin approval updates #82471 - That closed unmerged PR proposed metadata/idempotency for plugin approval status cards on chat.inject, but it does not supersede this user-role replay request.
superseded: feat(gateway): add optional role param to chat.inject RPC #60706 - That older closed unmerged PR proposed only the optional role piece, while this PR and the canonical issue cover the current replay/idempotency shape.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🦞 diamond lobster
Patch quality: 🧂 unranked krab
Result: blocked by patch quality or review findings.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

Rebase or replace the branch on current main and move schema changes to packages/gateway-protocol.
Preserve selected-agent/global routing, assistant TTS supplement metadata, and the current transcript idempotency contract.

Risk before merge

[P1] The PR changes the public chat.inject Gateway wire/client contract while targeting a stale schema path and generated Swift surface, so generated clients and protocol validation need current-main reconciliation.
[P1] The PR head can misroute or suppress selected-agent and global-session visible updates because it bypasses current selected-agent validation and global-aware node delivery.
[P1] The assistant injection refactor can drop openclawTtsSupplement metadata from existing assistant media/TTS transcript rows.
[P1] The transcript append changes add a parallel idempotency result shape instead of composing with current main's locked idempotencyLookup and appended contract.
[P1] The branch is draft and conflicting, so the actual merge result cannot be reviewed until the branch is rebased or replaced.

Maintainer options:

Refresh against current Gateway contracts (recommended)
Rebase or replace the branch so the new fields land in packages/gateway-protocol, generated clients retain agentId, and the handler keeps current routing, metadata, and idempotency semantics.
Approve the public API shape first
Maintainers can explicitly sponsor the admin-scoped role and idempotencyKey contract before implementation polish continues, because this changes a public Gateway RPC surface.
Retire this draft and keep the issue canonical
If reconciling the stale draft is not worth the risk, keep chat.inject needs user-role replay and stable caller IDs for synthetic turns #79820 open and ask for a narrow replacement PR based on current main.

Next step before merge

[P2] Maintainers need to decide the public Gateway API shape and request a current-main rebase or replacement; this is not a safe automated repair on the draft dirty branch.

Security
Cleared: No dependency, workflow, secret-handling, or supply-chain regression was found; the admin-scoped user-role injection remains a Gateway API trust-boundary decision before merge.

Review findings

[P1] Preserve selected-agent routing for chat.inject — src/gateway/server-methods/chat.ts:2868
[P1] Keep assistant TTS supplement metadata — src/gateway/server-methods/chat-transcript-inject.ts:156-165
[P2] Move chat.inject schema changes to the current protocol package — src/gateway/protocol/schema/logs-chat.ts:69-70

Review details

Best possible solution:

Land a refreshed current-main implementation that adds user-role replay and stable idempotency through packages/gateway-protocol, while preserving assistant defaults, selected-agent/global routing, parent-chain-safe transcript writes, assistant metadata, generated clients, docs, and focused tests.

Do we have a high-confidence way to reproduce the issue?

Yes. Source inspection shows current main and v2026.6.11 still reject role and public idempotencyKey on chat.inject, while the handler still appends through the assistant path only.

Is this the best way to solve the issue?

No, not as submitted. The direction is plausible, but the best fix must be rebased or replaced to use the current protocol package and preserve routing, metadata, and idempotency invariants.

Full review comments:

[P1] Preserve selected-agent routing for chat.inject — src/gateway/server-methods/chat.ts:2868
The PR head loads the session with loadSessionEntry(rawSessionKey) and broadcasts with context.nodeSendToSession(sessionKey, ...), dropping current main's agentId selection, selected-agent validation, and global-aware delivery path. Rebase the handler so user-role injection keeps the same selected-agent/global routing contract as current chat.inject.
Confidence: 0.9
[P1] Keep assistant TTS supplement metadata — src/gateway/server-methods/chat-transcript-inject.ts:156-165
The refactored assistant path no longer accepts or persists openclawTtsSupplement, while current main passes that marker for gateway-injected assistant media/TTS rows. Add the user-role path without removing the assistant metadata path.
Confidence: 0.86
[P2] Move chat.inject schema changes to the current protocol package — src/gateway/protocol/schema/logs-chat.ts:69-70
This edits the retired src/gateway/protocol schema path, but current main validates chat.inject from packages/gateway-protocol and generated Swift already includes agentId. Rebase the schema change to the current protocol package and regenerate clients without dropping agentId.
Confidence: 0.88
[P2] Compose with the current transcript idempotency contract — src/config/sessions/transcript-append.ts:250
The branch adds a parallel idempotencyKey parameter and deduped result to appendSessionTranscriptMessage, while current main already exposes locked replay through message idempotencyKey, idempotencyLookup: "scan", and appended results. Rebase onto that contract instead of adding a competing API.
Confidence: 0.82

Overall correctness: patch is incorrect
Overall confidence: 0.9

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 9d68f877ac3e.

Label changes

Label justifications:

P2: This is a bounded Gateway/session API feature with real transcript-coherence impact but limited blast radius.
merge-risk: 🚨 compatibility: The PR adds public chat.inject fields while targeting stale schema and generated-client surfaces relative to current main.
merge-risk: 🚨 message-delivery: The stale handler changes live chat broadcast routing and can misroute or suppress selected-agent or global-session updates.
merge-risk: 🚨 session-state: The patch changes transcript role persistence and idempotent append behavior, affecting session history and replay coherence.
rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🦞 diamond lobster and patch quality is 🧂 unranked krab.
status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (live_output): The PR body includes copied live Gateway output showing after-fix user-role append, same-key deduped replay, concurrent replay behavior, and one persisted transcript entry.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes copied live Gateway output showing after-fix user-role append, same-key deduped replay, concurrent replay behavior, and one persisted transcript entry.

Evidence reviewed

PR surface:

Source +43, Tests +270, Other +8. Total +321 across 7 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	4	293	250	+43
Tests	2	274	4	+270
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	1	9	1	+8
Total	7	576	255	+321

What I checked:

Current main schema remains closed: Current main ChatInjectParamsSchema accepts sessionKey, optional agentId, message, and optional label; it still does not accept role or public idempotencyKey. (packages/gateway-protocol/src/schema/logs-chat.ts:115, 9d68f877ac3e)
Current main handler is assistant-only but preserves routing: Current main validates the closed schema, loads the selected agent, appends via appendAssistantTranscriptMessage, and broadcasts through sendGlobalAwareNodeChatPayload. (src/gateway/server-methods/chat.ts:5361, 9d68f877ac3e)
Latest release has the same closed schema: Release v2026.6.11 contains the same ChatInjectParamsSchema shape without role or public idempotencyKey, so the requested contract has not shipped. (packages/gateway-protocol/src/schema/logs-chat.ts:114, e085fa1a3ffd)
PR head bypasses current selected-agent routing: The PR head loads the session with loadSessionEntry(rawSessionKey) and later calls context.nodeSendToSession, omitting current main's selected-agent validation and global-aware delivery path. (src/gateway/server-methods/chat.ts:2868, 09ec74efdd6d)
PR head edits stale protocol path: The PR adds role and idempotencyKey under src/gateway/protocol/schema/logs-chat.ts, while current main imports validators from packages/gateway-protocol/src. (src/gateway/protocol/schema/logs-chat.ts:69, 09ec74efdd6d)
PR head generated Swift omits current agentId: The PR head's generated ChatInjectParams includes sessionKey, message, label, role, and idempotencyKey, but not current main's optional agentId. (apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift:6315, 09ec74efdd6d)

Likely related people:

steipete: History shows the original chat.inject Gateway method and later transcript append helper extraction in the relevant gateway files. (role: introduced behavior and helper extractor; confidence: high; commits: a4b347b45483, 142c0a7f7d0c; files: src/gateway/server-methods/chat.ts, src/gateway/server-methods/chat-transcript-inject.ts)
Takhoffman: History shows prior fixes for canonical chat.inject session routing and injected-message parentId behavior, both directly relevant to the routing and transcript risks here. (role: session routing contributor; confidence: high; commits: a0f48f099ed1, 0cf93b8fa745; files: src/gateway/server-methods/chat.ts, src/gateway/server-methods/chat-transcript-inject.ts)
jalehman: Merged PR history for refactor: route transcript writers through session seam #89123 routes transcript writers through the session seam across the files this PR changes. (role: recent transcript seam contributor; confidence: high; commits: 00a75db4280b; files: src/config/sessions/transcript-append.ts, src/gateway/server-methods/chat-transcript-inject.ts, src/gateway/server-methods/chat.ts)
masatohoshino: Recent broad commits touched current Gateway protocol and handler regions, making this a lower-confidence routing signal for current-main surface ownership. (role: recent adjacent contributor; confidence: medium; commits: 37341a703223; files: packages/gateway-protocol/src/schema/logs-chat.ts, src/gateway/server-methods/chat.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

openclaw-barnacle · 2026-06-02T05:07:52Z

This pull request has been automatically marked as stale due to inactivity.
Please add updates or it will be closed.

openclaw-barnacle · 2026-07-19T04:30:42Z

This pull request has been automatically marked as stale due to inactivity.
Please add updates or it will be closed.

clawsweeper · 2026-07-19T16:08:01Z

ClawSweeper status: review started.

I am starting a fresh review of this pull request: gateway: support user-role chat.inject with idempotent replays This is item 1/1 in the current shard. Shard 8/22.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.

openclaw-barnacle Bot added app: web-ui App: web-ui gateway Gateway runtime size: M triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels May 13, 2026

openclaw-barnacle Bot added proof: supplied External PR includes structured after-fix real behavior proof. and removed triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels May 13, 2026