Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
5 changes: 5 additions & 0 deletions .changeset/engine-adoption-refuses-readonly.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@flow-state-dev/engine": minor
---

A dispatch that reaches a key-derived child session which already exists, asking for another value of one of its readonly session-state fields, is refused with `key-occupied`, naming the field, instead of adopting the session. Nothing is written and nothing runs there (FIX-1788).
5 changes: 5 additions & 0 deletions .changeset/flow-resource-visibility.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@flow-state-dev/core": minor
---

`defineFlow` takes `resourceVisibility`, a per-turn rule for which of the flow's resources the model's resource tools reach. A resource it hides is absent from listing, search and the discovery door, and answers "not found" when named; a read-only one is read but not written. Omitted, nothing changes (FIX-1788).
5 changes: 5 additions & 0 deletions .changeset/shift-manager-workers-as-data.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@flow-state-dev/shift-manager": minor
---

Roster lists the signed-in person's own workers beside the Lab's standard ones, read through Workforce's roster flow, and the chief of staff's conversation is a session of its flow that names the worker. A Lab registers the flows `hireWorkforce(installation)` returns (FIX-1788).
5 changes: 5 additions & 0 deletions .changeset/workforce-one-copy-per-flow.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@flow-state-dev/workforce": minor
---

Every worker runs on one shared copy of the flow it names. `hireWorkforce(installation)` returns one copy of each worker flow and the roster flow (`workforce-roster`, with `hire`, `fork`, `edit` and `fire`), and mints nothing per worker and pins nothing. A worker flow declares `session: installation.session()` and loads its worker each turn; `workerFlow(...)` builds a flow in its own file on its installation, and `installation.resourceVisibility` narrows each turn's model to its worker's document grants. The built-in `agent` on an installation keeps each worker's skills apart, refuses a turn whose input names a worker, and signs its mailbox posts as the turn's worker. The mailbox wake and the task lookup open each session naming its worker, for standard workers only. Removed: `createSeatHireCapability`, `createSeatHireBlocks`, `registerHiredSeat`, `reloadHiredSeats`, the hired-roster collections and keys, `seatAddress`/`splitSeatAddress`, and `listedSeatRows` (FIX-1788).
4 changes: 0 additions & 4 deletions apps/docs/docs/cli/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -167,10 +167,6 @@ anything is written:

