Skip to content
7 changes: 7 additions & 0 deletions .changeset/conversation-work-project.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
"@flow-state-dev/workforce": minor
---

A user's own conversation with a worker can work in a project (FIX-2161). `createWorkforceClient(...).setWorkProject(worker, { visibility, id }, { sessionId? })` sets it on the user's default conversation with the worker, or on another session of theirs with it, such as a new session just created. The conversation's coding runs, and the tasks it files from then on, work in that project through `projectWorkspace()`. A later call replaces the project; tasks already filed keep the one they were filed in.

The call is refused, storing nothing, for a project the user isn't a member of (a private one: isn't theirs), and on the project coordinator's, a task's, a delegate's or a workstream lead's session. It runs the `setWorkProject` action (`SET_WORK_PROJECT_ACTION`), which the agent, coordinator and Error Reporter flows declare; an app's own worker flow declares `setWorkProjectAction` under that name. The project is kept in the server-owned session field `workProjectId` (`WORK_PROJECT_STATE_KEY`), which a session create can't seed.
49 changes: 46 additions & 3 deletions apps/docs/docs/workforce/projects.md
Original file line number Diff line number Diff line change
Expand Up @@ -631,10 +631,10 @@ harnessManager({
`projectWorkspace` finds the project a run works in, in this order:

1. The workstream the task came from, when it was filed from one.
2. The project the task came from, when it was filed from a project's conversation.
3. The project the task names in `input.project`, by its visibility and id, when it came from a conversation that belongs to no project, such as the user's own coordinator.
2. The project the task came from, when it was filed from a project's conversation, or from a conversation [set to work in a project](#setting-the-project-a-conversation-works-in).
3. The project the task names in `input.project`, by its visibility and id, when it came from a conversation with no project, such as the user's own coordinator until it's set to one.

A task filed from a workstream or a project's conversation is stored naming that project, whatever the filer put in `input.project`. A worker filing from one is told which project it works in, so it doesn't have to name one.
A task filed from a workstream, a project's conversation or a conversation set to a project is stored naming that project, whatever the filer put in `input.project`. A worker filing from one is told which project it works in, so it doesn't have to name one.

The run is refused, before any file is read, when:

Expand All @@ -657,6 +657,49 @@ A coordinator filing for a coding worker from a conversation with no project nam

Put `projectWorkspaceCapability` on the harness manager's `uses`, as in the example above.

### Setting the project a conversation works in

A user's own conversation with a worker can be set to work in one of their projects. From then on, its coding runs and every task it files work in that project, so nobody has to name it in `input.project`. Set it from the app with the workforce client's `setWorkProject`:

```ts
import { createSessionClient } from "@flow-state-dev/client";
import { createWorkforceClient } from "@flow-state-dev/workforce/browser";

const workforce = createWorkforceClient({ userId, baseUrl, fetcher });
const sessions = createSessionClient({ baseUrl, fetcher });
// A worker's one conversation, at the first job that needs files
await workforce.setWorkProject("lead", { visibility: "shared", id: "apollo" });
// A new session, after the user picks a project
const session = await sessions.createSession({ flowKind: "lab-main", userId, state: { workerId: "main" } });
await workforce.setWorkProject("main", { visibility: "shared", id: "apollo" }, { sessionId: session.id });
```

Without `sessionId`, it sets the user's default conversation with that worker, creating the conversation if there isn't one. With `sessionId`, it sets that session, which must be the user's own. It resolves to `{ project: { visibility, id } }`. A new session takes two calls, as above: create it, then set its project. A create that puts `workProjectId` in `state` is refused with a 400 naming the field.

Calling it again with another project replaces the first. Tasks already filed keep the project they were filed in, including one still waiting on the board for a delegate and one handed to a delegate's ongoing session, along with whatever that delegate files while working it. A run that has already started stays where it is. There's no way to clear the project: once set, the conversation always has one.

The worker flows the package ships take the call as they are: `agent`, `coordinator` and the [Error Reporter](./error-reporter.md)'s flow. A worker flow of your own declares the action under its name:

```ts
import { SET_WORK_PROJECT_ACTION, setWorkProjectAction } from "@flow-state-dev/workforce";

defineFlow({
// ...
actions: { respond, ...board.actions, [SET_WORK_PROJECT_ACTION]: setWorkProjectAction },
});
```

A refused call rejects with an `Error` whose message starts `Refused:`, and nothing is stored:

| Refused when | The message says |
|---|---|
| The project is shared and the user isn't one of its members | `not-a-member` |
| The user has no private project with that id | `you have no private project "<id>"` |
| The organization has no shared project with that id | `this organization has no project "<id>" you can read` |
| The session is a project coordinator's, a task's, a delegate's or a workstream lead's | Which of those it is. Each of them works in the project it was created, filed or opened in. |

Membership is checked again on every run, so a user removed from the project can't run work there through a conversation set to it earlier. A project coordinator's conversation gets its project from `ensureWorkerSession({ worker, projectId })`, as in [Talking to a project](#talking-to-a-project).

### Tools a project's coding work gets

A project can name MCP servers, and every coding run on the project can use their tools. MCP, the Model Context Protocol, is how an agent reaches a tool outside its checkout: an issue tracker, a docs search, a database. A run gets the project's servers however the work reached it: from a workstream, from the project's conversation, or from a task that names the project.
Expand Down
51 changes: 43 additions & 8 deletions packages/workforce/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -415,7 +415,10 @@ own worker when it is hired or edited.
A worker flow declares the installation's session (`session: installation.session()`), so every
session names its worker in a readonly `workerId`, checked when the session is created, and loads
that worker on every turn with `installation.resolveWorker(ctx, flowKind)`. `hireWorkforce` refuses a
worker flow that doesn't declare it.
worker flow that doesn't declare it. The same session state (`installation.sessionStateShape`)
carries `workProjectId` (`WORK_PROJECT_STATE_KEY`), the project a user set their own conversation
to work in, as `<visibility>/<id>`. Only the `setWorkProject` action writes it, and a create that
seeds it is refused with a 400 naming the field (see [Projects](#projects)).

A worker takes a user's message through its flow's **door**: the one public action the flow
declares with `userMessage` and a `{ message }` input. `openInventory` writes it on the worker's
Expand Down Expand Up @@ -1488,10 +1491,11 @@ defineFlow({ kind: "projects", actions: { ...projects.actions, ...workstreams.ac
the repository of the project the run works for, with the project's files beside the checkout, or
the project's files alone when it has no repository. A run in a workstream's session, or a task
session filed from one, works for that workstream, and is refused `not-the-owner` when the run's
owner isn't the workstream's. A task session filed from a project's conversation works in that
project, and one filed from a conversation with no project works in the project its task names
as `input.project`, for that project's members only (`not-a-member`). A task filed from a
workstream or a project's conversation that names a project in `input.project` is filed naming
owner isn't the workstream's. A task session filed from a project's conversation, or from a
conversation set to a project with `setWorkProject`, works in that project, and one filed from a
conversation with no project works in the project its task names as `input.project`, for that
project's members only (`not-a-member`). A task filed from a workstream, a project's conversation
or a conversation set to a project that names a project in `input.project` is filed naming
that conversation's project instead, and a worker filing there is told that project in its
task tools' context, so it has no project to name. `no-project` when none applies. The block that asks it
must hold `projectWorkspaceCapability`; with harness-manager, pass it on `uses`:
Expand All @@ -1504,6 +1508,35 @@ defineFlow({ kind: "projects", actions: { ...projects.actions, ...workstreams.ac
});
```

- **`setWorkProject`**, on the workforce client, sets the project one of the user's own
conversations with a worker works in. From then on its coding runs, and every task it files, work
in that project, as for a project's conversation above:

```ts
const workforce = createWorkforceClient({ userId, baseUrl, fetcher });
const sessions = createSessionClient({ baseUrl, fetcher }); // from @flow-state-dev/client
// A worker's one conversation, at the first job that needs files
await workforce.setWorkProject("lead", { visibility: "shared", id: "apollo" });
// A new session, after the user picks a project
const session = await sessions.createSession({ flowKind: "lab-main", userId, state: { workerId: "main" } });
await workforce.setWorkProject("main", { visibility: "shared", id: "apollo" }, { sessionId: session.id });
```

Without `sessionId` it sets the user's default conversation with the worker, creating it if
there is none. With one, it sets that session, which must be the user's. It resolves to
`{ project }`. Calling it again replaces the project. Tasks already filed keep the project they
were filed in, including one still waiting on the board and one handed to a delegate's ongoing
session, with what that delegate files while working it. A run already started stays where it
is. Nothing clears it. A
refusal rejects with an `Error` whose message starts `Refused:`, and nothing is stored: a shared
project the user isn't a member of (`not-a-member`), a private project that isn't theirs or a
project that doesn't exist, and a project coordinator's, a task's, a delegate's or a workstream
lead's session, each named. Membership is checked again on every run. The action is
`setWorkProject` (`SET_WORK_PROJECT_ACTION`, input `{ project: { visibility, id } }`): the
`agent`, `coordinator` and Error Reporter flows declare it, and a worker flow of your own adds
`[SET_WORK_PROJECT_ACTION]: setWorkProjectAction` to its `actions`. A project coordinator's
conversation takes its project from `ensureWorkerSession({ worker, projectId })` instead.

- **`projectMcpTools(servers, { operator })`** is a resolver for a coding harness's per-run
tools, in `claudeCodeAgent`'s `mcpTools` shape. It finds the run's project and owner the way
`projectWorkspace()` does, connects to each server the project names in `servers`
Expand Down Expand Up @@ -2122,7 +2155,8 @@ It exports `createWorkforceClient`, `deriveWorkerSessionId`, `isDerivedWorkerSes
`ROSTER_FLOW`, `WORKER_ID_STATE_KEY`, `COORDINATOR_FLOW`, `COORDINATOR_ROUTE`, `COORDINATOR_JUDGMENT` (the
coordinator's own turn's answer name, which its messages carry as `agentName`) and
`sessionIdOfFiling` (the conversation a board row was filed in), `RULE_TOOLS`, `MAX_RULES`,
`MAX_RULE_CHARS`, `STANDING_RULES_ACTION`, `STANDING_RULES_LINE`, `MESSAGE_WORKER_TOOL` (the
`MAX_RULE_CHARS`, `STANDING_RULES_ACTION`, `STANDING_RULES_LINE`, `SET_WORK_PROJECT_ACTION`,
`WORK_PROJECT_STATE_KEY`, `MESSAGE_WORKER_TOOL` (the
tool a sent message is a call to), `WORKER_MESSAGE_ENTRY`, `WORKER_MESSAGES_PATTERN`,
`WORKER_MESSAGES_RESOURCE` and `workerMessageRowSchema`, the same values the root exports, and reaches no Node built-in.

Expand All @@ -2148,8 +2182,9 @@ tool a sent message is a call to), `WORKER_MESSAGE_ENTRY`, `WORKER_MESSAGES_PATT
| `workerConfigOf(ctx)` | The configuration of the worker the turn loaded, synchronously, for a prompt, a tool list or a step condition. Throws when the turn loaded no worker: call `installation.resolveWorker` in the flow's `request.onStarted`. |
| `createWorkerHireBlocks(installation)` | `{ hire, fork, edit, fire }`: writes to the caller's own roster, each checked as a turn would check it before anything is written, each refusing a standard worker's id. |
| `defineWorkerRosterFlow(installation, actions?)` | The roster flow (`workforce-roster`), which declares the two worker collections so a client reads a user's roster through one session of it. Mount the hire blocks on it as actions. |
| `createWorkforceClient({ userId, baseUrl?, apiPath?, fetcher? })` | `roster()`, `findWorkerSession(criteria)`, `ensureWorkerSession(criteria)` and `standingRules(worker, input)` (see [Standing rules](#standing-rules)), over the session and resource clients. `criteria` is a `WorkerSessionCriteria`: `worker`, and optional keys such as `projectId`, which finds or starts the user's project coordinator for that project. From `./browser` only. |
| `createWorkforceClient({ userId, baseUrl?, apiPath?, fetcher? })` | `roster()`, `findWorkerSession(criteria)`, `ensureWorkerSession(criteria)`, `standingRules(worker, input)` (see [Standing rules](#standing-rules)) and `setWorkProject(worker, { visibility, id }, { sessionId? })` (see [Projects](#projects)), over the session and resource clients. `criteria` is a `WorkerSessionCriteria`: `worker`, and optional keys such as `projectId`, which finds or starts the user's project coordinator for that project. From `./browser` only. |
| `RULE_TOOLS`, `MAX_RULES`, `MAX_RULE_CHARS`, `STANDING_RULES_ACTION`, `STANDING_RULES_LINE`, `STANDING_RULES_RESOURCE` | The four rule tools' names, the list's limits (20 and 300), the flow action `standingRules` calls, the `agentName` a rule write's line carries, and the resource the list is kept under. All but `STANDING_RULES_RESOURCE` are also exported from `./browser`. |
| `SET_WORK_PROJECT_ACTION` / `setWorkProjectAction` / `WORK_PROJECT_STATE_KEY` | The action `setWorkProject` calls (`"setWorkProject"`), the action itself for a worker flow of your own to declare under that name, and the server-owned session-state field it writes (`"workProjectId"`, `<visibility>/<id>`). The two constants are also exported from `./browser`. |
| `deriveWorkerSessionId({ userId, orgId, flow, criteria })` / `isDerivedWorkerSessionId(id)` | The id `ensureWorkerSession` creates a session at, and the shape a worker flow's create check reserves for the user it derives to. |
| `WorkerTurnRefusedError` | What `resolveWorker` throws when a turn can't run as the session's worker; nothing is written. |
| `defineWorkerCollection()` / `workerRowSchema` / `parseWorkerRow(value)` | The user's worker collection at `workforce/workers/*`, user scope, and its row. |
Expand Down Expand Up @@ -2201,7 +2236,7 @@ tool a sent message is a call to), `WORKER_MESSAGE_ENTRY`, `WORKER_MESSAGES_PATT
| `parseWorkstreamEntry(path, state)` | One entry read off its storage key and checked against `workstreamEntrySchema`, with its `project`, `owner` and `id`; `undefined` for a key that isn't an entry. Also from `./browser`, for a browser reading entries through the resource routes. |
| `projectCoordinatorTools` | `{ readProject }`, the project coordinator's tool, which marks each workstream `yours` when the user it talks to owns it: put it in `defineCoordinatorFlow({ agent: { catalog } })` and name it in the coordinator's `tools:`. Add `setBrief` and `setRepository` from `defineProjectBlocks()` for it to manage its own project. |
| `linkedProjectOf(state)` | The `{ visibility, id }` a session's state links it to by its `projectId`, or `undefined`. |
| `projectWorkspace({ checkouts? })` / `projectWorkspaceCapability` / `ProjectCheckout` | A run source for a coding run on a project: from the workstream its session leads or was filed from, the project its conversation belongs to, or the project its task names. `checkouts` (`ProjectCheckout[]`: `{ remote, checkout, projects, baseRef? }`) sends the listed shared projects' runs, in their own organization, to a checkout on this machine. The capability holds the collections it reads. See [Projects](#projects). |
| `projectWorkspace({ checkouts? })` / `projectWorkspaceCapability` / `ProjectCheckout` | A run source for a coding run on a project: from the workstream its session leads or was filed from, the project its conversation belongs to or was set to, or the project its task names. `checkouts` (`ProjectCheckout[]`: `{ remote, checkout, projects, baseRef? }`) sends the listed shared projects' runs, in their own organization, to a checkout on this machine. The capability holds the collections it reads. See [Projects](#projects). |
| `createWorkerLookup({ installation })` | Which standard worker a task's name means. Returns `{ find, flowKind, state, filingCheck }`. `find(name)` answers `{ found: true, flowId }`, or `{ found: false, reason, message }` with `reason` `not-found` or `takes-no-tasks` (a worker whose flow declares no `work` task entry). `flowKind` and `state` are a `per-task` dispatcher's targets: the flow of the worker the task's `assignee` names, and a starting state naming that worker. |
| `WORKER_TASK_ENTRY` | `"work"`, the task entry a worker flow takes tasks through. |
| `workerTaskEntry({ name, turn \| block })` / `WorkerTaskEntryOptions` / `WorkerTaskBlockInput` / `conversationLedgers` / `filingConversationBoard` | The `work` task entry for a worker flow of your own: `task: { actions: { work: workerTaskEntry({ name, turn }) } }`. Each task a coordinator files for one of its workers runs as one `turn` (`{ message }` in, the answer out), or, with `block` instead (one or the other, refused at build otherwise), as a block handed the task itself plus `claim` (`{ collectionId, partition, incarnationId }`, the board the task was claimed from, never read from the task), in a task session of its own, and the conversation that filed it is told when it ends. A flow whose `work` entry is built any other way takes no conversation task: `listDelegates` reports it as taking `nothing`, and a filing for it is refused. `conversationLedgers(ledgerId, ctx, partition)` finds the board of the conversation a task came from; pass it to a harness manager that takes tasks from conversations. `filingConversationBoard(ctx)` answers, in a task session, that conversation's board with the entry and flow that run it there (`{ tasks, runEntry, filingFlow, filingSession }`), for a door over the session's run (`harnessSessionDoor`'s `board`). A coding run's `projectWorkspace()` finds its project from the filing workstream, then the project of the conversation that filed it, then the task's `input.project` (`{ visibility, id }`, checked against the run's own user), then the `board` claim. |
Expand Down
3 changes: 3 additions & 0 deletions packages/workforce/src/agent-worker-flow.ts
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,8 @@ import { turnConfigOf, verifiedWorkerOf } from "./workers/verified-worker";
import { markUserTurnStep } from "./standing-rules/user-turn";
import { standingRulesCapability } from "./standing-rules/rules-capability";
import { STANDING_RULES_ACTION, standingRulesAction } from "./standing-rules/rules-action";
import { setWorkProjectAction } from "./projects/work-project";
import { SET_WORK_PROJECT_ACTION } from "./workers/keys";
import type { WorkerInstallation } from "./workers/installation";
import { steerOrTalk } from "./conversation-board/steer";
import { worksConversationResultTask } from "./conversation-board/task-admission";
Expand Down Expand Up @@ -1354,6 +1356,7 @@ function defineAgentFlowAround(
concurrency: REPLY_CONCURRENCY
},
[STANDING_RULES_ACTION]: standingRulesAction,
[SET_WORK_PROJECT_ACTION]: setWorkProjectAction,
// On an installation: the task actions (`updateTask_tasks` and the
// rest) over this session's board, and the four delegate actions. A
// session whose delegates take no task answers `no_delegation_board`.
Expand Down
Loading
Loading