Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
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
Prev Previous commit
Next Next commit
docs(orchestration): scope a wait's one hearing to a notice that wait…
…s behind the turn (FIX-2112)

Review 5627158643 on #3697.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A
  • Loading branch information
claude committed Oct 23, 2026
commit 07cbbbf2645815591eeaa6a97c99bcb1978cba03
2 changes: 1 addition & 1 deletion .changeset/wait-reads-an-ended-task-once.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@
"@flow-state-dev/orchestration": patch
---

A `getTask({ id, wait: true })` on a task that already ended returns it at once, and that answer is the filer's delivery: the ending no longer also starts an `onTaskSettled` turn. Task collection refs gain an optional `dropNoticeReadByWait(id)`, which both built-in backings implement; a ref without it keeps the old behaviour (FIX-2112).
A `getTask({ id, wait: true })` on a task that already ended returns it at once, and that answer is the filer's delivery: when the flow's `onTaskSettled` waits behind the turn that filed the task, as Workforce's turns make it, the ending's notice request still runs but no longer calls your block. Task collection refs gain an optional `dropNoticeReadByWait(id)`, which both built-in backings implement; a ref without it keeps the old behaviour (FIX-2112).
5 changes: 3 additions & 2 deletions apps/docs/docs/orchestration/task-board.md
Original file line number Diff line number Diff line change
Expand Up @@ -846,8 +846,9 @@ getTask({ id: "task_8f2", wait: true })
You can wait in the same turn or in a later one. Your turn pauses until the task ends, then
carries on with the task as `getTask` always returns it: its status, and its output once it
completed. Nothing holds a request open while it waits, so a server restart loses nothing.
If the task already ended when you wait, you get it back at once, and that answer is how you
hear about it: no `onTaskSettled` turn follows.
A task that already ended is returned at once, and no `onTaskSettled` follows for it, as long
as your `onTaskSettled` waits behind the turn that filed the task. A Workforce conversation or
task turn works that way. The request still runs, but your block isn't called.

A wait has a deadline, five minutes unless you pass `deadline` in milliseconds. At the deadline
your turn carries on with the task as it stands, usually still `in_progress`. Nothing is
Expand Down
8 changes: 5 additions & 3 deletions packages/orchestration/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -988,9 +988,11 @@ See [Per-generator binding](https://flow-state.dev/docs/skills/binding) for the
`getTask({ id, wait: true, deadline? })` parks the calling turn on a task its session filed,
until the task ends or the deadline passes, and returns the task as `getTask` always does. The
deadline is milliseconds from the call, five minutes by default, within the host's
`waitDeadlines` bounds. A task that already ended is returned at once, and its ending starts no
`onTaskSettled`: the wait's answer delivered it. At the deadline the task runs on and nothing is cancelled. If it ends
before the waiting request does, that request's next `getTask` on it returns the ending. If
`waitDeadlines` bounds. A task that already ended is returned at once, and no `onTaskSettled`
follows for it when the flow's `onTaskSettled` waits behind the turn that filed the task, as
Workforce's `respond` and `work` turns make it: the request still runs, but your block isn't
called. At the deadline the task runs on and nothing is cancelled. If it ends before the
waiting request does, that request's next `getTask` on it returns the ending. If
the request ends without reading it, the ending goes to `onTaskSettled`, once. Waits nest: a
task's own turn may wait too. A wait is refused when it would make a chain of more than five
waits (`MAX_WAIT_DEPTH`), counting the waits above you and any already below the task you wait
Expand Down
Loading