- A session belongs to the user and organization it was created with. Resuming one with
`--session` as anyone else is refused, as it would be over HTTP. Use a new session id.
- A [hired seat](/docs/workforce/durable-hire#who-can-reach-a-hired-seat) runs only for the owner
it's pinned to. A run whose user or organization falls outside that pin is refused, whether the
identity came from your resolver or from `--user` and `--org`. Name the owner with `--org`, plus
`--user` for a seat one member owns.
- A session with no organization recorded on it is refused and left unchanged. The message points
to the upgrade steps in
[Which organization a record belongs to](/docs/persistence/overview#which-organization-a-record-belongs-to).
Expand Down
2 changes: 0 additions & 2 deletions apps/docs/docs/devtool/debug-vs-client-state.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,6 @@ For each storage key the session touches, the debug response includes:

It does not apply `prefetchWindow`: a collection lists all of its items, not a window of them. It does not apply `client.data` to the storage view either; that projection is shown alongside the raw state, not in place of it.

The workforce roster is the exception to the full listing. A [user-owned seat](../workforce/durable-hire.md#hiring-a-seat-only-one-member-can-reach) that belongs to a user other than the session's user doesn't appear in the collection's item list or its item count, and fetching its content returns 404.

On any collection, fetching content for a topic that doesn't match the collection's pattern also returns 404.

The endpoint is read-only. You can't mutate state through it.
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/docs/devtool/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ The tab appears on a session whose flow declares at least one of the three inven
- **Registered mailboxes:** Id, Kind, Members, and Registered, the time the mailbox first registered.
- **Registered memberships:** Seat and Mailbox.

A mailbox's session declares all three. Some flows declare only part: a seat carrying the [`seat-hire` tools](/docs/workforce/durable-hire) declares only the seat collection. A collection the flow doesn't declare reads "Not installed on this flow.", which is different from an empty section such as "No seats registered." When nothing is registered anywhere, the tab says so and points at the usual cause: the app never calls `openInventory` at boot.
A mailbox's session declares all three. Some flows declare only part. A collection the flow doesn't declare reads "Not installed on this flow.", which is different from an empty section such as "No seats registered." When nothing is registered anywhere, the tab says so and points at the usual cause: the app never calls `openInventory` at boot.

Every row is labelled registered. Rows are never removed, so a fired seat stays listed, and a mailbox's members are the ones it had when it registered. The tab is a record of what has been registered here. It can't tell you which seats are working now.

Expand Down
10 changes: 5 additions & 5 deletions apps/docs/docs/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,14 +100,14 @@ These sit beside Orchestration on Core and don't use a task board.

| Term | Package | What it is | Built from |
|---|---|---|---|
| **Worker** | workforce | One worker record, usually from a `WORKER.md` and sometimes built in code, hired into a flow instance with its own address. You open sessions against it like any flow. See [Workers on disk](./workforce/workers-on-disk.md). | Flow instance |
| **Address** | workforce | A worker's id: `team.name` for a team worker, the bare name for an org worker. A worker hired while the app runs is addressed `<org>.<name>`, or `<org>.~<user>.<name>` when one person owns it. | None |
| **Worker** | workforce | A configuration run by one shared copy of the flow it names: a `WORKER.md` (a standard worker every user has) or a row a user hired or forked for themselves. A session names its worker when it is created. See [Workers on disk](./workforce/workers-on-disk.md). | Flow, session state |
| **Address** | workforce | A worker's id: `team.name` for a team worker, the bare name for an org worker. A user's own worker is addressed by the id it was hired or forked under, on that user's roster. | None |
| **Team** | workforce | A folder of workers under `teams/<name>/`, with an optional `TEAM.md` whose body every worker on the team reads. A team is not a flow and has no address. | Workers |
| **Org worker** | workforce | A worker under `org/workers/<name>/`. It belongs to no team. | Worker |
| **Built-in worker** | workforce | The `agent` kind every worker runs on unless its file names another `flow:`. See [The built-in worker](./workforce/built-in-worker.md). | Flow (collection), generator, skills |
| **Hire** | workforce | `hireWorkforce` turns each worker record into a flow instance. Your app registers what comes back. | Flow instance |
| **Roster** | workforce | The workers you hire. The ones hired while the app runs are kept as rows, so they come back after a restart. See [Hiring while the app runs](./workforce/durable-hire.md). | Org resource collection |
| **Fire** | workforce | Removes a worker hired while the app runs. A worker declared in a file leaves when its folder is deleted. | Roster row, inventory row |
| **Hire** | workforce | A user adds a worker of their own, as a row in their data. `hireWorkforce` gives back one copy of each worker flow, which your app registers. | Roster row |
| **Roster** | workforce | A user's workers: their own, and the standard ones your files declare. See [Hiring and forking](./workforce/durable-hire.md). | User-scoped resource collection, standard workers from files |
| **Fire** | workforce | Removes one of a user's own workers from their roster. A worker declared in a file leaves when its folder is deleted. | Roster row |
| **Mailbox** | workforce | One `MAILBOX.md`: a named session on the shared `mailbox` flow, with members, a charter and a transcript. See [Mailboxes](./workforce/mailboxes.md). | Session, flow |
| **Member** | workforce | A worker id on a mailbox's member list. A post wakes each member whose flow kind handles posts, or only the chosen one on a routed mailbox. | Worker address |
| **Transcript** | workforce | The posts in a mailbox, rebuilt from the post items. | Items |
Expand Down
6 changes: 3 additions & 3 deletions apps/docs/docs/orchestration/agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -167,11 +167,11 @@ Both forms default to `scope: "org"`, so a persona is shared across users unless

`createWorkforceCapability({ roster, inventory })` returns a capability named `workforce` that gives every seat of the kind one tool: `discover`, which answers what seats and mailboxes have been registered, and whatever other domains you hand it. Pass the declared roster and the registry keys the [inventory](../workforce/inventory)'s seat and mailbox rows are mounted under. See [Discovery](./discovery).

## Hired workers
## Workforce workers

Workforce is a separate product. `hireWorkforce` turns a roster into configured flow copies you register and open a session against. A board's workers are blocks that claim tasks from a collection.
Workforce is a separate product. A Workforce worker is a configuration run by one shared copy of the flow it names, and you talk to it by opening a session that names it. A board's workers are blocks that claim tasks from a collection.

A hired worker's flow can mount a board, and that board's workers are any of the three above. A task's `assignee` can also name a hired worker: a board whose `defaultWorker` asks Workforce's worker lookup hands the task to the worker of that name. See [Giving a task to a worker](../workforce/overview#giving-a-task-to-a-worker).
A worker flow can mount a board, and that board's workers are any of the three above. A task's `assignee` can also name a standard Workforce worker: a board whose `defaultWorker` asks Workforce's worker lookup hands the task to the worker of that name. See [Giving a task to a worker](../workforce/overview#giving-a-task-to-a-worker).

## Related pages

Expand Down
14 changes: 14 additions & 0 deletions apps/docs/docs/resources/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -289,6 +289,20 @@ Resource collections take the same flags, declared once on the collection and ap

The generic tools address resources by their scope-qualified uri (for example `session/files/readme.md`), the same handle the [search tools](/docs/resources/searching) return — so a result from `globResources` or `grepResourceContent` feeds straight into `readResourceContentTool`.

A flow can also narrow what the model reaches on a single turn. Give it a `resourceVisibility` rule: a function that returns `"visible"`, `"read-only"` or `"hidden"` for each resource. The built-in resource tools, the `discover` tool, and any tool you build on them treat a resource the rule hides as one that doesn't exist: it isn't listed, searched, read or written, and asking for it by its uri gets the same answer as asking for a missing one. A resource the rule marks read-only is read but not written. With no rule, the model reaches every resource the flow declares, as its `llmReadable` and `llmWritable` flags allow.

```ts
defineFlow({
kind: "desk",
resources: { handbook, payroll },
// Called on every listing and lookup: keep it synchronous, and decide from what your server wrote, never the turn's input.
resourceVisibility: (ctx, { name }) => (name === "payroll" && !isFinance(ctx) ? "hidden" : "visible"),
actions: { /* … */ },
});
```

The rule decides what the model sees, not what your code does: a block that reads a resource by reference, as `ctx.resources.payroll`, still reads it. Workforce sets the rule for you, so a worker's model reaches only the documents its `WORKER.md` grants, even when many workers share one flow.

## Resource collections

Static resources have a fixed name. Resource collections let you create typed sets of resources dynamically at runtime — useful when the number of instances isn't known ahead of time (file collections, per-topic knowledge, dynamic workspaces).
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/docs/server/background-work.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ A refusal at run time throws `DispatchRefusedError`, with `code:
| `refused` | Meaning |
|---|---|
| `no-entry` | The addressed flow declares no entry at that address |
| `flow-not-found` | A `flowKind` names a flow this server has not registered, or a [hired seat](../workforce/durable-hire.md#who-can-reach-a-hired-seat) the sending session may not open: one pinned to another organization, or a user-owned seat that belongs to another user. The refusal is the same in both cases, so `flow-not-found` doesn't tell you which one you hit |
| `flow-not-found` | A `flowKind` names a flow this server has not registered |
| `session-not-found` | An `id` names a session that does not exist, or one that belongs to another user |
| `session-not-addressable` | An `id` names a session on a flow other than the one addressed |
| `key-occupied` | The `key` derived a session id already held by a record that is not this conversation's run |
Expand Down
Loading
Loading