Repository navigation
feat(client): read a long session from its newest end (FIX-2408) - #4510
Conversation
readSessionTail reads a session's newest page, readSessionEarlier grows the window back on request, and refreshSessionWindow reads it again from its start. Every read goes through readSessionHistory, the client's one paging loop (FIX-2374's), given a start offset. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NczDiDgwa4zZVeE3jwkDQL
|
The latest updates on your projects. Learn more about Vercel for GitHub. 4 Skipped Deployments
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Second look + architecture passVerdict: the approach holds. It matches the merged spec (D1/D2), and the tests pin the right things (refresh-from-start, overlap restart, session re-created). Nothing blocks. The items below are for the implementing agent to take or drop. Is there a better approach?Not within the spec's decisions. A route-side Findings (most useful first)
Architecture (only where this PR is the opportunity)
No changes needed to the changeset or the test layout. Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1033af60ea
ℹ️ 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".
There was a problem hiding this comment.
Simplify review (FIX-2408 + stack)
I read the FIX-2408 implementation commit (~596 lines) and the full branch diff (~6.3k lines / 72 files). Parallel read-only passes covered code quality, performance, and reuse against useSession, readEveryCollectionPage, and Shift Manager sessionHoldsLine.
Verdict on approach (FIX-2408)
The chosen shape looks right for the spec, not over-engineered relative to the alternatives the issue already rejected:
- D1 (refresh = re-read start→end) is the meaningful complexity. It is heavier than a delta read, but the spec and unit tests argue delta reads miss in-place streaming updates and late-stamped items. I would not simplify that away without revisiting D1.
- D2 (three public helpers over internal
readSessionHistory+offset) is cleaner than a second overlap loop in this module or a bespokefrom_endroute (FIX-877 cost deferred). Tail-first probe + second read fromtotal - limitmatches Shift Manager’s today pattern and generalisessessionHoldsLinein the adoption PR. - Directory layout (
session-client/session-window.ts+ internalsession-history.ts, mirroringreadEveryCollectionPage) is a good sign.
I ran pnpm --filter @flow-state-dev/client test -- session-window — 9 tests passed.
Where the PR went too far (merge / review scope)
This branch is a project thread, not a FIX-2408 slice. On top of main it includes:
- #4472 — workspace / harness-manager / fsdev / worktrees (~5.7k lines)
- FIX-2429 — retained spec + POC
- FIX-2408 — spec + client implementation
The PR title/body describe only FIX-2408. That makes review, rollback, and bisect much harder than the client change warrants.
Recommendation (strong): either rebase this PR to FIX-2408 implementation only (spec already merged via #4395 on this branch — confirm against main), or retitle/rebody and get explicit sign-off that a multi-epic stack merge is intentional. Past simplify reviews in this repo have treated bundled specs the same way.
I am not approving the full PR as-is because of that stack; the FIX-2408 code itself is close to approvable once scope is honest.
Simpler / cleaner follow-ups (FIX-2408 slice)
| Item | Severity | Note |
|---|---|---|
readSessionHistory lands before/alongside FIX-2374 wiring |
Medium (reuse) | Epic allows either merge order, but three copies of the overlap loop exist today (session-history.ts, useSession, Teammates session-feed). Highest-leverage simplification is 2374 calling client readSessionHistory and deleting the react inline loop — not in wave 1 per spec, but do it soon after. |
Dedicated session-history.test.ts |
Medium | Window tests cover history indirectly; overlap restart, exhausted attempts, and offset > 0 deserve the same treatment as read-every-page.test.ts. |
reread session swap guard |
Low (maybe bug) | Reset to readSessionTail only when window.sessionCreatedAt !== undefined. If the first read omitted sessionCreatedAt, a id-reuse swap might not reset — might be worth aligning with readSessionHistory’s mid-read guard; I have not proven a failing scenario on a real host. |
Wide-window refreshSessionWindow |
Low (perf) | pageLimit = window.total - start + 200 minimises call count but can mean one huge state request after Load earlier loads a large span — relevant for Shift Manager’s 5s refresh until FIX-2409. Inherent to D1 unless you cap page size and accept multi-page refresh. |
| Offset-0 probe waste | Info | Long-session tail always fetches then drops the oldest limit items to learn total (E7). Accepted in spec sign-off; a metadata-only state shape would be the real fix later. |
Alternative approaches considered
- Server
from_end/ count-only state — simpler call pattern, but spec explicitly deferred (engine + FIX-877). - Only bump Shift Manager page size — rejected in spec; still drops newest past cap.
- Inline tail loop without
readSessionHistory— rejected in D2; duplicates FIX-2374’s paging rule.
What I would approve
After scope is split or explicitly acknowledged, I would be comfortable approving the FIX-2408 client commit with optional follow-ups above (especially session-history tests + 2374 dedupe). I am not asking to revisit D1/D2 unless product wants cheaper refresh at the cost of the stamped-item / in-progress reply cases the tests document.
Sent by Cursor Automation: Review For Best Approach
There was a problem hiding this comment.
Code Snob — already tight. No rewrite.
Read packages/client/src/session-client/session-window.ts, session-history.ts, the root export in packages/client/src/index.ts, packages/client/test/session-window.test.ts, packages/node/test/client-session-tail.test.ts, and the README and API-page additions.
readSessionEarlier and refreshSessionWindow are already one reread. windowOf is the one snapshot-to-window map. The tail's first state() call is the size probe: readSessionHistory returns a finished read (hasMore: false, total = items held), so it cannot answer "how long is this?" unless it grows an option. The pager is useSession's loop plus offset, in the file the other history PR is meant to share. Folding it into the window module, or into useSession in this PR, moves those lines and leaves two loops.
A shared host helper next to client-own-sessions.test.ts would be new code for one say flow. Dropping the optional-field spreads in windowOf is about four lines and puts undefined keys on the window.
Left D1, D2, and E1–E7. Did not take the second look's page-size clamp, the tail's sessionCreatedAt restart, or the example rename.
Sent by Cursor Automation: Code Snob
…tem pages advance (FIX-2408) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NczDiDgwa4zZVeE3jwkDQL
…ths (FIX-2408) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NczDiDgwa4zZVeE3jwkDQL
…FIX-2408) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NczDiDgwa4zZVeE3jwkDQL
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d1f7bad547
ℹ️ 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".
…ropped from under it (FIX-2408) A retention policy drops a session's oldest turns without re-creating it, so a saved start can sit past the session's end or past items the window held. A re-read now checks it still holds the window's first item. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NczDiDgwa4zZVeE3jwkDQL
Mechanism check (advisory, never blocks)Rows from
|


Requested by Jake · project thread
Builds specs/issues/FIX-2408, merged in #4395.
What it does. This PR adds three functions to
@flow-state-dev/client:readSessionTailreads a session's newest 200 items.readSessionEarlieradds earlier items, for a Load earlier button.refreshSessionWindowreads the window again, from its start to the session's end.A
SessionItemsWindowholdsitems,start,total, andhasEarlier, plusatandsessionCreatedAtfor the session stream. Every read goes throughreadSessionHistory, the client's one paging loop. That is FIX-2374's function with anoffsetoption added. It is internal and not exported from the package root.The window starts over at the session's end in three cases:
Merge order with FIX-2374 (#4360). This PR adds
session-client/session-history.tsfirst. FIX-2374'sreadSessionHistoryis the same function withoutoffset, so whichever PR merges second keepsoffset(spec D2). This slice changes no app files. The Shift Manager adopts these functions in the wave-2 stack.Evidence
packages/node/test/client-session-tail.test.tsruns against a realserve()host with 1,051 stored messages. The tail's last item is the newest reply, and Load earlier reaches the first item with no gap. Control: starting the tail at offset 0, as the Shift Manager reads today, fails this check.session-window.test.ts(13 tests):session-history.test.ts(3 tests): restart on a moved history, the error once attempts run out, and a non-zero offset.sessionCreatedAtcomparison removed: 1 fails;pnpm --filter @flow-state-dev/client test: 197 passed. The new-dead-code check is clean against main, and CI is green.Docs and release
Updates the client README ("Reading a long session from its end") and the client API page (
readSessionTail). Adds apatchchangeset for@flow-state-dev/client.🤖 Generated with Claude Code
https://claude.ai/code/session_01NczDiDgwa4zZVeE3jwkDQL