docs(imessage): warn that cliPath wrappers must stream JSON-RPC stdio (#84330)#84347
docs(imessage): warn that cliPath wrappers must stream JSON-RPC stdio (#84330)#84347hclsys wants to merge 1 commit into
Conversation
…openclaw#84330) A custom `cliPath` wrapper or SSH proxy in front of `imsg` must behave like a transparent stdio pipe for long-lived JSON-RPC: small newline- framed messages can sit indefinitely if the wrapper buffers stdin until EOF or a large block fills. The visible symptom is `imsg rpc timeout (chats.list)` or repeated channel restarts even though `imsg rpc` is healthy. Add a <Warning> block in the 'Remote Mac over SSH' Tab listing the six interoperability requirements the issue calls out, and note that filter pipelines like `ssh host imsg | grep ...` need `stdbuf -oL` on every stage to stay safe.
|
Codex review: needs changes before merge. Workflow note: Future ClawSweeper reviews update this same comment in place. How this review workflow works
Summary Reproducibility: yes. at source level: current main lacks the warning, and the runtime client uses long-lived newline-framed JSON-RPC over the configured PR rating Rank-up moves:
What the crustacean ranks mean
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. Real behavior proof Risk before merge
Maintainer options:
Next step before merge Security Review findings
Review detailsBest possible solution: Keep the new warning, but remove or rewrite the Do we have a high-confidence way to reproduce the issue? Yes at source level: current main lacks the warning, and the runtime client uses long-lived newline-framed JSON-RPC over the configured Is this the best way to solve the issue? Mostly yes. Documenting the streaming requirement in the Remote Mac setup section is the right fix, but the added Label changes:
Full review comments:
Overall correctness: patch is correct Acceptance criteria:
What I checked:
Likely related people:
Codex review notes: model gpt-5.5, reasoning high; reviewed against ad925bd43b1e. |
|
ClawSweeper PR egg ✨ Hatched: 🥚 common Moonlit Merge Sprite Hatch commandComment Hatchability rules:
Rarity: 🥚 common. What is this egg doing here?
|
|
@clawsweeper hatch |
|
🦞👀 I queued a comment sync for this PR. If the egg is hatchable, ClawSweeper will generate the image once and update the existing review comment. |
|
ClawSweeper could not hatch this PR egg yet. Reason: there is no current durable ClawSweeper review record for this PR, so there is no PR egg state record to update. |
|
@clawsweeper hatch |
|
@clawsweeper automerge |
|
🦞🧹
Draft PRs stay fix-only until GitHub marks them ready for review. Pause with Automerge progress:
|
|
ClawSweeper 🐠 reef update Thanks for the contribution. ClawSweeper hit a branch-permission wall on this PR, so it opened a replacement branch to keep review moving while preserving credit. Why replacement: ClawSweeper could not update the source PR branch directly; GitHub did not grant sufficient push rights to the bot for that branch.
fish notes: model gpt-5.5, reasoning high; reviewed against a371ee9. |
Fixes #84330.
docs/channels/imessage.mddocuments thatchannels.imessage.cliPathcan be pointed at an SSH/custom wrapper but doesn't call out a critical interoperability requirement: the wrapper must forward JSON-RPC stdin/stdout incrementally. The OpenClaw iMessage channel exchanges small newline-framed JSON-RPC frames over the wrapper's stdio for the channel's entire lifetime. A wrapper that reads with a large blockingread(N)or buffers stdin until EOF will make small frames likechats.listsit indefinitely, producing symptoms that look exactly like an iMessage outage (imsg rpc timeout (chats.list), repeated channel restarts) even thoughimsg rpcitself is fine.Changes
docs/channels/imessage.md: add a<Warning>block inside the "Remote Mac over SSH" Tab listing the six interoperability requirements the issue calls out (forward stdin/stdout promptly, preserve newlines, don't wait for EOF, avoid fixed-size blocking reads, keep stderr separate). Cite the exact symptom phrasing the issue uses (imsg rpc timeout) so operators searching for that error find the warning. Note the practical pitfall that pipelines likessh host imsg | grep ...needstdbuf -oL -eLon every stage to stay safe — line-buffered tools can still hold frames otherwise.Diff stat: 1 file, +12 / -0. Documentation-only.
Real behavior proof
Behavior or issue addressed: Sanitized issue evidence — the issue describes that a custom stdio bridge wrapper using a large blocking
read(N)producedimsg rpc timeout (chats.list)until the wrapper was changed to forward bytes/lines as soon as they were available. The fix documents this constraint at the spot operators actually look.Real environment tested: Local Node 22.x. Probe at
/tmp/probe_84330.mjs(a) verifies the<Warning>block was added todocs/channels/imessage.mdand lives inside the "Remote Mac over SSH" Tab, (b) checks coverage against the issue's "Expected Documentation" list — all six bullets present (forward stdin/stdout promptly, preserve newlines, don't wait for EOF, avoid fixed-size blocking reads, keep stderr separate), (c) confirms the exact symptom phrasingimsg rpc timeoutis cited so operators searching for that error find this section, (d) confirms surrounding sections (Tab intro + Requirements heading) are unchanged, (e) checks<Warning>open/close tags are balanced.Exact steps or command run after this patch:
node /tmp/probe_84330.mjsEvidence after fix:
Observed result after fix: Operators following the "Remote Mac over SSH" Tab now see the streaming requirement directly under the wrapper-script example. The Warning calls out the visible symptom (
imsg rpc timeout), the structural requirements, and a common pitfall (greppipelines withoutstdbuf -oL) that produces the same failure mode.What was not tested: No iMessage instance was actually run against a buffering wrapper to reproduce the symptom — this is a documentation-only change to an existing operator-facing manual page. The doc updates the section the issue explicitly suggests in "Suggested Location" (
docs/channels/imessage.mdnear the Remote Mac over SSH wrapper section).Audit (per CLAUDE rules — all 5 steps)
<Warning>Mintlify component is the established callout convention used throughout this doc and across the docs site. PASSgh pr list --search '84330 in:title,body'andgh pr list --search 'iMessage cliPath wrapper'return no open PRs. Issue timeline shows zero cross-references. PASSgit log --oneline -5 -- docs/channels/imessage.mdshows no recent commits touching this file. PASS