Skip to content

feat(client): read a long session from its newest end (FIX-2408) - #4510

Merged
jhoffner merged 5 commits into
mainfrom
claude/project-thread-sxkinr
Nov 2, 2026
Merged

jhoffner merged 5 commits into
mainfrom
claude/project-thread-sxkinr

Conversation

@jhoffner

@jhoffner jhoffner commented Nov 2, 2026 •

Copy link
Copy Markdown
Collaborator

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:

  • readSessionTail reads a session's newest 200 items.
  • readSessionEarlier adds earlier items, for a Load earlier button.
  • refreshSessionWindow reads the window again, from its start to the session's end.

A SessionItemsWindow holds items, start, total, and hasEarlier, plus at and sessionCreatedAt for the session stream. Every read goes through readSessionHistory, the client's one paging loop. That is FIX-2374's function with an offset option added. It is internal and not exported from the package root.

The window starts over at the session's end in three cases:

  • the session is re-created under the same id;
  • older turns are dropped by a retention policy;
  • the session is re-created between the tail's two calls.

Merge order with FIX-2374 (#4360). This PR adds session-client/session-history.ts first. FIX-2374's readSessionHistory is the same function without offset, so whichever PR merges second keeps offset (spec D2). This slice changes no app files. The Shift Manager adopts these functions in the wave-2 stack.

Evidence

  • Goal check: packages/node/test/client-session-tail.test.ts runs against a real serve() 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.
  • Unit, session-window.test.ts (13 tests):
    • a reply first read half-written shows finished on refresh;
    • an item stored behind the newest one appears on refresh;
    • a read restarts when the session moves under it;
    • a session re-created under the id (during a refresh, or between the tail's two calls) starts over at its end;
    • dropped older turns start the window over;
    • a one-item limit still reaches the newest item.
  • Unit, session-history.test.ts (3 tests): restart on a moved history, the error once attempts run out, and a non-zero offset.
  • Controls fail:
    • refresh only from the old end: 3 tests fail;
    • the overlap check removed: 2 fail;
    • the first-item check removed: 2 fail;
    • the probe's sessionCreatedAt comparison removed: 1 fails;
    • the minimum page size of 2 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 a patch changeset for @flow-state-dev/client.


🤖 Generated with Claude Code

https://claude.ai/code/session_01NczDiDgwa4zZVeE3jwkDQL

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
@vercel

vercel Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

4 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Nov 2, 2026 12:34am UTC
flow-state-dev-kitchen-sink Ignored Ignored Nov 2, 2026 12:34am UTC
flow-state-dev-ui Ignored Ignored Preview Nov 2, 2026 12:34am UTC
flow-state-dev-build-site Skipped Skipped Nov 2, 2026 12:34am UTC

Request Review

@linear-code

linear-code Bot commented Nov 2, 2026

Copy link
Copy Markdown

FIX-2408

@jhoffner jhoffner self-assigned this Nov 2, 2026
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-02T00:36:00.403218Z e7af961 New commits
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

jhoffner commented Nov 2, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass

Verdict: 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 tail/descending option would remove the two-call tail read and the discarded first page, but D2 rejected it for this slice. Nothing in the diff argues for revisiting that.

Findings (most useful first)

  1. Silent truncation in readSessionHistory when pageLimit < 2 (session-history.ts, the nextOffset - 1 <= offset break). The loop steps one item back for the overlap check. With a page size of 1 and hasMore: true, it breaks and returns a result stamped hasMore: false and total = start + items.length. That reads as a complete history but isn't. readSessionTail(…, { limit: 1 }) is a public path to this when the session grows between the two calls. useSession's original loop never had this case. Suggested fix: clamp pageLimit to at least 2 (or reject smaller values) and throw instead of breaking if the page can't advance. Add a test.

  2. Session re-created between the tail's two calls (session-window.ts, readSessionTail). start is computed from the first call's total, but the second read can come from a new session. If the new session is shorter, the window comes back with items: [], start > total, and hasEarlier: true. reread handles re-creation, but readSessionTail doesn't compare sessionCreatedAt across its own two calls. Rare. Cheap to guard: compare the two sessionCreatedAt values and restart once.

  3. The tail's first call discards a full page for long sessions. It reads 200 oldest items just to learn total, and for any long session that payload is thrown away. The spec accepts this, trading one extra payload for a single call on short sessions. If it shows up in the Shift Manager's adoption, a cheaper probe can go in later without changing the API. Leave it for now.

  4. Refresh cost grows with every Load earlier. reread asks for window.total - start + 200 items in one request, so a window grown to 1,000+ items re-reads all of them on each refresh. D1 chose this knowingly. The Shift Manager's 5-second poll will feel it until FIX-2409 lands. Worth a line in the adoption PR, not a change here.

  5. Docs nit. The README and API examples name the variable window, which shadows the browser global in the code these examples are meant for. Rename to view or tail. Cosmetic.

Architecture (only where this PR is the opportunity)

  • Duplicate paging loop. session-history.ts is a copy of the loop inlined in packages/react/src/hooks/useSession.ts (fetchSessionSnapshot). The spec makes this deliberate, and spec: a session feed any app can follow, without React (FIX-2374) #4360 is meant to move useSession onto it. So don't refactor useSession here. Make sure whichever PR merges second keeps offset and deletes the inline copy. Two paging loops must not survive both merges. The PR body says this, and I'd keep it as a merge-time check.
  • No other consolidation is warranted. The new window module is a small function set over Pick<SessionsApi, "state">, the same shape as readEveryCollectionPage. Don't add abstractions beyond that.
  • Out of scope here, by design: the Shift Manager's run.ts readSessionItems and send.ts sessionHoldsLine are the two copies this replaces. They are deleted in the wave-2 adoption PR, not this one.

No changes needed to the changeset or the test layout.


Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 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".

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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 bespoke from_end route (FIX-877 cost deferred). Tail-first probe + second read from total - limit matches Shift Manager’s today pattern and generalises sessionHoldsLine in the adoption PR.
  • Directory layout (session-client/session-window.ts + internal session-history.ts, mirroring readEveryCollectionPage) 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:

  1. #4472 — workspace / harness-manager / fsdev / worktrees (~5.7k lines)
  2. FIX-2429 — retained spec + POC
  3. 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.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

Open in Web View Automation 

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

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 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
@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Mechanism check (advisory, never blocks)

Rows from docs/mechanisms/mechanisms.yaml · labels: none

New export Package Mechanism
readSessionTail @flow-state-dev/client client
readSessionEarlier @flow-state-dev/client client
refreshSessionWindow @flow-state-dev/client client

@jhoffner
jhoffner merged commit 0554e0b into main Nov 2, 2026
21 checks passed
@jhoffner
jhoffner deleted the claude/project-thread-sxkinr branch November 2, 2026 00:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants