Skip to content

fix: container renderers empty under documented composition - #2080

Closed
jhoffner wants to merge 7 commits into
mainfrom
cursor/session-items-provider-flow-15a6
Closed

jhoffner wants to merge 7 commits into
mainfrom
cursor/session-items-provider-flow-15a6

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

An adopter who copies FlowProvider + Conversation + ItemsRenderer and drops in EventedActors, Debate, or RoutedSpecialists gets a blank card. Those renderers read useSessionItems(), which is [] unless a provider is mounted, and FlowProvider never mounts one.

ItemsRenderer now mounts SessionItemsProvider with the list it is already rendering. The documented stack is unchanged. Copied registry session-items-context re-exports the same context from @flow-state-dev/react. TaskPlan's items prop stays as the out-of-stream escape hatch.

What's asked of you

Nothing here is yours to decide. The mount point (ItemsRenderer, not a second provider on every app) was the locked direction. This PR is the review gate.

Parts worth reviewing closely

This is for the code reviewer. The weak spot is the copied file: an adopter who already has a local session-items-context.tsx still has a different context until they re-add that component. Kitchen-sink copies were left alone (FIX-1455).

Links: Fixes FIX-1498 · Closes #2020

How to review this — altitude, what's in scope, what's deliberately unsettled

How to review this. This is a bug fix on the direct route: there is no spec and no spec PR, because the hard part was the diagnosis and it happened in code. This PR is the only gate, so unlike a spec-backed change, the approach is in scope — nothing here was signed off upstream.

Most valuable here: the diagnosis chain — does the repro actually reproduce the reported failure, is the named cause the real one, does the fix address that cause rather than the symptom, and does the regression test fail without the fix? Then the second path (the legacy shape, the null boundary, the concurrent case, the cancel path).

In scope to challenge: where the guard was placed, any behaviour change a user could notice, and whether this should have been a spec'd feature instead of a fix.

Engineering calls — decided along the way, no product sign-off needed
  • Mount from ItemsRenderer, not FlowProvider. FlowProvider has no item list; useSession lives below it. Wrong call costs a second items prop on every app or a session subscription inside FlowProvider.
  • Re-export the react context from the registry file instead of keeping a local createContext. A second context would leave copied cards reading [] even after the mount.
  • No items prop on EventedActors / Debate / RoutedSpecialists. TaskPlan keeps its existing escape hatch.
  • Kitchen-sink copies not updated. That rebuild is FIX-1455.
  • ItemsRenderer return type is now ReactNode (one provider root) instead of ReactNode[].
Verification

Regression packages/react/test/items-renderer-session-items.test.ts failed without the provider wire (Unable to find [data-testid="container-probe"], empty body) and passed after ItemsRenderer wrapped with SessionItemsProvider value={props.items}.

pnpm --filter @flow-state-dev/react test — 26 files, 220 passed.
pnpm --filter @flow-state-dev/react typecheck — exit 0.
pnpm --filter @flow-state-dev/ui test — 9 files, 61 passed.
pnpm --filter @flow-state-dev/ui typecheck — exit 0.

fix-1498-regression-red-green.log

No changeset needed for @flow-state-dev/ui (private). Patch changeset on @flow-state-dev/react for the new exports and the ItemsRenderer behavior.

To show artifacts inline, enable in settings.

Open in Web Open in Cursor 

cursoragent and others added 3 commits September 23, 2026 02:12
Document that ItemsRenderer puts its items array in scope for nested
useSessionItems consumers, and that SessionItemsProvider is only for
cards rendered outside that helper.

Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
Drop the receipt/reload and matching-item sentences. State that
useSessionItems reads the list ItemsRenderer already scopes.

Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
Container renderers call useSessionItems() and render nothing under the
documented FlowProvider + ItemsRenderer stack. FlowProvider has no item
list; ItemsRenderer already does, so it mounts the provider. The registry
session-items-context re-exports the react context so copied cards share it.

Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
@vercel

vercel Bot commented Sep 23, 2026 •

Copy link
Copy Markdown

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

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 23, 2026 8:51pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 23, 2026 8:51pm UTC
flow-state-dev-ui Ignored Ignored Preview Sep 23, 2026 8:51pm UTC

Request Review

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

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 41c50ff. Configure here.

cursoragent and others added 2 commits September 23, 2026 19:32
The drift check requires installed flow-state components to stay
byte-identical with the registry source. Copy the re-exported
session-items context and the Approval comment that matches it.

Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
ItemsRenderer was replacing any outer SessionItemsProvider with its own
items. RequestGroup passes a list that already dropped task-owned items,
so TaskPlan expansions read that subset and rendered empty. Mount the
provider only when none is already in scope.

Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
@jhoffner jhoffner closed this Sep 23, 2026
@jhoffner jhoffner reopened this Sep 23, 2026
@jhoffner
jhoffner marked this pull request as ready for review September 23, 2026 20:45
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 23, 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-10-31T22:58:35.933555Z 2c70def Manual request
ℹ️ 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.

