Repository navigation
docs: a ping is the replay boundary, a cursor frame is not - #250
Merged
Merged
Conversation
States the agent event stream contract in FeedFrame and the channel plan, from the contract questions on #232. Refs #239. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QNDehAAVazXavfSCUqc9om
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Requested by Allen · project thread
Human overview
Writes down the agent event stream contract that the questions on #232 brought up. A
: pingmarks the end of replay, because the server only sends one when it has nothing past the client's position. Acursorframe only marks skipped events. This is the decision to keep the ping as the boundary. Docs only: theFeedFramedocstring and one bullet in the channel plan. Refs #239.AI reviewer
Details for agents: what the diff does, invariants, verification, checklist
What the diff does. Two prose additions, with no change to behavior.
src/pepper_cli/api_client.pyFeedFramedocstring: a: pingis the replay boundary (sent only while the server has nothing past the caller's position). Acursorframe is not a boundary and can arrive mid-replay or not at all. Astart=headstream opens with its headcursorframe, afterscopeand before any event or ping.planning/claude-code-channel.md§7.4 first-run bullet: keeps "the first heartbeat after replay" and adds why it is the boundary, plus the same note about cursor frames.Why. #232 proposed using the cursor frame as the end-of-replay marker, and #246 reworded the plan to match. The server sends a cursor frame only when a page's tail was filtered out, so it is a skip marker. The ping is what
claude_channel.pyonmainalready uses. #246 is closed and #232 has been asked to keep only itsfirst_runfix.Known edge. A single upstream scan that takes longer than the heartbeat interval could produce a ping mid-replay. The client would then end replay early and owe a spurious
resync. That is noisy but safe, and this PR does not document it.Verification.
uv run ruff format --checkanduv run ruff checkboth clean.npx markdownlint-cli2@0.18.1 planning/claude-code-channel.mdgives 0 errors. Tests andtywere not re-run because the only Python change is a docstring.Checklist (repo-specific)
uv run ruff format --checkanduv run ruff checkclean (no new lint ignores)uv run ty check src/pepper_cli/clean: not run, docstring-only changeuv run pytestpasses: not run, no behavior changeSKILL.mdupdated if commands or output changed: not applicable, no command or output changedGenerated by Claude Code