Skip to content

refactor(claude-code-style): pins flow declares its user state schema - #4713

Open
jhoffner wants to merge 3 commits into
mainfrom
cleanup/pins
Open

jhoffner wants to merge 3 commits into
mainfrom
cleanup/pins

Conversation

@jhoffner

@jhoffner jhoffner commented Nov 4, 2026

Copy link
Copy Markdown
Collaborator

What

The lab's pins flow now declares its user state schema once and uses it everywhere:

  • userStateSchema ({ pinned: string[] }, defaulting to []) is passed to the flow's user.stateSchema, and to each handler as userStateSchema and outputSchema.
  • Handlers read ctx.user.state.pinned with its type. The pinnedOf(ctx) cast helper is gone.
  • defineFlow no longer needs the as never cast.

No behaviour change: the same actions (pin, unpin), the same read (listPins), and the same stored shape.

Why

We underuse userStateSchema across the codebase. This cleans it up in one place. We looked at larger simplifications here (client data in place of the read, a shared pins resource with a capability) and set them aside: none of them made this smaller.

Verification

  • pnpm --filter @flow-state-dev/claude-code-style typecheck: clean
  • pnpm --filter @flow-state-dev/claude-code-style test: 23 files, 159 tests passed

No changeset: labs/ is private.

🤖 Generated with Claude Code

Replaced the previous pins schema with a user state schema that defaults to an empty array for pinned items. Updated the pinsBlock handler and the definePinsFlow function to utilize the new schema for input and output, ensuring consistency in handling user state across the flow.
@vercel

vercel Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
flow-state-dev-build-site Ready Ready Preview Nov 5, 2026 8:10pm UTC
flow-state-dev-docs Error Error Nov 5, 2026 8:10pm UTC
2 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-kitchen-sink Ignored Ignored Nov 5, 2026 8:10pm UTC
flow-state-dev-ui Ignored Ignored Preview Nov 5, 2026 8:10pm UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 4, 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-04T21:33:59.735889Z eb1d3db 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 4, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (read-only; one file, +10/−8)

Verdict: right direction, small and worthwhile. No better approach to pursue; a few things to fix or verify before merge. I could not run tsc here (deps not installed in this sandbox), so the typing claims below are by reading, not execution.

Is there a better approach?

No. One schema declared once and handed to the flow's user.stateSchema and to each handler's userStateSchema is the intended typed-state path. It removes the pinnedOf cast helper and the as never on defineFlow, which is the point of the refactor. Not worth widening into anything else.

Needs attention

  1. Stray whitespace. pins.mts has a whitespace-only line after pinsBlock (+ , then a blank line). Lint/prettier will likely flag it. Delete it.
  2. ?? [] guard dropped without evidence (BP-030, BP-003). pinnedOf tolerated user state with no pinned key. ctx.user.state.pinned is now typed as always present, which holds only if the engine applies the schema .default([]) when reading already-persisted user state written before this field or schema existed. The type says yes; I have not seen it proven. Evidence path: run goals/realtime/app-views-read-on-notice/run.mts (it registers definePinsFlow()) and add or confirm a case that calls listPins/pin for a user with no prior state and for one with {} persisted. If the engine does not default on read, change(undefined, id) throws on .includes.
  3. as never removal is unverified. Please attach pnpm --filter typecheck output for labs/claude-code-style (and the goals typecheck, since it imports this file) in the PR. Sibling flows (projects.mts, harness-thread.mts) still carry as never. If pins now typechecks clean, that is useful evidence for the others, but do not touch them in this PR.

Minor / optional

  • Schema reuse couples two contracts. outputSchema: userStateSchema ties the wire response shape to the storage shape. They are identical today, so it is fine and less code. If either changes (e.g. state gains another key), the read response changes silently. Acceptable; a one-line comment saying the response intentionally mirrors state would pin the intent.
  • userStateSchema on every handler. Needed for ctx.user.state typing, so it is justified. It also makes the three repeated userStateSchema, lines the only repetition left. No further abstraction is warranted at this size.

