Repository navigation
FIX-1788 P2: the worker model, beside today's - #2856
Conversation
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Brings in P1's state-based binding (readonly session-state fields,
createSession({ state }), listSessions({ state })) in place of the link.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Brings in P1's docs-editor commit. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
A worker is a row its owner holds in user scope (workforce/workers/*), or a standard worker the installation's files declare, projected read-only. A session names its worker once, in a readonly `workerId` session-state field, and the worker flow's create check confirms it: the creating user's own or a standard worker, on this flow, and a derived worker-session id only for its own user. Each turn loads the worker with `resolveWorker`, which resolves its configuration through the hire step without registering anything, refuses a fired, moved or unresolvable worker, and says which documents it reaches. - createWorkerInstallation: the create check, resolveWorker, the session declaration and the two worker collections a worker flow spreads in. - createWorkerHireBlocks: hire, fork (copies the configuration and shared instructions), edit and fire, each a checked write to the caller's roster. - defineWorkerRosterFlow and createWorkforceClient: read the roster through a roster session, and find or start a session with a worker at a derived id. - writeShared names the worker the turn resolved, never a setting or state. - The wake and the worker lookup name the worker when they create its session; the agent drawer is kept per worker through the skills library's per-run partition. Proved on a fixture worker flow registered once; every existing flow still mints per worker. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Documents createWorkerInstallation, the hire blocks, the roster flow and createWorkforceClient in the workforce README, the skills library's partitionBy in the orchestration README, and writeShared's attribution in the workers-on-disk page. FIX-1789's goal runs its sharer flow on the worker model, since writeShared now names the session's worker rather than a seatId setting, with a control that fails leg b when it names none. resolveWorker takes any block's context. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Brings in P1 (#2850) as merged, and main since. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: 11ade820-f2bb-41a6-b679-6cea133f47d1) |
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: c4214ac1-dfb2-4886-a8b5-a1f7594eb738) |
There was a problem hiding this comment.
Code Snob — already tight. No POC.
I read packages/workforce/src/workers/installation.ts, hire-blocks.ts, client.ts, worker-row.ts, standard-workers.ts, derive-session-id.ts, keys.ts, verified-worker.ts, roster-flow.ts, the refusal throw in packages/workforce/src/hire.ts, packages/orchestration/src/skills/partition.ts, and packages/orchestration/src/tasks/collection/partition.ts.
The create check and resolveWorker walk the same row-or-file lookup, but the sentences are the contract: a missing row is a 404 at create and "was fired" on a turn, and a flow move is a different sentence in each place. A shared loader keeps both message sets, so the lines move rather than disappear. Hire, fork, edit, and fire already share refuseStandard, check, write, and readOwn. The four executes are different writes.
partition.ts matches the task-ledger partition only up to what this catalog needs. Skill keys nest (name/SKILL.md), the view rewrites its pattern so a reader that strips the prefix still gets the skill key, and partitionBy is synchronous over the block context. partitionedResourceCollection rejects a nested id and keeps the inner pattern. A generic with those flags is larger than the copy.
The open criteria object (S5a), the derived wks_ id, and resolving a turn by minting through hireWorkforce and dropping the instance are already recorded. The file split is the boundary: client.ts and derive-session-id.ts stay off hire, and verified-worker.ts stays off the installation so writeShared does not import the model.
A rewrite would not shrink the contract.
Sent by Cursor Automation: Code Snob
There was a problem hiding this comment.
Simplify review (FIX-1788 P2)
P2 adds a real worker model (roster rows + session-bound workerId + create check + turn resolution + client) beside today’s seat hire. After reading the diff and running parallel simplify/perf/reuse passes, the shape looks right: createWorkerInstallation as the single façade, workers/ split by caller (installation / hire-blocks / client / roster-flow), and reusing hireWorkforce for validation instead of a second mint grammar are all sensible. The ~2.7k lines are mostly tests and harness, which is appropriate for engine-level contracts.
I don’t think the epic needed a smaller feature — it needed this surface. The complexity that does feel like “approach went one step too far” is mostly how two existing mechanisms are reused on hot paths, not that too many modules exist.
Cleaner alternative (if you revisit before kitchen-sink wiring)
- Turn resolution:
mint()calls fullhireWorkforce([manifest], …)on everyresolveWorker(andconfigurationProblems). That re-runs flow validation and seat materialization even though nothing is registered. A narrower internal API — e.g. “parse manifest → seat config + reaches” with hire’s rules factored once at installation build — would shrink per-turn CPU and make the mental model clearer than “drop the instance after hire.” - Partition views:
skills/partition.tsduplicatestasks/collection/partition.ts(~WeakMap view cache + encoded segment + proxied CRUD). One shared helper in orchestration (hooks for task-only direct-child filtering vs skills prefix pattern) would cut drift risk; there’s no npm package forResourceCollectionRefsemantics. - Identity ladder:
createCheckandresolveWorkerrepeat own-row vs standard vs flow-match logic — a single internal lookup would be easier to keep in sync. - Client:
flowOfpaginates both roster collections on everyensureWorkerSession/findWorkerSession; memoizing roster or a single-row read would simplify call sites that only needworker → flow.
What I’d keep as-is (not over-engineered)
WorkerInstallationvs scattering create check + collections.derive-session-id+ create-check binding for derived session ids.worker-model-harnessweight — it’s the right tier for this contract.- Adding
@flow-state-dev/clienton workforce (orchestration was already a dep);workers/staying core-only exceptclient.tsis clean.
Integration gap (doc / follow-up, not a revert)
defineAgentWorkerFlow now sets skills partitionBy from session workerId, but unlike the harness it doesn’t spread installation.session() (readonly state + create check). Until hosts wire installation, partitioned drawers depend on callers seeding workerId without engine enforcement on the stock agent kind. Worth calling out in README or making installation an explicit option on the agent flow factory.
Skipped (defer / product call)
- Merging seat-hire blocks and worker-hire blocks.
- Moving partition helpers to core without a design pass on list/pattern differences.
- Per-step skills
list()cost (pre-existing tool-loop pattern; partition doesn’t fix it).
Verdict: Direction approved. Highest-value simplify follow-ups: per-turn hireWorkforce, partition DRY, and client roster churn. None of these block merge for P2 if you’re explicitly trading correctness/reuse for perf until the next slice.
Sent by Cursor Automation: Review For Best Approach
…w and docs findings (FIX-1788 P2) - A partitioned skills library gives a run whose partitionBy returns undefined an empty catalog it can't write, instead of the bucket every partition lives in. Tested to fail with the old read. - agent's drawer is no longer partitioned by session state in P2: on a copy that doesn't bind workerId, that is caller-written state (BP-031). A test pins that a seeded workerId picks no partition; the drawer moves to per-worker partitions in P4. - One shared worker lookup for the create check and a turn, each keeping its own refusals; ensureWorkerSession reads the roster once per call; the per-turn mint says why it reuses the hire (about 0.13 ms a turn). - createWorkforceClient is exported from ./browser only. - Docs: who writeShared records, per setup; the worker model's README with a client example, the hire blocks' inputs and outputs, recovery for each refused turn, and per-worker data on a custom worker flow (Q6); "Partitioning a library" in the orchestration README. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: 258aa7bb-9667-46cc-902d-9948b00bc774) |


The problem
Today a worker is a registered copy of a flow. Every hire mints one, pins it to its owner, and registers it in the process that made it, so another process doesn't see the hire until it restarts, and a fired worker keeps answering there. The workforce epic needs a worker to be data instead: a row its owner holds, run by one shared copy of the flow it names, so a hire, fork or fire is a write that every process reads on its next turn. P1 (#2850, merged) gave a flow a way to name something once, when a session is created, and never change it. This PR builds the worker model on top of that, beside today's.
What this does
A worker is a row in its owner's user scope (
workforce/workers/<id>, per organization), or a standard worker the installation's files declare, projected read-only for everyone. A worker flow declares a readonlyworkerIdand Workforce's create check. The check confirms the worker is the creating user's own or a standard one, and that it runs on this flow. Each turn callsresolveWorker, which loads the worker and resolves its configuration through the hire step without registering anything. It refuses a worker that was fired, moved to another flow, or names something this process doesn't register. Hire, fork, edit and fire are checked writes to the caller's roster.createWorkforceClientfinds or starts a session with a worker, at an id derived from the user, organization, flow and worker, so two calls at once get one session.flowchart LR A["app · createWorkforceClient"] -->|"roster · ensureWorkerSession"| C{"create check · own or standard · on this flow"} C -->|"refused"| R["4xx · nothing written"] C -->|"accepted"| S["session · readonly workerId"] S --> T["each turn · resolveWorker"] T --> W["the user's row, or a standard file"] W -->|"resolved per turn"| F["the flow's one copy runs it"]It is proved on a fixture worker flow registered once. Every existing flow,
agentincluded, still mints a copy per worker; the switch is P4.What's asked of you
Nothing to decide on direction: this implements P2 of the approved spec (FIX-1788), as the product owner reshaped it on #2850 (binding through readonly initial state).
Waiting on: S7's generic half (product owner Q6). Whether every flow-isolated resource on a custom worker flow is keyed by the worker. This PR builds only the Workforce-owned half: the skills library takes its partition per run, and the built-in
agentdrawer is kept per worker through it.One behaviour change ships here, as the coordinator decided:
writeSharednames the worker the turn resolved, not aseatIdsetting. Until P4 movesagentonto the model, an entry written by a copy minted per worker names the user alone.Parts worth reviewing closely
packages/workforce/src/workers/installation.ts, the one module for S5, S6 and S8. Callers reach the create check,resolveWorkerandsession(), never the row, the name resolution or the refusals.hireWorkforce([manifest])and drops the minted instance. One path for "what does this worker run with", so a hire, a turn and a save refuse the same things in the same words. The cost is a mint per turn, uncached.resolveWorkermarks the request's session handle, andwriteSharedreads that mark. A flow that isn't a worker flow can hold aworkerIda caller wrote; it never signs.workforcemay now importclient(scripts/validate-package-boundaries.mjs), forcreateWorkforceClient. The client imports only core and contracts, so no cycle is added.Links: spec
specs/issues/FIX-1788/· FIX-1788 · epic FIX-1786 · stack: P2 of three; P1 (#2850) merged; P4 (the switch) builds on this. Merges.How to review this
Engineering calls
wks_prefix is refused with a 403 unless it is the caller's own derivation (BR-13b). The id is a SHA-256 over user, organization, flow and criteria, computed with Web Crypto so the browser and the server agree.skillsif given, else every skill a standard worker sees, the first standard worker in id order winning a name two hold. A fork copies the standard worker's skill names, instructions and team instructions (D3); a later file edit changes neither the instructions nor the names it holds.reaches(accessor), from the same grants and reference wall a hire applies. A document a block declares itself is handed to every worker, so a worker flow keeps its documents at flow level, as the hire step already requires. Wiringreachesinto theagentgenerator's tools and context is P4, withagent.workforce-roster) declares the two worker collections and takes no create check, so a client reads the roster over the existing collection routes. One roster session per user per organization; an app listing every flow's sessions filters that kind.state: { workerId }from the seat it chose, andcreateWorkerLookup(...).statenames the task's assignee. Both reach today's minted copies too, which keep the field as plain state and never sign with it.workerId. On today's minted copies no create check confirms it, so a caller who seeds one splits only their own drawer within their own cell.Everything else
Verification (BP-003). Each check was seen failing with the behaviour it covers removed.
packages/workforce/test/worker-sessions.test.tsworker-sessions.test.tspackages/workforce/test/worker-roster.test.tspackages/workforce/test/worker-dispatch.test.ts; the wake inwake-member-seats.test.tsagentcopypackages/workforce/test/agent-drawer-by-worker.test.ts;packages/orchestration/test/skills/partition.test.tspackages/workforce/test/shared-resource.test.ts; the FIX-1789 goalRun locally on this head:
pnpm typecheck, the docs build, the workforce suite (1458) and the orchestration suite (1670), all passing, andgoals/worker-contract/runs-workers-only-on-registered-flows/run.mtsPASS.Not in this PR. S10 (one copy per flow,
agentfirst), S11's switch of the lookup to new-model workers, S12 (Shift Manager), S14 removals, S15 goals and apps, S16 docs and the VG goal are P4. The React hook over the client (useWorkforce) isn't built:workforcemay not importreact.Docs. README sections in workforce ("Workers as data", the export table) and orchestration (
partitionBy), and the attribution sentence inapps/docs/docs/workforce/workers-on-disk.md. The user-facing pages inDOCS.mdpublish with P4. I can't dispatch the docs-writer or docs-editor agents from here; I wrote these myself.Changeset.
.changeset/workforce-worker-model.md:minorfor workforce (new API, andwriteShared's attribution change),patchfor orchestration (partitionBy).🤖 Generated with Claude Code
https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Generated by Claude Code
Note
High Risk
Adds session create checks, derived session id reservation, roster writes, and changes shared-resource attribution—security- and audit-sensitive paths exercised on the real engine but coexisting with legacy hire until P4.
Overview
Introduces the worker-as-data model alongside today's per-hire flow copies: workers live in user-scoped roster rows (or as read-only standard workers from files), while one registered worker flow serves every worker that names it.
Workforce adds
createWorkerInstallation(readonly sessionworkerId, create check, per-turnresolveWorker), roster hire/fork/edit/fire blocks,defineWorkerRosterFlow, and browsercreateWorkforceClientwith derivedwks_session ids.writeSharednow stampswrittenBy.workerIdfrom the turn's verifiedresolveWorkerresult, notseatId; hired-seat writes still record{ userId }only. Mailbox wakes and task dispatch seed child sessions withworkerIdfor worker flows.Orchestration adds
partitionByon skills libraries so multiple parties on one flow copy get separate skill catalogs (used for per-worker drawers); all skills reads go throughresolveSkillsCollection.Docs, FIX-1789 goal/sharer fixture, and broad integration tests cover sessions, roster rules, dispatch, attribution, and partitioning. Package boundaries allow
workforce→client.Reviewed by Cursor Bugbot for commit 7c765ab. Configure here.