@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-1498)

Verdict: approve. The diagnosis is right (registry-local createContext ≠ provider on the react tree), and the fix is about as small as it can be without changing every container renderer API.

Did this go too far?

I looked for a materially simpler path:

Alternative Why it doesn’t beat this PR
Document “always wrap SessionItemsProvider” Fixes the guide, not the default FlowProvider + ItemsRenderer stack; easy to miss.
Mount on FlowProvider No item list there without coupling to useSession; wider API.
Pass items into Debate / EventedActors / RoutedSpecialists Large registry churn; TaskPlan already has an escape hatch; hooks are the established pattern.
Always nest a provider inside ItemsRenderer Breaks RequestGroup → filtered ItemsRenderer + full-list TaskPlan (your second regression test).

The extra moving part (SessionItemsGate + null sentinel) is not accidental complexity—it is the minimum way to auto-wire the common case and preserve an ancestor superset. That directly answers the earlier “filtered list hides task-owned items” concern: gate skips nesting when a provider is already mounted.

Canonical context in @flow-state-dev/react + registry/kitchen-sink re-export is the right boundary (same story as SuspensionResolver, but with a copied hub file because siblings import ./session-items-context). No new third-party package buys anything here.

Optional cleanups (non-blocking)

These are polish, not merge gates:

  1. SessionItemsGate is exported but only used by ItemsRenderer and not re-exported from the package entry—consider making it module-private so it stays an implementation detail.
  2. JSDoc overlap between the module header, SessionItemsProvider, useSessionItems, SessionItemsGate, and ItemsRenderer repeats the same composition story; could mirror SuspensionResolver.ts (one narrative block, short per-symbol lines).
  3. useSessionItems() fallback ?? [] allocates a fresh empty array when no provider is mounted; a module-level EMPTY_ITEMS constant would stabilize referential identity for misconfigured trees/tests (minor).
  4. Story wrappers that wrap both SessionItemsProvider and ItemsRenderer with the same full list are now redundant in many cases; trimming them later would reduce noise (keep stories that model ancestor-full + filtered-child).
  5. Confirm ui registry build runs in CI so public/r picks up the re-export (source is correct; built artifacts are easy to drift).

Performance (skipped as merge blocker)

Putting session.items in context means every useSessionItems() consumer re-renders when useSession replaces the sorted array reference—same model kitchen-sink already used with a page-level provider. Worth knowing for long sessions + many container cards; selectors or getOwnedItems-style context would be a follow-up, not this bugfix.

What landed well

  • Regression test encodes both the empty-card bug and the ancestor-superset invariant.
  • props.items (unfiltered) on the gate while buildItemRenderStream filters for display is the correct split for suspensions + owned snapshots.
  • Static ui test guarding against reintroducing a second createContext is a cheap, worthwhile guardrail.

No changeset concern from this review; the react patch fragment matches the public surface change.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