Architecture opportunity

None to take in this PR. The unified-schema move is already the whole refactor. The only follow-up worth noting (separate issue, not here): the as never pattern across the other workforce flows suggests defineFlow's typing fights flows with reads; if pins typechecks without the cast, that narrows where the real typing gap is.

No changeset needed (lab, private).


Generated by Claude Code

@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

Read this as two layers: the pins typing refactor (what the title describes) and a much larger bundle (workforce defaults, DevTeam EM/harness, teammates coder brief, goals tsconfig, FIX-2490 spec amendments).

Pins (labs/claude-code-style/workforce/flows/pins.mts) — approach looks right

Hoisting userStateSchema, declaring it on handlers, reading ctx.user.state.pinned, and dropping pinnedOf + defineFlow(…) as never is the cleaner pattern the fundamentals docs and kitchen-sink already use. I would not go back to a local pinnedOf helper; that was the old escape hatch.

Optional nits only: reuse taskInput inside pinsBlock instead of re-inlining the same taskId schema, and trim the trailing whitespace on the blank line after pinsBlock.

Where complexity comes from (not the pins edit)

PR scope vs title — Most of the diff is unrelated to pins. That makes simplify review, bisect, and rollback harder. If this branch is intentionally a cleanup stack, a title/body that lists the bundled concerns (or splitting merges) would match what reviewers are actually signing off on.

Two hand-synced default-layer prompt slots — Exporting workerIdentityPrompt and calling it from em.mts is the right reuse vs copying strings. The cost is a duplicate lambda plus a “must change together” comment vs agent-worker-flow.ts (~1149), while the agent flow comment explicitly warns against widening into a compose helper before FIX-2498. A narrower middle ground (if you want less drift risk without FIX-2498): export something like workerIdentityPromptEntry(installation) that returns the same slot function both flows use — not a registry, just one callsite for the lambda shape. The new Lab integration test is a good enforcer either way; importing TOOL_USE_RULE (or a stable prefix) in shift-manager tests instead of re-stringifying the opener would tie assertions to workforce’s canonical text.

maxSteps default 50 — Simpler control flow than the old conditional spread (maxIterations: options.maxSteps ?? DEFAULT_MAX_STEPS). This is the main cost/latency knob in the PR (worst-case tool loops × prompt/tool resolution). Docs/changeset match intent; apps that relied on the old implicit cap need maxSteps: 8 explicitly.

Harness preset + tools — Moving to Claude Code’s preset: "claude_code" with append (ER-5) is the right simplification vs a plain string that replaced SDK behavior. Grep/Glob on the coder harness may add tool rounds; seems intentional for real coding work.

FIX-2490 spec/decision SVG churn — Substantive and fine, but orthogonal to pins; riding in the same PR increases review surface without simplifying runtime code.

Performance / reuse (parallel read-only pass)

No new busy-waits or obvious accidental N+1 in the diff. Identity string rebuild each loop step is pre-existing pattern, now on EM too; optional future cache if profiling says so.

Teammates vi.mock(… workerConfigOf …) duplicated across two test files — small DRY opportunity, not blocking.

Verdict

Pins: approve the direction. Whole PR: comment, not approve — not because the workforce/harness/teammates changes look wrong, but because the bundle + dual prompt-slot sync are the kind of complexity a simpler process or a tiny exported prompt-entry helper would reduce. I’m not requesting changes on merge if this stack is deliberate; the items above are what I’d simplify if tightening the diff.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

@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: f1a088e63b

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

Code Snob — already tight. No POC.

