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
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/seat-resource-allowlist.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
"@flow-state-dev/workforce": minor
---

A `WORKER.md` can declare `resources:`, the documents that seat may touch — naming one grants read, `rw` grants write — and the app supplies its documents through a new `documents` option on `hireWorkforce` (FIX-1381).

Migration: `resources` is now read by the hire step rather than passed on as a setting, so a worker kind that declared a `resources` setting of its own must rename that setting before upgrading — it no longer receives an authored value. A seat that declares no `resources:` key keeps the reach it has today.
2 changes: 2 additions & 0 deletions apps/docs/docs/workforce/documents-on-disk.md
Original file line number Diff line number Diff line change
Expand Up @@ -223,6 +223,8 @@ const engineering = resourcesFromDocs(

The same is true one level down, and it is worth being plain about. Putting a document under `workers/on-call/` addresses it to that seat. It does not keep it from the others. Seats hired into one kind share that kind's flow definition, so by default every one of them reads the same row.

Filtering decides what a whole kind installs. To narrow one seat within a kind, the seat's own file names the documents it may touch, and can take one read-only: see [what a `WORKER.md` says](./workers-on-disk.md#what-a-workermd-says). A seat naming a document its kind was not installed with is refused at the hire, so the filter holds.

### Giving one seat a document of its own

A document whose frontmatter carries `flowIsolation: true` gets one row per seat:
Expand Down
54 changes: 53 additions & 1 deletion apps/docs/docs/workforce/workers-on-disk.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,9 @@ description: Holds the engineering board and breaks work into tasks.
flow: custom-agent
model: openai/gpt-5.4-mini
tools: [board, search]
resources:
- teams/engineering/handbook
- teams/engineering/board-notes: rw
---

You are the engineering lead. You do not write code yourself. You break the
Expand All @@ -55,6 +58,10 @@ request into tasks, assign them, and report what came back.

`description` is the only key the file itself requires. Four it refuses outright: `persona:`, `seatSkills:`, `seatTools:` and `teamInstructions:` — the last three because a seat's skills and the blocks it can reach are decided by where its folders sit, and its team's instructions by that team's [`TEAM.md`](#what-a-teammd-says), rather than by what one worker's file claims. `flow` names which of your flow kinds this worker runs. Leave it out and the worker is hired into [the built-in worker kind](./built-in-worker.md), which needs no flow of yours.

`resources:` is a list of the [documents](./documents-on-disk.md) this worker may touch, chosen from the ones its kind holds. Each entry is a document's [ref](./documents-on-disk.md#a-documents-ref), the name it gets from where its file sits. A ref on its own is read-only. `<ref>: rw` grants writes, and `<ref>: ro` spells the default out. Leave the key out and the worker reaches every document its kind installed, and writes the ones that allow writes; `resources: []` is how you say it gets none.

Only documents are narrowed. The stores and boards its kind declares stay reachable and writable whatever the list says, and so do the resources the kind's own blocks declare. Where the documents come from is [below](#supplying-the-documents-a-seat-may-name).

Reading the file checks no other key. Whatever else you write lands on the record spelled exactly as you spelled it. The flow a worker names has the final say: at hiring it [refuses a setting it never declared](#the-flow-decides-what-a-worker-may-declare).

The frontmatter is the same dialect a [`SKILL.md`](../skills/overview.md) uses. If you have written one of those, you already know the shape.
Expand Down Expand Up @@ -284,7 +291,7 @@ composed kind for free and makes a hand-rolled one refuse at startup until you a

`cardinality: "collection"` is what lets one definition have many copies. A roster is exactly that: one copy per worker, each with its own id and its own settings. [Copies that differ by settings](../fundamentals/flows.md#copies-that-differ-by-settings) covers how a copy is configured, and [how an instance is addressed](../fundamentals/flows.md#how-an-instance-is-addressed) covers the URL each one answers on.

`hireWorkforce` reads `flow` to pick the kind, and `description` as a label for the roster. Everything else becomes that copy's settings and is parsed against the flow's `configSchema`, which is closed. So the flow's author, not the framework, decides what a worker of that kind may say about itself.
`hireWorkforce` reads three keys of its own: `flow` to pick the kind, `description` as a label for the roster, and [`resources`](#supplying-the-documents-a-seat-may-name) to decide which documents the copy is minted with. Everything else becomes that copy's settings and is parsed against the flow's `configSchema`, which is closed. So the flow's author, not the framework, decides what a worker of that kind may say about itself.

```ts
const lead = seats.find((seat) => seat.id === "engineering.lead")!;
Expand Down Expand Up @@ -353,6 +360,50 @@ Declaring `instructions:` in the frontmatter *and* writing a body is refused, na

`persona:` names something else here, [an agent's system prompt](../orchestration/agents.md#personas). A `WORKER.md` has no `persona` setting, so declaring one lands the worker in `errors` when the tree is read, or is refused by `hireWorkforce` for a hand-built record.

### Supplying the documents a seat may name

A worker's `resources:` list selects from the documents its kind was installed with, so the hire step has to be told which entries in a kind's resource map are documents. Pass it the same map you spread into the flow. Here is [the `custom-agent` kind](#the-flow-decides-what-a-worker-may-declare) again with its documents installed — the action's `inputSchema` and `runTurn`, and the `workers` you loaded, are the same ones as there:

```ts
import { defineFlow } from "@flow-state-dev/core";
import { hireWorkforce, resourcesFromDocs, workerConfigSchema } from "@flow-state-dev/workforce";
import { readResourcesDirectory } from "@flow-state-dev/workforce/loader";
import { boardResource } from "./resources";

const { documents } = await readResourcesDirectory("./workforce");
const catalog = resourcesFromDocs(documents);

export const customAgentFlow = defineFlow({
kind: "custom-agent",
cardinality: "collection",
configSchema: workerConfigSchema().extend({
instructions: z.string(),
model: z.string().default("openai/gpt-5.4-mini"),
tools: z.array(z.string()).default([]),
}),
resources: { board: boardResource, ...catalog },
actions: { run: { inputSchema, block: runTurn } },
});

const seats = hireWorkforce(workers, {
Comment thread
jhoffner marked this conversation as resolved.
Resolved
kinds: { "custom-agent": customAgentFlow },
documents: catalog,
});
```

One catalog, spread into the flow and handed to the hire. Which entries in that map are documents is what the `documents` option answers: `board` above is not one, and no worker's list governs it.

`documents` is consulted only for a worker that declares `resources:`. A roster where none does hires the same whether you pass it or not. A worker that does declare one while `documents` is absent is refused, naming what is missing.

A list the hire step cannot resolve refuses the whole roster, naming the worker and what was wrong. The message calls one entry a grant and quotes the ref as the file spelled it, which here is `handbook` with two letters swapped:

```
hireWorkforce refused 1 of 3 workers; nothing was hired:
- worker "engineering.lead" — grants "teams/engineering/hanbdook", which is
not a document this app declared. A grant selects from the documents passed
to hireWorkforce as `documents`; it cannot declare one.
```

### When a hire is refused

Every problem here is a startup misconfiguration, so every problem throws. They are collected first, so one run names all of them and you fix them in one pass, and nothing is returned, so a bad record cannot leave you with a half-hired roster.
Expand All @@ -366,6 +417,7 @@ A record is refused when it:
- declares `instructions:` and carries a body;
- declares `persona:`, `seatSkills:` or `teamInstructions:`, none of which is a setting a worker declares;
- declares `teamInstructions:` in its frontmatter, wherever that frontmatter came from — a team's instructions come from its [`TEAM.md`](#what-a-teammd-says) body, read by the loader;
- declares a `resources:` list the hire step cannot resolve: a ref no document matches, a ref naming a document the app declared but did not install on this worker's kind, a mode that is neither `ro` nor `rw`, the same ref twice, `rw` on a document whose own frontmatter says `writable: false`, a ref colliding with a name the kind's own blocks declare, or the key at all when no `documents` were passed;
- shares an id with another record in the same call, which is two workers claiming one address.

`kinds` itself is checked too. A flow passed under a key that is not its own `kind` is refused. The copy would otherwise come back carrying the right worker's id, and run the other kind's graph once you registered it.
Expand Down
9 changes: 9 additions & 0 deletions docs/architecture/workforce-default-worker-kind.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,15 @@ at boot:
|---|---|---|
| **The admission contract** | `instructions?`, `teamInstructions?`, `seatSkills`, `seatTools` | The framework's. Every hireable kind admits these, by composing `workerConfigSchema()` (`packages/workforce/src/worker-config.ts`). |
| **This kind's own** | `model`, `tools`, `skills` (the switches) | The default kind's alone. They sit at the top level beside the contract's, where the framework closes the set and an undeclared key refuses by name. `tools` is the one of the three that is **reserved** — see below. |
| **The hire step's** | `flow`, `description`, `resources` | Never a kind's. Read and removed before admission, so no `configSchema` sees them — see `resources` below. |

**`resources` is taken outright, and is not a setting at all (FIX-1381).** Where `tools` is a key a
kind declares and the hire step reads, `resources` is a key the hire step *consumes*: it names the
documents that seat may touch, it is removed from the bag before admission, and it never reaches a
kind's `configSchema`. So a kind may not declare a `resources` setting of its own — one that did
would simply stop receiving an authored value. The narrowed map it produces replaces the kind's
flow-level resource map for that seat; `packages/workforce/src/seat-resources.ts` is canonical for
the grant shapes and the refusals.

**`tools` is reserved across hireable kinds, for one meaning: the names of tools this seat may call.** It is not a contract key — a kind declares it itself, or does not declare it at all — but a kind that declares it may not give it some other meaning, because the hire step reads it. A name in `tools:` is resolved against what is registered for that seat (its own `blocks/` folder, then its team's, then the kind's catalog), and the ones that resolved to the seat's own folders are moved onto `seatTools` as live blocks. A kind is free to decide what it checks the remaining names against, and free to declare no `tools` at all; what it may not do is use the key for unrelated string configuration, which the hire step would rewrite.

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
/**
* One worker kind, built the way an app builds one: the documents its
* `resources/` folder declared, spread into a flow-level map beside a store of
* its own.
*
* A factory rather than a module-level constant, because the documents come off
* disk. That is also what makes the fixture honest: the flow-level map holds a
* `${STORE}` the allowlist must never touch, beside documents it must narrow.
* A fixture whose flow-level map held nothing but documents would be green for
* a resolver that silently deletes the app's own machinery.
*
* No model, no generator. What is graded is which resources reached a running
* block and which of them it could write.
*/
import { defineFlow, defineResource, handler, sequencer } from "@flow-state-dev/core";
import type { DeclaredResources } from "@flow-state-dev/core";
import type { ResourceDoc } from "@flow-state-dev/workforce";
import { resourcesFromDocs, workerConfigSchema } from "@flow-state-dev/workforce";
import { z } from "zod";

export const DESK_KIND = "desk";

/** The app's own store, declared at flow level beside the documents. Not a document. */
export const STORE = "audit-log";

const auditLog = defineResource({
ref: STORE,
scope: "org",
stateSchema: z.object({ entries: z.array(z.string()).default([]) }),
default: { entries: [] },
writable: true
});

const inputSchema = z.object({ note: z.string() });

/** What the seat records about what it could actually touch. */
const seatState = z.object({
/** Every resource key the block resolved, sorted. */
reach: z.array(z.string()).nullable().default(null),
/** Every one of those it could also write, sorted. */
wrote: z.array(z.string()).nullable().default(null),
runs: z.number().default(0)
});

const start = handler({
name: "desk-start",
inputSchema,
execute: async (_input, ctx) => {
await ctx.session.incState({ runs: 1 });
}
});

/**
* The nested read — what this seat can reach, and what it can write.
*
* Both halves are probed by DOING them, never by reading a flag: `ro` is only
* worth anything if the write actually refuses at the seam, and a check that
* asserted `writable === false` would pass for a flag nothing consults.
*/
function probe(keys: readonly string[]) {
return handler({
name: "desk-probe",
inputSchema,
outputSchema: z.void(),
// Every document is org-scoped, and a flow collects `requiresOrg` from its
// blocks rather than from its resource map. Without this the request is
// admitted with no org, no org registry is built, and every document reads
// as unregistered — a green `reach: []` for the wrong reason.
requireOrg: true,
sessionStateSchema: seatState,
execute: async (_input, ctx) => {
const reach: string[] = [];
const wrote: string[] = [];
for (const key of keys) {
let ref: { setState(next: Record<string, unknown>): Promise<void> } | undefined;
try {
ref = ctx.resources.get(key) as unknown as typeof ref;
} catch {
continue;
}
if (ref === undefined) continue;
reach.push(key);
try {
await ref.setState({ touched: true });
wrote.push(key);
} catch {
// A refused write is the point of the `ro` half, not an error here.
}
}
await ctx.session.patchState({ reach: reach.sort(), wrote: wrote.sort() });
}
});
}

const clientView = {
derived: {
ran: (ctx: { state: { reach?: string[] | null; wrote?: string[] | null; runs?: number } }) => ({
reach: ctx.state.reach ?? null,
wrote: ctx.state.wrote ?? null,
runs: ctx.state.runs ?? 0
})
}
};

/**
* Build the kind from the documents the loader found.
*
* Returns the catalog too, because that is the same map the app hands
* `hireWorkforce` as `documents` — one list, spread into the flow and passed to
* the hire step, never built twice.
*/
export function buildDesk(documents: ResourceDoc[]): {
deskFlow: ReturnType<typeof defineFlow>;
catalog: DeclaredResources;
probedKeys: string[];
} {
const catalog = resourcesFromDocs(documents);
const probedKeys = [...Object.keys(catalog), STORE].sort();

const deskFlow = defineFlow({
kind: DESK_KIND,
cardinality: "collection",
configSchema: workerConfigSchema(),
resources: { ...catalog, [STORE]: auditLog } as DeclaredResources,
actions: {
run: {
inputSchema,
block: sequencer({ name: "desk-work", inputSchema }).tap(start).tap(probe(probedKeys))
}
},
session: { stateSchema: seatState, client: clientView }
});

return { deskFlow, catalog, probedKeys };
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
{
"userId": "u_seat_resource_allowlist_goal",
"note": "Who is allowed to read payroll?",
"documents": ["handbook", "payroll"],
"store": "audit-log",
"seats": {
"lead": {
"id": "engineering.lead",
"reaches": ["handbook"],
"writes": []
},
"cfo": {
"id": "engineering.cfo",
"reaches": ["payroll"],
"writes": ["payroll"]
},
"chief": {
"id": "engineering.chief",
"reaches": ["handbook", "payroll"],
"writes": ["handbook", "payroll"]
}
},
"control": {
"dir": "typo",
"id": "engineering.typo",
"ref": "hanbdook"
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
description: The same desk, with one character wrong in its grant.
flow: desk
resources:
- hanbdook
---

You meant the handbook.
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
description: How the engineering team works — on-call, review, escalation.
llmReadable: true
llmWritable: true
---

# Engineering handbook

Escalate anything customer-visible within 15 minutes.
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
description: What every seat on the roster is paid.
llmReadable: true
llmWritable: true
---

# Payroll

Not everybody's business.
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
description: Holds anything about money.
flow: desk
resources:
- payroll: rw
---

You keep payroll current.
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
description: The seat that was here before any of this and declares no resources.
flow: desk
---

You see everything this app declared, as you always did.
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
description: Holds the engineering board and breaks work into tasks.
flow: desk
resources:
- handbook
---

You are the engineering lead. You consult the handbook; you do not rewrite it.
Loading
Loading