Skip to content

FIX-1788 P2: the worker model, beside today's - #2856

Merged
jhoffner merged 9 commits into
mainfrom
fix/FIX-1788-p2
Oct 7, 2026
Merged

jhoffner merged 9 commits into
mainfrom
fix/FIX-1788-p2

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 7, 2026 •

Copy link
Copy Markdown
Collaborator

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 readonly workerId and 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 calls resolveWorker, 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. createWorkforceClient finds 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"]
Loading

It is proved on a fixture worker flow registered once. Every existing flow, agent included, 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 agent drawer is kept per worker through it.

One behaviour change ships here, as the coordinator decided: writeShared names the worker the turn resolved, not a seatId setting. Until P4 moves agent onto the model, an entry written by a copy minted per worker names the user alone.

Parts worth reviewing closely

  1. packages/workforce/src/workers/installation.ts, the one module for S5, S6 and S8. Callers reach the create check, resolveWorker and session(), never the row, the name resolution or the refusals.
  2. Per-turn resolution goes through 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.
  3. Attribution reads a verified worker, not state. resolveWorker marks the request's session handle, and writeShared reads that mark. A flow that isn't a worker flow can hold a workerId a caller wrote; it never signs.
  4. The roster session isn't at a derived id. The client can't know its organization before it has a session, so it lists the user's roster sessions and creates one without an id when there are none. Two first calls at once may create two; either reads the same roster. Worker-session ids do include the organization, read off that session.
  5. workforce may now import client (scripts/validate-package-boundaries.mjs), for createWorkforceClient. 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

How to review this. This implements an approved spec — the approach and the numbered
decisions in its DECISIONS.md are already signed off by a human, so please review the
code against that direction, not the direction itself. The canonical set is retained
at specs/issues/FIX-1788/ on main; Linear links to it and the original merged spec
PR, which keeps review history. Follow-up amendment PRs explain later direction changes.
Current architecture docs remain the authority for shipped behavior (BP-037).

Most valuable here: correctness on the second path (the legacy shape, the null
boundary, the concurrent case, the cancel path), anything deriving an auth or routing
decision from caller-controllable input, and a behaviour the tests assert around
rather than on.

Already settled upstream: the approach and every decision in the spec's DECISIONS.md
(human-approved — if one is wrong, say so as a spec finding and it gets folded back; don't
re-argue it inline), and the conventions in docs/contributing/best-practices.md.

Engineering calls
  • A worker that isn't yours gets the 404 a missing one gets (BR-11). The check reads only the caller's own scope, so Bob's row isn't there to find.
  • A derived id is reserved for its user. A create at an id with the 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.
  • Skills are names. A user's worker names skills resolved per turn against the installation's skills: skills if 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.
  • Documents are narrowed per turn as 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. Wiring reaches into the agent generator's tools and context is P4, with agent.
  • The roster flow (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.
  • The wake and the worker lookup name the worker at create. The wake's child gets state: { workerId } from the seat it chose, and createWorkerLookup(...).state names the task's assignee. Both reach today's minted copies too, which keep the field as plain state and never sign with it.
  • The agent drawer partition reads the session's 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.
  • FIX-1789's goal now runs its sharer on the worker model, since the leg asserts the worker an entry names; its log has a control that fails leg b with the attribution removed.
Everything else

Verification (BP-003). Each check was seen failing with the behaviour it covers removed.

Rule Evidence Red state
BR-10, 11, 12, 13, 14, 15 · the create check, and a turn naming a worker packages/workforce/test/worker-sessions.test.ts Flow mismatch allowed, or another user's worker read as found: fails
BR-13a, 13b, 14a, 16, 19b · find and ensure worker-sessions.test.ts Derived-id check removed, or a moved worker's turn allowed: fails
BR-1 to 7, 9, 19c, 20, 22, 22a, 24 · hire, fork, edit, fire, per-turn configuration, grants, two hosts packages/workforce/test/worker-roster.test.ts Hire not checked: 3 fail; fork following the files, fired worker running, standard-only ignored: each fails
BR-18 · a task opens its worker's session naming it packages/workforce/test/worker-dispatch.test.ts; the wake in wake-member-seats.test.ts Lookup or wake naming no worker: fails
BR-23, Workforce half · one drawer per worker on one agent copy packages/workforce/test/agent-drawer-by-worker.test.ts; packages/orchestration/test/skills/partition.test.ts Partition removed: fails
BR-25a · two workers sign as two; a non-worker flow signs as nobody whatever its settings or a caller's state say packages/workforce/test/shared-resource.test.ts; the FIX-1789 goal Reading the caller's state: fails; reading no worker: the goal fails leg b

Run locally on this head: pnpm typecheck, the docs build, the workforce suite (1458) and the orchestration suite (1670), all passing, and goals/worker-contract/runs-workers-only-on-registered-flows/run.mts PASS.

Not in this PR. S10 (one copy per flow, agent first), 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: workforce may not import react.

Docs. README sections in workforce ("Workers as data", the export table) and orchestration (partitionBy), and the attribution sentence in apps/docs/docs/workforce/workers-on-disk.md. The user-facing pages in DOCS.md publish 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: minor for workforce (new API, and writeShared's attribution change), patch for 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 session workerId, create check, per-turn resolveWorker), roster hire/fork/edit/fire blocks, defineWorkerRosterFlow, and browser createWorkforceClient with derived wks_ session ids. writeShared now stamps writtenBy.workerId from the turn's verified resolveWorker result, not seatId; hired-seat writes still record { userId } only. Mailbox wakes and task dispatch seed child sessions with workerId for worker flows.

Orchestration adds partitionBy on skills libraries so multiple parties on one flow copy get separate skill catalogs (used for per-worker drawers); all skills reads go through resolveSkillsCollection.

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.

claude added 8 commits October 7, 2026 19:05
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
@vercel

vercel Bot commented Oct 7, 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 Oct 7, 2026 9:15pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 7, 2026 9:15pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 7, 2026 9:15pm UTC

Request Review

@cursor

cursor Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot 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)

@jhoffner
jhoffner marked this pull request as ready for review October 7, 2026 21:00
@cursor

cursor Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot 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)

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

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.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

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

  1. Turn resolution: mint() calls full hireWorkforce([manifest], …) on every resolveWorker (and configurationProblems). 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.”
  2. Partition views: skills/partition.ts duplicates tasks/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 for ResourceCollectionRef semantics.
  3. Identity ladder: createCheck and resolveWorker repeat own-row vs standard vs flow-match logic — a single internal lookup would be easier to keep in sync.
  4. Client: flowOf paginates both roster collections on every ensureWorkerSession / findWorkerSession; memoizing roster or a single-row read would simplify call sites that only need worker → flow.

What I’d keep as-is (not over-engineered)

  • WorkerInstallation vs scattering create check + collections.
  • derive-session-id + create-check binding for derived session ids.
  • worker-model-harness weight — it’s the right tier for this contract.
  • Adding @flow-state-dev/client on workforce (orchestration was already a dep); workers/ staying core-only except client.ts is 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.

Open in Web View Automation 

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

cursor Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot 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)

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