Skip to content
Prev Previous commit
Next Next commit
chore(workforce): use the current vocabulary in FIX-2159's prose and …
…test (FIX-2159)

"user" for the signed-in user, and a test helper not named like the
retired ask mark, so the Process guards pass.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N9RvCHba2QKPohNxnZNzct
  • Loading branch information
claude committed Oct 24, 2026
commit 7fb929d1f3ded5d5b501488ec9a853dcd4375d63
6 changes: 3 additions & 3 deletions packages/workforce/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -786,7 +786,7 @@ worker is still answering shows up in that same request, and the worker answers
const agent = defineAgentWorkerFlow({ installation, catalog: appTools, answerAgain: true });
```

After the worker answers a person's message, each task the conversation filed that ended since the
After the worker answers a user's message, each task the conversation filed that ended since the
turn began is said once, as a line under the delegate's name:

```text
Expand Down Expand Up @@ -863,7 +863,7 @@ Limits:
in the same round, the worker answers once about both.
- An answering-again turn files no step for the worker itself. A task it files for a delegate is
dispatched as usual.
- Only a turn started by a person's own message to the worker (`respond`) takes anything. In a
- Only a turn started by a user's own message to the worker (`respond`) takes anything. In a
task's turn, a turn a task's ending woke, or a turn another worker's message started,
`takeFinishedTasks` returns `[]` and results arrive after the turn.
- A result that lands during a long answer waits until that answer ends. One that lands after the
Expand Down Expand Up @@ -2230,7 +2230,7 @@ tool a sent message is a call to), `WORKER_MESSAGE_ENTRY`, `WORKER_MESSAGES_PATT
|--------|-------------|
| `defineAgentWorkerFlow(options?)` | Build the `agent` worker flow, the one the framework ships. With `installation` it is the copy every worker on `agent` shares: it declares the installation's session and documents, loads the turn's worker in `request.onStarted`, and refuses a turn whose input names a worker; called with factory options (`AgentWorkerFlowOptions`) it is the replacement you register under `agent`. Its flow declares `run` (public) and a `work` task entry that takes the tasks a conversation files for its workers. |
| `AGENT_FLOW` | The kind name (`"agent"`) the hire step defaults to, and the key a replacement registers under. |
| `takeFinishedTasks` / `finishedTaskSchema` / `FinishedTask` | A handler block that takes the tasks this conversation filed that ended since the turn began, says each as a line under its delegate's name, and returns them as `{ taskId, ending, worker?, line }[]`. Input is ignored. `[]` outside a turn a person's own message started (see [Answering again with finished tasks](#answering-again-with-finished-tasks)). |
| `takeFinishedTasks` / `finishedTaskSchema` / `FinishedTask` | A handler block that takes the tasks this conversation filed that ended since the turn began, says each as a line under its delegate's name, and returns them as `{ taskId, ending, worker?, line }[]`. Input is ignored. `[]` outside a turn a user's own message started (see [Answering again with finished tasks](#answering-again-with-finished-tasks)). |
| `finishedTasksAnswerAgain({ message? })` / `FinishedTasksAnswerAgainOptions` | The block `answerAgain: true` uses: `takeFinishedTasks`, then `{ message }` built from the lines, or `{}` when nothing finished. `message(finished)` replaces the default wording. |
| `MAX_ANSWERS_AGAIN` | `3`, the most times one request answers again after its turn, the answer after a plan included. |
| `definePersona(config)` | Declare a persona resource or collection. |
Expand Down
2 changes: 1 addition & 1 deletion packages/workforce/src/agent-worker-flow.ts
Original file line number Diff line number Diff line change
Expand Up @@ -369,7 +369,7 @@ export interface AgentWorkerFlowOptions {
* It feeds the one answer-again step the worker's plan already runs, so the
* answer after the plan and these count toward one cap,
* {@link MAX_ANSWERS_AGAIN} answers again per request. The take hands
* over nothing outside a turn a person's own message started, so in a
* over nothing outside a turn a user's own message started, so in a
* task's turn, or a turn a notice or another worker's message started,
* results arrive after the turn as before. Only on an installation, where
* the worker files tasks.
Expand Down
6 changes: 3 additions & 3 deletions packages/workforce/src/conversation-board/take-finished.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/**
* What finished while a person's turn ran (FIX-2159): the take that hands a
* What finished while a user's turn ran (FIX-2159): the take that hands a
* running turn the endings of the tasks its conversation filed, so the worker
* can answer again with them in the same request, rather than hear them after
* the reply as a turn of their own.
Expand All @@ -16,7 +16,7 @@
* answer-again step (`defineAgentWorkerFlow({ answerAgain: true })`): the
* take, then the lines as the message the worker answers again about.
*
* Only a turn a person's own message started takes anything (`isUserTurn`):
* Only a turn a user's own message started takes anything (`isUserTurn`):
* in a task session the queued handling also does the task's own ending work,
* and a worker talking to a worker keeps its turn order. Everywhere else the
* take hands over nothing, and endings arrive after the turn, as before.
Expand Down Expand Up @@ -71,7 +71,7 @@ function takes(notice: TaskNotice, resultTo: string | undefined): boolean {
/**
* Take the tasks this conversation filed that finished since the turn began,
* say each as a line under its delegate's name, and hand the lines back.
* Empty outside a turn a person's own message started, and when nothing
* Empty outside a turn a user's own message started, and when nothing
* finished. Input is ignored.
*/
export const takeFinishedTasks = handler({
Expand Down
4 changes: 2 additions & 2 deletions packages/workforce/src/conversation-board/task-settled.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@
* An ending frees its session (FIX-2080), so each notice also runs the board's
* pass when a row is startable: the pass, not this entry, starts it.
*
* A person's running turn may take a notice itself after it answers
* A user's running turn may take a notice itself after it answers
* (FIX-2159, `./take-finished`): it runs this same handling
* ({@link settleTakenNotice}) in its own request and says the line there, and
* the copy queued here then finds the notice cleared.
Expand Down Expand Up @@ -244,7 +244,7 @@ async function acknowledgeOnce(ctx: BlockContext, ref: TaskCollectionRef, row: T
}

/**
* A notice a person's running turn took itself (FIX-2159), handled as
* A notice a user's running turn took itself (FIX-2159), handled as
* `onTaskSettled` handles one: the same steps, in the same order, so the
* ending is heard once whichever request took it. Only what is said
* differs: the caller says the line in its own request rather than waking a
Expand Down
2 changes: 1 addition & 1 deletion packages/workforce/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ export {
steerTurnEntry,
type SteerTurnEntryOptions
} from "./conversation-board/steer";
// A person's running turn hears the tasks that finished while it answered
// A user's running turn hears the tasks that finished while it answered
// (FIX-2159): the take, the pre-built `answerAgain` source, and the cap on
// answers again in one request.
export {
Expand Down
38 changes: 19 additions & 19 deletions packages/workforce/test/answer-again-finished-tasks.test.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/**
* A person's running turn hears the tasks that finished while it answered
* A user's running turn hears the tasks that finished while it answered
* (FIX-2159): the worker answers, the answer-again step takes what finished
* (`takeFinishedTasks`), the line lands in that same request under the
* delegate's name, and the worker answers again with it. The queued
Expand Down Expand Up @@ -42,7 +42,7 @@ vi.mock("../src/conversation-board/ledger", async (original) => {
return {
...actual,
// A process that dies between the dedupe write and the acknowledgement, in
// a person's turn: the clear of a notice's marker never lands.
// a user's turn: the clear of a notice's marker never lands.
ownConversationLedger: async (ctx: Parameters<typeof actual.ownConversationLedger>[0]) => {
const ref = await actual.ownConversationLedger(ctx);
if (ref === undefined || !seams.failAckInUserTurn || !isUserTurn(ctx)) return ref;
Expand Down Expand Up @@ -81,7 +81,7 @@ const STEP = "You are working a step you filed for yourself";
type Turn = { requestId: string; kind: "turn" | "again" | "notice" | "step"; message: string };

type Controls = {
/** What the person's turn files for `eng.tasker`, or (with `self`) for the worker itself, as a step. */
/** What the user's turn files for `eng.tasker`, or (with `self`) for the worker itself, as a step. */
file: Array<{ id: string; goal: string; self?: boolean }>;
/** Held after the filing, before the turn answers: the endings land meanwhile. */
waitInTurn?: () => Promise<void>;
Expand Down Expand Up @@ -144,7 +144,7 @@ function deskFlow(installation: WorkerInstallation, controls: Controls, source:
inputSchema: doorInput.strict(),
block: door,
userMessage: (input: { message: string }) => input.message,
// The person's door holds the reply line, as the agent flow's does, so a queued notice waits for the reply.
// The user's door holds the reply line, as the agent flow's does, so a queued notice waits for the reply.
concurrency: REPLY_CONCURRENCY
},
...board.actions
Expand Down Expand Up @@ -176,13 +176,13 @@ function host(options: { source?: BlockDefinition<any, any>; marksUserTurn?: boo
await sleep(10);
}
};
/** The person's turn, through the host's dispatch: its request id, once every request settled. */
const ask = async (sessionId: string) => {
/** The user's turn, through the host's dispatch: its request id, once every request settled. */
const sendMessage = async (sessionId: string) => {
const requestId = await h.post("alice", sessionId, "respond", { message: "Find the facts" }, "desk");
await h.settled(20_000);
return requestId;
};
return Object.assign(h, { controls, ended, ask });
return Object.assign(h, { controls, ended, sendMessage });
}

async function deskSession(h: BoardHost): Promise<string> {
Expand All @@ -205,15 +205,15 @@ function textOf(item: any): string {
return ((item.content ?? []) as Array<{ text?: string }>).map((part) => part.text ?? "").join("");
}

describe("a person's turn hears a task that finished while it answered (FIX-2159)", () => {
describe("a user's turn hears a task that finished while it answered (FIX-2159)", () => {
it("says the result in that request, once, under the delegate's name, and the worker answers again with it", async () => {
const nonce = `n${Math.random().toString(36).slice(2, 8)}`;
const h = host({ source: finishedTasksAnswerAgain() });
try {
const session = await deskSession(h);
h.controls.file = [{ id: "t-1", goal: `Look up ${nonce}` }];
h.controls.waitInTurn = () => h.ended("t-1");
const respond = await h.ask(session);
const respond = await h.sendMessage(session);

const lines = (await delegateLines(h, session)).filter((line) => line.text.includes("(t-1)"));
expect(lines).toHaveLength(1);
Expand All @@ -228,7 +228,7 @@ describe("a person's turn hears a task that finished while it answered (FIX-2159
expect(h.controls.turns.filter((turn) => turn.kind === "notice")).toEqual([]);
const row = (await h.rows("alice")).find((r) => r.id === "t-1")!;
expect(row.metadata?.["noticeOwed:1:completed"] ?? null).toBeNull();
// Taken in the turn's name: the take record names the person's request.
// Taken in the turn's name: the take record names the user's request.
expect((row.metadata?.["noticeTaken:1:completed"] as { by?: string } | undefined)?.by).toBe(respond);
} finally {
await h.dispose();
Expand All @@ -241,7 +241,7 @@ describe("a person's turn hears a task that finished while it answered (FIX-2159
const session = await deskSession(h);
h.controls.file = [{ id: "t-1", goal: "Look up the fact" }];
h.controls.waitInTurn = () => h.ended("t-1");
const respond = await h.ask(session);
const respond = await h.sendMessage(session);
const lines = (await delegateLines(h, session)).filter((line) => line.text.includes("(t-1)"));
expect(lines).toHaveLength(1);
expect(lines[0]!.requestId).not.toBe(respond);
Expand Down Expand Up @@ -273,7 +273,7 @@ describe("a person's turn hears a task that finished while it answered (FIX-2159
const session = await deskSession(h);
h.controls.file = [{ id: "t-1", goal: "Look up the fact" }];
h.controls.waitInTurn = () => h.ended("t-1");
const respond = await h.ask(session);
const respond = await h.sendMessage(session);
const heard = h.controls.turns.filter((turn) => turn.kind !== "turn" && turn.message.includes("t-1"));
// In the reply, then again after it: the queued notice still owed it.
expect(heard.slice(0, 2).map((turn) => [turn.kind, turn.requestId === respond])).toEqual([
Expand Down Expand Up @@ -301,7 +301,7 @@ describe("a person's turn hears a task that finished while it answered (FIX-2159
release();
await h.ended("t-2");
};
const respond = await h.ask(session);
const respond = await h.sendMessage(session);
const lines = await delegateLines(h, session);
for (const id of ["t-1", "t-2"]) {
const said = lines.filter((line) => line.text.includes(`(${id})`));
Expand All @@ -321,14 +321,14 @@ describe("a person's turn hears a task that finished while it answered (FIX-2159
});
});

describe("only a turn a person's own message started takes a result (D2)", () => {
it("a turn no person's message started takes nothing: the result is heard after it, as before", async () => {
describe("only a turn a user's own message started takes a result (D2)", () => {
it("a turn no user's message started takes nothing: the result is heard after it, as before", async () => {
const h = host({ source: finishedTasksAnswerAgain(), marksUserTurn: false });
try {
const session = await deskSession(h);
h.controls.file = [{ id: "t-1", goal: "Look up the fact" }];
h.controls.waitInTurn = () => h.ended("t-1");
const respond = await h.ask(session);
const respond = await h.sendMessage(session);
const lines = (await delegateLines(h, session)).filter((line) => line.text.includes("(t-1)"));
expect(lines).toHaveLength(1);
expect(lines[0]!.requestId).not.toBe(respond);
Expand All @@ -349,7 +349,7 @@ describe("the take keeps the queued handling's guarantees (D1)", () => {
const session = await deskSession(h);
h.controls.file = [{ id: "t-1", goal: "[fail] Look up the fact" }];
h.controls.waitInTurn = () => h.ended("t-1");
const respond = await h.ask(session);
const respond = await h.sendMessage(session);
const lines = (await delegateLines(h, session)).filter((line) => line.text.includes("(t-1)"));
expect(lines).toHaveLength(1);
expect(lines[0]!.text).toContain("failed for good");
Expand All @@ -370,7 +370,7 @@ describe("the take keeps the queued handling's guarantees (D1)", () => {
const session = await deskSession(h);
h.controls.file = [{ id: "t-1", goal: "Look up the fact" }];
h.controls.waitInTurn = () => h.ended("t-1");
await h.ask(session);
await h.sendMessage(session);
const lines = (await delegateLines(h, session)).filter((line) => line.text.includes("(t-1)"));
expect(lines).toEqual([]);
expect(h.controls.turns.filter((turn) => turn.kind !== "turn")).toEqual([]);
Expand Down Expand Up @@ -401,7 +401,7 @@ describe("one answer-again step, under one cap", () => {
const session = await deskSession(h);
// A step the worker files for itself: the plan's source has its answer too.
h.controls.file = [{ id: "s-1", goal: "Outline it", self: true }];
const respond = await h.ask(session);
const respond = await h.sendMessage(session);
const again = h.controls.turns.filter((turn) => turn.kind === "again");
expect(again).toHaveLength(MAX_ANSWERS_AGAIN);
expect(again.every((turn) => turn.requestId === respond)).toBe(true);
Expand Down
Loading