* Used by {@link ItemsRenderer}. A filtered `items` prop must not hide a
* fuller list an ancestor already provided.
*/
export function SessionItemsGate(props: {

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 (optional): SessionItemsGate looks like an ItemsRenderer implementation detail. It is not on index.ts, but export function still invites deep imports. Dropping export (or colocating the gate next to ItemsRenderer) would keep the public API to SessionItemsProvider / useSessionItems only.

* Reads the nearest session item list, or `[]` when no provider is mounted.
*/
export function useSessionItems(): OutputItem[] {
return useContext(SessionItemsContext) ?? [];

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 (optional): ?? [] creates a new array on every call when no provider is mounted. A shared const EMPTY_ITEMS: OutputItem[] = [] (used only for the missing-provider case) avoids surprising memo deps in misconfigured trees. Not an issue on the happy path where ItemsRenderer or an ancestor provider is present.

return createElement(ItemRenderer, { item, key: item.id });
});

return createElement(SessionItemsGate, { value: props.items }, nodes);

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.

Using props.items here (not the filtered stream) is the right call—container/HITL hooks need owned snapshots and suspension pairing from the same array you pass in, while SessionItemsGate ensures you do not replace a fuller ancestor list. Worth keeping that invariant obvious in code review because it is easy to “simplify” incorrectly to stream items.

* when rendering stream-aware cards outside `ItemsRenderer`.
*/
export {
SessionItemsProvider,

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.

Re-export-only file is the right fix for duplicate context identity. If you want one more simplify pass later: stories that wrap the same full list in both SessionItemsProvider and ItemsRenderer can drop the outer provider now that the gate exists—except stories that intentionally model ancestor-full + filtered-child (RequestGroup / TaskPlan).

@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 — too small to shrink. No POC.

I read packages/react/src/context/SessionItemsContext.ts, packages/react/src/components/ItemsRenderer.ts, packages/react/src/context/SuspensionResolver.ts (the sibling provider), packages/react/test/items-renderer-session-items.test.ts, packages/ui/registry/components/session-items-context.tsx, packages/ui/test/session-items-context.test.ts, and the README / docs edits that correct the old “wrap it yourself” instructions.

The contract is: ItemsRenderer supplies props.items only when nothing is mounted, an explicit SessionItemsProvider can still set a list, useSessionItems() is [] when absent, and the registry file re-exports that one context.

SessionItemsGate is the extra piece past SuspensionResolverProvider, and it has to stay a separate check. The null sentinel is not the same as [] (an empty list is a real mounted value), and putting the check inside SessionItemsProvider would make a nested provider a no-op. Inlining the gate into ItemsRenderer only moves those lines into the function that already groups the stream and matches suspension resumes.

The registry file is a re-export. The kitchen-sink copy is the byte-identical twin the drift check requires. The source-text test is the pin that the re-export does not grow a second createContext.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

…provider-flow-15a6

Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>

@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: 0d98c4b023

ℹ️ 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".

Comment on lines +69 to +70
const mounted = useContext(SessionItemsContext) !== null;
if (mounted) return props.children ?? null;

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Let nested renderers establish their own session scope

When a child or background session's <ItemsRenderer items={child.items}> is nested beneath a provider for the parent session, this presence-only gate keeps the parent's list. Stream-aware renderers in the child then cannot find child-owned container snapshots or suspension-resume items, producing empty or unresolved cards. This is a normal composition for the child-session detail documented in packages/react/README.md; preserve an ancestor only when it represents the same stream, or provide an override for the nested renderer.

Useful? React with 👍 / 👎.

Comment on lines +55 to +56
export function useSessionItems(): OutputItem[] {
return useContext(SessionItemsContext) ?? [];

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Reuse a stable empty items array

When useSessionItems() is called without a provider, this expression allocates a new array on every render. A consumer that treats the returned list as a dependency—for example, an effect that updates derived state—will observe a change on every render and can enter a render/effect loop even though the item list remains empty; memoized derivations also recompute unnecessarily. Return a shared empty constant or use a stable context default.

Useful? React with 👍 / 👎.

Discover and seat hire read .manifest on a result that may be a
RowProblem, which fails the workforce build. Skip a roster row owned
by another org, and surface that reason when a hire cannot mint.

Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>

@jhoffner jhoffner left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Architect call — #2080

Verdict: change-request. FIX-1498 approach is coherent with the locked mount (ItemsRenderer + gate + registry re-export); ancestor-superset regression is the right guard. Blocker: this branch also ships workforce hire/manifest cross-org skips unrelated to the PR title/body — strip or split those before merge. Nested child-session under a parent provider remains a known gate limit (non-blocking follow-up).

Not owner approval / not the merge gate.

— FSD Architect

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Keep it up!

Reviewed commit: 2c70defe9e

ℹ️ 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".

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: not approving yet. The branch has merge conflicts with main, and two current Codex P2 threads are unanswered: packages/react/src/context/SessionItemsContext.ts:70 (a nested ItemsRenderer for a child session can't set its own session scope under a parent provider) and SessionItemsContext.ts:56 (?? [] makes a new array each render without a provider). Unblock: merge main in, fix or answer both threads and resolve them, and keep CI green.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. More of your lovely PRs please.

Reviewed commit: 2c70defe9e

ℹ️ 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".

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Swish!

Reviewed commit: 2c70defe9e

ℹ️ 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".

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Swish!

Reviewed commit: 2c70defe9e

ℹ️ 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".

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

1 similar comment
@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: 2c70defe9e

ℹ️ 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".

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Nice work!

Reviewed commit: 2c70defe9e

ℹ️ 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".

@jhoffner

jhoffner commented Nov 5, 2026

Copy link
Copy Markdown
Collaborator Author

Closing per Jake. This has gone stale (merge conflicts), and Codex's P2 on nested child sessions was never fixed. The bug is still open and is now tracked in FIX-1498, refreshed with the chosen direction, the same-session check for nested renderers, and a stable empty array.

— FSD Architect

@jhoffner jhoffner closed this Nov 5, 2026
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.

Container renderers (EventedActors, Debate, RoutedSpecialists) render nothing when the documented FlowProvider composition is followed

2 participants