Head f1a088e63b5daab4b448049f1b84409d60992943. pins.mts, +10/−8. A rewrite leaves the same contract.

  • One schema, three slots. userStateSchema is the stored bag (user.stateSchema, .default([])), the handler context (userStateSchema types ctx.user.state), and the return (outputSchema). pinnedOf and the as never cast are already gone.
  • handler.withDefaults. A helper for { outputSchema: userStateSchema, userStateSchema } is four lines. It removes those two keys on pinsBlock and on listPins, also four lines. Tie, at two call sites.
  • taskInput. Same shape as the block's inputSchema. The action field is the optional override (runAction uses action.inputSchema ?? action.block.inputSchema). Dropping the const leaves the block schema and both action entries. harness in harness-thread.mts spells that override on the action and the block.
  • listPins. The read must not patchState. Folding it into pinsBlock adds a branch.

Files: labs/claude-code-style/workforce/flows/pins.mts, packages/core/src/blocks/handler.ts, packages/core/src/types/flow.ts, packages/engine/src/execution/runAction.ts, labs/claude-code-style/workforce/flows/harness-thread.mts.

Left as recorded: client data in place of the read, and a shared pins resource. Both were already set aside because they came out no smaller.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

The engine doesn't apply user.stateSchema's .default([]) to stored user
state, so a first pin read ctx.user.state.pinned as undefined and threw.
Keep the empty-pins fallback (pinnedOf), drop the action-level taskInput
override (the block's inputSchema is used), and cover a fresh user's
pin/unpin on the real engine.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jhoffner

jhoffner commented Nov 4, 2026

Copy link
Copy Markdown
Collaborator Author

Replies to the reviews on f1a088e; fixes are in eb1d3db.

Codex P1 (first pin throws): confirmed and fixed. Details are on the inline thread.

Cursor, Simplify review:

  • Applied: the taskInput reuse (the action override is removed) and the trailing whitespace.
  • Not applicable: the "much larger bundle" part. This PR is one file, pins.mts, so there's nothing here about workforce defaults, EM/harness or FIX-2490. That review seems to have read a different diff.

Cursor, Code Snob: no change. The review agrees nothing more is warranted.

Second look:

  1. Whitespace line: removed.
  2. Dropping ?? []: you were right to doubt it. The engine does not apply .default([]) to stored user state, so the fallback is back, and a real-engine regression test covers a fresh user.
  3. Removing as never: verified. pnpm --filter @flow-state-dev/claude-code-style typecheck is clean, goals tsc --noEmit exits 0 with no errors, and the lab tests pass: 24 files, 161 tests. The sibling flows are untouched.
  • outputSchema mirroring state: left as is, as you suggested.

Possible follow-up, outside this PR: user.stateSchema defaults aren't applied when a block reads ctx.user.state, but the types say the field is always there. That mismatch is an engine gap, not something specific to pins.

@jhoffner

jhoffner commented Nov 5, 2026

Copy link
Copy Markdown
Collaborator Author

Architect: not approving yet. The PR text says the pinnedOf cast helper is gone, but labs/claude-code-style/workforce/flows/pins.mts:19 keeps a pinnedOf fallback because the engine doesn't apply .default([]) to stored user state. That is the workaround the planned engine fix under FIX-2447 (scope state applies schema defaults) is meant to delete. Either land after that fix and drop pinnedOf, or have Jake accept this as an interim step and correct the PR text, and this unblocks.

— FSD Architect

# Conflicts:
#	labs/claude-code-style/workforce/flows/pins.mts
@jhoffner

jhoffner commented Nov 6, 2026

Copy link
Copy Markdown
Collaborator Author

This PR acts as an example of how we should be leveraging typed schemas more so that we don't need ugly helper methods that bloat the codebase and make things more complicated to read then they need to be. However I'm putting on hold until we both decide what to do with #4820 and the "CRUD flow" issue, as well as wait for the #4800 spec to be implemented.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Keeping this on hold. We are about to do a large "Kit" addition which might break this PR, but its an example we will keep for when we do a large refactor. Now that we support proper defaults within schemas, we can likely update dozens (hundreds maybe) of instances in the codebase that use helper methods where they should rely on schema defaults and proper usage of schema like how userStateSchema does here.

This branch had an error being deployed

1 failed deployment
Preview – flow-state-dev-docs — 67339bfb Deployed Nov 5, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants