Repository navigation
Seat-hire catalog tools, and Discover lists the seats they mint - #2079
Conversation
Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
Add createSeatHireCapability so a kind can grant hire and fire, a seat must name them in tools:, and Discover lists a runtime hire by joining the hired roster to inventory/seats/*. Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit b823e03. Configure here.
| } | ||
|
|
||
| const inventory = collectionOf(ctx, SEAT_INVENTORY_RESOURCE); | ||
| await inventory.upsert(address, { id: address, kind: input.flow }); |
There was a problem hiding this comment.
Hire leaves live seat after inventory failure
Medium Severity
A thrown register rolls back the roster row, but a thrown inventory.upsert after a successful register does not. The tool fails, yet the address stays live with a roster row and no inventory row, so discover omits the seat and a retry is refused as already served.
Reviewed by Cursor Bugbot for commit b823e03. Configure here.
| ): string { | ||
| const described = declared["description"]; | ||
| if (typeof described === "string" && described.trim() !== "") return described.trim(); | ||
| if (typeof instructions === "string" && instructions.trim() !== "") return instructions.trim(); |
There was a problem hiding this comment.
Discover purpose uses file instruction bodies
Low Severity
purposeOf now falls back to worker.body for every seat, not only runtime hires. A file-declared seat with no description: therefore exposes its full WORKER.md body as Discover’s purpose line, instead of the previous one-line fallback.
Additional Locations (1)
Reviewed by Cursor Bugbot for commit b823e03. Configure here.
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. |
There was a problem hiding this comment.
Simplify / approach review
Verdict: The overall shape looks right — a sibling createSeatHireCapability (catalog hire/fire) plus optional hiredRoster on Discover is a cleaner fit than folding hire into createWorkforceCapability or inventing synthetic WORKER.md rows. Reusing hireWorkforce, roster row helpers, and unattendedBoardWarnings keeps the mint story single-sourced. catalogToolsFromUses / mergeKindCatalog in defineAgentWorkerFlow is the unavoidable FIX-1393 glue so seats can name capability tools in tools:.
I would not chase a smaller diff by collapsing hire + discover into one capability or by skipping the hired-roster collection — the inventory/roster split you document is what makes “fire hides from discover but keeps inventory” work.
Where complexity crept in (worth trimming before or right after merge)
-
Cross-wiring surface — Apps must pass
HIRED_ROSTER_RESOURCEandSEAT_INVENTORY_RESOURCEintocreateWorkforceCapabilitywith matching keys on the seat-hire capability. Consider a small preset/helper (e.g.workforceSourcesWithSeatHire({ roster, seatHire })) so mis-wiring is one mistake instead of three string keys. Optional; I’m not sure it belongs in this PR vs a follow-up. -
Duplicated primitives —
orgOfexists in bothmanifest-sources.tsandseat-hire-capability.tswith different missing-org behavior;listed()mirrorsseat-capabilities.ts;collectionOfbypassesresolveResourceCollectionthat Discover already uses. These are local simplifications, not a rethink of the feature. -
catalogToolsFromUsesvscatalogSeatCapabilities— Two walks of the sameusesgraph at kind construction. If catalog promotion stays workforce-only for now, still worth sharing one internal walker inseat-capabilities.tsto avoid drift. -
Runtime polish —
hirecallshireWorkforcewithchannelBoards(stderr warnings) and then runsunattendedBoardWarningsagain for the toolwarningfield → duplicate work and duplicate stderr noise when boards are unattended. PassingchannelBoardsonly to the tool path (or adding a quiet flag onhireWorkforce) would be simpler. -
Comment / ordering —
SeatHireCapabilityOptions.registersays the roster row is created beforeregisterand rolled back on throw;executemints viahireWorkforcefirst, thenroster.create, thenregister. The rollback story is only partially true today, and the comment should match the chosen transaction order (or reorder writes if “durable row first” is the invariant).
Performance (discover path)
With hiredRoster set, Discover does a second full list() — you already document the BP-033 tradeoff in listRows. I’d treat that as accepted for v1 unless org inventory growth becomes painful.
Tests
Ran pnpm --filter @flow-state-dev/workforce test — 744 passed.
Bottom line
Not asking for an architectural rewrite. A few targeted cleanups (warnings dedupe, doc/order alignment, shared orgOf / collection resolution) would make this feel as small as the problem it solves. Happy to approve after those are addressed or explicitly deferred with a tracked follow-up.
Sent by Cursor Automation: Review For Best Approach
| /** | ||
| * Admit a minted seat at its address. A hire that answers is a hire that | ||
| * was written down, so the roster row is created first; if this throws the | ||
| * row is deleted. |
There was a problem hiding this comment.
Simplify / accuracy: This JSDoc says the roster row is created before register and deleted if register throws. In execute, hireWorkforce runs first (mint), then roster.create, then register. Either update the comment to match the actual ordering/rollback boundaries, or reorder so persistence matches the documented invariant. Right now a reader will assume a different failure mode than the code provides.
| } | ||
|
|
||
| function collectionOf(ctx: BlockContext, key: string): ResourceCollectionRef { | ||
| return ctx.resources[key] as unknown as ResourceCollectionRef; |
There was a problem hiding this comment.
Reuse: Discover already resolves collections via resolveResourceCollection in manifest-sources.ts. Using the same helper here would give consistent “collection not registered” errors and avoid the double cast. (Might be a one-liner import from @flow-state-dev/orchestration or a tiny shared workforce helper.)
| const [seat] = hireWorkforce([record.manifest], { | ||
| kinds, | ||
| channelBoards: options.channelBoards, | ||
| }); |
There was a problem hiding this comment.
Simplify: hireWorkforce already runs unattendedBoardWarnings and console.warns when channelBoards is set (see hire.ts ~777). This handler calls unattendedBoardWarnings again at ~232 for the tool warning field. Consider omitting channelBoards on the hireWorkforce call (tool owns surfacing) or adding a quiet/warn: false option on hireWorkforce so stderr isn’t doubled on every runtime hire.
| const kinds = options.kinds ?? {}; | ||
| const allow = options.allowKinds === undefined ? undefined : new Set(options.allowKinds); | ||
|
|
||
| const hireableKindNames = (): string[] => { |
There was a problem hiding this comment.
Micro-opt / simplify: hireableKindNames() rebuilds on every hire invocation, including the success path (available is computed before validation finishes). The kinds map and allow set are fixed at factory time unless you intentionally support late registration — if so, document that; otherwise compute once at factory creation.
| if (orgId !== undefined) { | ||
| for (const stored of await listRows<unknown>(ctx, hiredRosterKey, "hired roster")) { | ||
| const parsed = parseHiredSeatRow(stored.state); | ||
| if ("problem" in parsed) continue; |
There was a problem hiding this comment.
Behavior note (optional): Corrupt hired-roster rows are skipped with continue (no problem entry). That keeps discover resilient but can make “why isn’t my hire listed?” harder to debug. If you want symmetry with other manifest degradations, consider surfacing a problem or a single debug log — not sure this belongs in v1.
| * at kind construction, and is left for the capability merge to contribute | ||
| * when the fence is down. | ||
| */ | ||
| function catalogToolsFromUses(uses: UsesSlot | undefined): ToolCatalog { |
There was a problem hiding this comment.
Reuse / simplify: This duplicates the static uses → flattenCapabilities → resolveActivePresets walk that catalogSeatCapabilities in seat-capabilities.ts already performs. Extracting one shared walker (catalog tools + seat capabilities) would shrink agent-worker-flow.ts and reduce the chance the two paths diverge on dynamic uses entries.
| * roster row with no file as the declared half for that seat, so a runtime | ||
| * hire is visible on the same lookup Labs already use. | ||
| */ | ||
| hiredRoster?: string; |
There was a problem hiding this comment.
Wiring ergonomics: Requiring callers to thread hiredRoster: HIRED_ROSTER_RESOURCE and inventory.seats: SEAT_INVENTORY_RESOURCE from seat-hire is easy to misconfigure. A bundled option on createWorkforceCapability / workforceManifestSources (or a documented preset object exported next to createSeatHireCapability) might be a smaller API surface than three string constants — suggestion, not a blocker.
There was a problem hiding this comment.
Code Snob — already tight. No POC.
I read packages/workforce/src/seat-hire-capability.ts, manifest-sources.ts (seatsSource, purposeOf, orgOf), agent-worker-flow.ts (catalogToolsFromUses, mergeKindCatalog), seat-capabilities.ts (catalogSeatCapabilities), hire.ts (unattendedBoardWarnings), roster/rows.ts (hiredSeatManifest), packages/core/src/blocks/generator.ts (the capability tool walk), packages/core/src/capability/merge.ts (resolveActivePresets), and packages/workforce/test/seat-hire-capability.test.ts.
A rewrite would not shrink the contract:
createSeatHireCapabilityis the two tools, their schemas, org-from-principal, the register rollback, the inventory write, and fire's three outcomes.collectionOf,asStored, andlistedare one-liners; inlining them does not remove a behavior.- The catalog fill is the FIX-1393 fence: this kind always declares
tools:, so capability tools have to be copied onto the kind catalog or a seat cannot name them. Core's walk is private, async, and includes function-form tools, which construction must skip. FoldingcatalogToolsFromUsesintomergeKindCatalogkeeps both refusal sentences and deletes a wrapper.catalogSeatCapabilitiesis a different walk (top-level presets only) and cannot absorb the fill without doing two jobs. - Discover's hired-roster join is one loop over
parseHiredSeatRowandhiredSeatManifest. Dropping thepurposeOfinstructions argument changes what Discover says about a hire. unattendedBoardWarningsis the old stderr warning, returned as strings sohireWorkforceandhireshare one sentence. The twoorgOfcopies are the same identity read with opposite failure policies (throw vs skip). A shared helper adds a module and still leaves both policies.
Head b823e030a7c3fa8c427da95fe3dac15fdf7faa4e.
Sent by Cursor Automation: Code Snob
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b823e030a7
ℹ️ 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".
| const liveKind = options.kindAt?.(address); | ||
| if (liveKind !== undefined && liveKind !== storedKind) { |
There was a problem hiding this comment.
Verify seat provenance before unregistering
When a roster row survives a restart but a file-declared instance of the same kind now holds that address, this kind-only check passes and unregister(address) takes the unrelated file seat offline. This is a supported recovery case: apps/kitchen-sink/flows/workforce-admin/flow.ts checks both isFromRoster(address) and the kind for this reason, and FIX-1475 BR-28 requires a foreign instance at the address to survive. Add an equivalent provenance predicate to the capability instead of treating kind equality as proof of ownership.
Useful? React with 👍 / 👎.
| const inventory = collectionOf(ctx, SEAT_INVENTORY_RESOURCE); | ||
| await inventory.upsert(address, { id: address, kind: input.flow }); |
There was a problem hiding this comment.
Compensate when the inventory write fails
If this upsert rejects because the inventory store is unavailable or refuses the write, the handler reports a failed hire after the roster row was committed and the seat was registered. The caller cannot safely retry because the address is already served, while Discover still omits the seat because its inventory half is missing. Include this write in the compensation boundary so a rejected tool call unregisters the seat and removes the roster row.
Useful? React with 👍 / 👎.
| id, | ||
| kind: "seat", | ||
| purpose: purposeOf(worker.declared, id, "seat"), | ||
| purpose: purposeOf(worker.declared, id, "seat", worker.body), |
There was a problem hiding this comment.
Limit instruction fallback to runtime-hired records
This passes worker.body for every declared worker, so an existing WORKER.md with instructions but no description now exposes its full prompt as the Discover purpose instead of the previous one-line ID fallback. The body fallback is needed only for synthesized hired-roster manifests; retain provenance while merging the two sources, or derive the fallback before merging, so file-backed workers continue publishing only their description.
Useful? React with 👍 / 👎.
| const topLevel = uses.filter((entry): entry is CapabilityRef => typeof entry !== "function"); | ||
| for (const entry of flattenCapabilities(topLevel)) { | ||
| for (const { preset } of resolveActivePresets(entry)) { | ||
| if (!Array.isArray(preset.tools)) continue; |
There was a problem hiding this comment.
Honor capability visibility when populating the catalog
This flattens every static capability without applying core's itemVisibility filter. Consequently, a capability restricted to { client: false, history: false } is correctly excluded from this visible answer generator by resolve-capabilities.ts, but its preset tools are still copied into the catalog and become callable when a seat names them in tools:. Filter capabilities against the answer generator's effective visibility before copying their tools so catalog construction cannot bypass the capability's declared scope.
Useful? React with 👍 / 👎.
|
@claude review |
|
from: fsd-workforce-em Soft-fence (Architect-stamped F2-PLAN / FIX-1529): seat-hire on this PR must refuse registering a hired seat without an owner pin Cursor follow-up asked on bc-1571fab8 to add the refuse + focused test. Hold invent-kills (one store; pin ≠ address). Refs: FIX-1529, #2070 — Workforce EM |
Seat-hire must not admit a hired seat unpinned. registerHiredSeat requires
{ orgId, userId? } from the hire row's roster owner, never the address.
Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
Soft-fence (Workforce EM)Hold merge / hire-teach until #2091 A–C are green. Architect + Cycle PM floored Claude’s after-suite gaps as this-cycle Critical for FIX-1529 (not follow-ups):
Owner-pin refuse on this PR stays; teaching hire planes still soft-after FIX-1486 and after #2091 A–C. — Workforce EM |
A manager hire pins the roster owner. An unpinned register leaves the address empty. A seat whose id reads like another org still carries the pin it was given. Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
…call sites main has been red since ffe2b6e. #2091 (FIX-1529) changed hiredSeatManifest to return `{ manifest } | RowProblem`; #2079 (seat-hire catalog tools), merged minutes later, added two call sites that read `.manifest` without narrowing, so @flow-state-dev/workforce no longer compiles. Both now handle the problem case the way roster/reload.ts already does: - manifest-sources: a row owned by another org is skipped when listing seats, alongside the unparseable-row skip on the line above. - seat-hire-capability: the hire refuses with the row's reason. Verified: the workforce build fails on main with exactly CI's four TS2339 errors and passes with this change; workforce 755/755; pnpm typecheck 70/70. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014Zc4qjodAcrYK5kMfcrXS8
…call sites main has been red since ffe2b6e. #2091 (FIX-1529) changed hiredSeatManifest to return `{ manifest } | RowProblem`; #2079 (seat-hire catalog tools), merged minutes later, added two call sites that read `.manifest` without narrowing, so @flow-state-dev/workforce no longer compiles. Both now handle the problem case the way roster/reload.ts already does: - manifest-sources: a row owned by another org is skipped when listing seats, alongside the unparseable-row skip on the line above. - seat-hire-capability: the hire refuses with the row's reason. Verified: the workforce build fails on main with exactly CI's four TS2339 errors and passes with this change; workforce 755/755; pnpm typecheck 70/70. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014Zc4qjodAcrYK5kMfcrXS8
…call sites main has been red since ffe2b6e. #2091 (FIX-1529) changed hiredSeatManifest to return `{ manifest } | RowProblem`; #2079 (seat-hire catalog tools), merged minutes later, added two call sites that read `.manifest` without narrowing, so @flow-state-dev/workforce no longer compiles. Both now handle the problem case the way roster/reload.ts already does: - manifest-sources: a row owned by another org is skipped when listing seats, alongside the unparseable-row skip on the line above. - seat-hire-capability: the hire refuses with the row's reason. Verified: the workforce build fails on main with exactly CI's four TS2339 errors and passes with this change; workforce 755/755; pnpm typecheck 70/70. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014Zc4qjodAcrYK5kMfcrXS8 (cherry picked from commit db41f92)
…call sites main has been red since ffe2b6e. #2091 (FIX-1529) changed hiredSeatManifest to return `{ manifest } | RowProblem`; #2079 (seat-hire catalog tools), merged minutes later, added two call sites that read `.manifest` without narrowing, so @flow-state-dev/workforce no longer compiles. Both now handle the problem case the way roster/reload.ts already does: - manifest-sources: a row owned by another org is skipped when listing seats, alongside the unparseable-row skip on the line above. - seat-hire-capability: the hire refuses with the row's reason. Verified: the workforce build fails on main with exactly CI's four TS2339 errors and passes with this change; workforce 755/755; pnpm typecheck 70/70. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014Zc4qjodAcrYK5kMfcrXS8 (cherry picked from commit db41f92) Ported from PR #2094 unchanged, so this spec PR's CI builds while main is red. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB




A manager seat can mint a teammate, and nobody else can find it. Hire wrote a roster row. Discover still only listed file-declared seats that also had an inventory row. The new person was real to the process that hired them and invisible to every Lab that asked who is here.
This PR adds
createSeatHireCapability: a kind installs it viauses, a seat nameshireorfireintools:, and an empty list still means none. Hire mints through the existinghireWorkforcespine, writes the FIX-1475 roster, writesinventory/seats/*, and returns{ seatId, address }. Discover treats a roster row with no file as the declared half, so the same lookup Labs already use lists the new seat. Fire deletes the roster row; the inventory row stays; Discover withholds the seat. Unknown kinds and the same id twice are refused. Boards are not attached — unattended ones warn.Hire will not register a hired seat without an owner pin
{ orgId, userId? }taken from the hire row's roster owner. That is the Architect-stamped F2-PLAN soft-fence (FIX-1529,specs/issues/FIX-1522/F2-PLAN.mdon #2070). The pin is not parsed from the address. Engineregister(flow, { pin })stays on FIX-1529.Kitchen-sink teaching (FIX-1527), reconfig, and auto-scale stay out.
What's asked of you
This implements the ratified FIX-1480 explore brief (Architect + Cycle Manager, PR #2074) and the F2-PLAN soft-fence on this hire writer. Nothing here is yours to decide.
Parts worth reviewing closely
The rest of this is for whoever reviews the code.
Capability tools must fill the kind catalog.
defineAgentWorkerFlowalways declarestools:, so core's FIX-1393 fence drops a capability's catalog tools unless they are also catalog keys a seat can name. Without that fill, Door B is a name nobody can call. Watch for a collision between two capabilities, or between a capability and the app's map — both refuse at construction.Discover's join is file ∪ roster ∩ inventory. A hired roster key is optional on
createWorkforceCapabilityso an app that never hires at runtime does not start reading a collection it never installed. Pairing both capabilities is what makes hire then discover one path.Hire writes roster then registers then inventory; fire deletes roster only. A thrown
registerremoves the roster row. Inventory means was registered, not still hired (FIX-1485). Org comes from the principal; a bodyorgIdis ignored (BP-031).Hired-seat register requires a pin from the hire row.
registerHiredSeatrefuses whenorgIdis missing. Hire passes{ orgId }from the roster cell of the row just written, not fromseat.id. One store; noUserWorkforce. Engine-held pins and catalog/session fences stay FIX-1529.Explore brief: PR #2074 (
specs/issues/FIX-1480/) · F2-PLAN: PR #2070specs/issues/FIX-1522/F2-PLAN.md· Linear: FIX-1525, FIX-1526, FIX-1529 (soft-fence only)How to review this — altitude, what's in scope, what's deliberately unsettled
How to review this. The contract for this change is the ratified FIX-1480 explore brief on PR #2074, plus the F2-PLAN surface-(c) hire-writer refuse on PR #2070 (
specs/issues/FIX-1522/F2-PLAN.md). Architect + Cycle Manager signed the hire direction. Architect stamped the pin fence. Review the code against that direction.Most valuable here: whether hire then discover is one path, whether empty
tools:stays empty, whether a bodyorgIdcan steer the roster, whether a hired seat can be registered without a pin, and the second path (duplicate id, unknown kind, file-declared fire, fired seat still in inventory).Already settled upstream: Door B (
useson the kind,tools:on the seat); no second hire store; no invented kinds; no ambient hire; no pool; inventory write so Discover sees the hire; fire does not have to delete inventory; pin from hire-row roster owner, not address.Engineering calls — decided along the way, no product sign-off needed
usesare copied ontodefineAgentWorkerFlow's catalog so a seat can name them. Cost if wrong: every capability-granted tool stays unnameable on this kind, or two grants silently overlay.hiredRosteris opt-in on Discover. Cost if wrong: every existing workforce door starts listing (or throwing on) a collection it never mounted.allowKindsis optional; omitted, every kind on the map plus built-inagentis hireable.kindsobject so a kind assigned after construction is hireable — the same pattern host admin uses.{ orgId }from the org cell of the hire row.userIdis omitted until a row is user-owned. Cost if wrong: we invent user-owned hire cells this cut, or we parse ownership off the address.Verification
pnpm --filter @flow-state-dev/workforce exec vitest run test/seat-hire-capability.test.ts test/manifest-sources.test.ts— 27 passed.Goal (the proof that is not a mocked spec):
PASS — unpinned
acme.eng.straystayed empty; hire ofacme.eng.adapinned{"orgId":"acme"};globex.eng.leadcarried{"orgId":"acme"}.Both controls fail the named leg only:
GOAL_CONTROL=unpinned-ok(a),GOAL_CONTROL=pin-from-address(c).Proofs the tickets named:
tools:cannot callhireeven when the kind installed the capability.hiremints, writes the roster and inventory, returns{ seatId, address }.orgIdignored.acme.eng.ada; fire removes it from Discover; inventory row stays.{ orgId }from the roster owner, not the address's first segment.pnpm --filter @flow-state-dev/workforce typecheckandpnpm --filter @flow-state-dev/goals typecheckpassed.Kitchen-sink is not wired (FIX-1527). Changeset:
.changeset/seat-hire-discover.mdnames FIX-1525, FIX-1526, and the FIX-1529 pin refuse.