diff --git a/specs/issues/FIX-2159/DECISIONS.md b/specs/issues/FIX-2159/DECISIONS.md new file mode 100644 index 0000000000..416fc08814 --- /dev/null +++ b/specs/issues/FIX-2159/DECISIONS.md @@ -0,0 +1,174 @@ +# FIX-2159 · Decisions + +[Spec](SPEC.md) · **Decisions** + +The epic already decided *that* a result reaches the running turn ([FIX-2152 D2](../../epics/FIX-2152/DECISIONS.md#d2)), +and its merge approved the amendment to rule 7. These three decide *how*, and each has a +consequence a person can see. + +## The tree + +```mermaid +flowchart TD + I["FIX-2159"] --> D3["D3 · the app's block feeds the one answer-again step · the package adds only the take"] + D3 -.->|"rejected"| X3a["all in the lab · every result heard twice"] + D3 -.->|"rejected"| X3b["the package reads results before every model call · a loop the app can't see"] + D3 -.->|"rejected"| X3c["a hook with its own loop and cap · a second way to answer again"] + I --> D1["D1 · the take is FIX-2123's take record, in the turn's name"] + D1 -.->|"rejected"| X1["a new taken-in-R list · a second mark to keep in step"] + I --> D2["D2 · only a turn a person's message started takes one"] + D2 -.->|"rejected"| X2["any running request · skips a task's own ending work"] +``` + +Solid edges are what you're signing. Dashed edges lost, and the label says why. + + +## D3 · The app's block feeds the one answer-again step `planned` already runs; the package adds only the take + +*From the build Jake prefers, relayed on the epic's handle: the end-of-turn loop lives in the +lab's flow. Tested against the lab bar before it was drafted.* + +| | | +|---|---| +| **Instead of** | (a) All of it in the lab, on public entries only. (b) The package reading results before every model call, through a context entry like the steer one, and answering once more itself. (c) A hook on the agent flow with its own answer-again loop and its own cap of three, beside `planned`'s | +| **Because** | (a) fails on public entries: nothing public takes a notice, and the agent flow has no step that may answer again (`afterAnswer` is a side step that can't change the answer). A lab that only *reads* finished rows leaves the notice owed, so the queued `onTaskSettled` says the line and wakes a second turn after the reply: heard twice ([POC](poc/take-in-turn/README.md), control). A lab that takes them itself must also report a failure, dedupe and free the delegate's session, which is package work in the lab (ER-4). (b) works, but the loop is package code no app can see or change, and the before-each-call read is a second mechanism step 4 doesn't need. (c) works, and was this card's first draft, but `planned` (FIX-2076) already answers once more after a turn in the same request: a second step with a second limit is a second way to answer again | +| **Locks in** | `planned`'s answer-once-more step, extracted into one block with two sources (the plan's ended steps, and finished tasks) and one exported cap on answers again per request, the plan's included, built on core's `doWhile`. One option on the agent worker flow, `answerAgain`: `true` for the package's pre-built block (an exported factory: take, then turn the lines into a message), or a block that replaces it. A block underneath either way, never one the app must write. It adds no loop and no cap. The person's door is built inside the factory and `afterAnswer` can't answer, so without the option nothing can run after the turn. One public take, a handler block the workforce package exports, that hands over what finished, once. An app that sets no source behaves as today. A result that lands during a long tool loop waits for that answer to end, and one that lands after the last look waits for the turn to end, as today | + +![D3: the app's block feeds the shared answer step and the package takes, chosen, beside all in the lab and the package reading before every call; decided by hearing each result once](figures/d3-app-flow-answers-again.svg) + +It comes down to hearing each result once: the lab alone can read a result but can't take it. + +**What would change my mind:** the lab bar allowing a lab to call the package's notice handling +directly. Then the take could be lab code, and the package adds only the source slot. Or the agent +flow gaining a public way to compose its door: then the slot goes too, and the lab wraps the turn itself. + + +## D1 · The take is FIX-2123's take record, written in the turn's name, with the queued handling's order + +| | | +|---|---| +| **Instead of** | A new "taken in request R" list on the conversation, kept like `steersTakenIn` on a task | +| **Because** | `onTaskSettled` already takes a notice in one conditional write that names its request, keeps that record after the clear, and takes a notice over once its taker ended without clearing it (FIX-2123). A turn that takes in its own name gets all three for nothing. The [POC](poc/take-in-turn/README.md) runs it on the real engine: taken in the turn and skipped by the queued copy; refused when the copy took it first; taken over after a turn that failed before clearing it | +| **Locks in** | A result taken in the turn has exactly the guarantees of one after the turn: never twice, and taken over if the turn dies before its dedupe write. The take goes only through `takeNotice` with `by:` the turn's request: no new metadata key, and no read or write of the running-filer hold (`heldFor`, `whileRunning`). The order is the queued handling's: take, report a failure, dedupe, free the session, acknowledge, then the line, with the part from report to acknowledge one function the queued `settle` shares. The point of no return is the dedupe write (`noteSeen`), which comes before the acknowledgement: a copy that takes over after it finds the key seen and says nothing. A process death from the dedupe write to the line drops the line, as it does today | + +![D1: the existing take record in the turn's name, chosen, beside a new taken-in-R list; decided by one mark that the queued entry already obeys](figures/d1-one-take-record.svg) + +It comes down to one mark: a second one is a second rule the queued entry would have to learn. + +**What would change my mind:** a store that can't keep the take record after the clear. Then +the turn needs its own list, and this card becomes the rejected one. + + +## D2 · Only a turn a person's own message started can take a result + +| | | +|---|---| +| **Instead of** | Any running request of the filer's session: a turn a notice woke, a message from another worker (`receive`), a task's turn | +| **Because** | In a task session the queued handling also does the task's own ending work (`admitOwnTask`), and the entry refuses a notice once it is cleared, so a take there would skip it (epic D2). A `receive` is talk between workers, and its turn order is FIX-1989's. `isUserTurn` already marks exactly a person's turn in a conversation, and skips task and delegate sessions | +| **Locks in** | The take hands over nothing outside a person's turn, whatever the app's block asks. A coordinator's woken turn, a worker answering another worker, and a worker on a task hear results after the turn, as today. Widening it later is a new decision, not a flag. Two edges: the coordinator's round-0 post carries the mark, so it passes the gate, but this issue adds no source to the coordinator flow and its delegates' answers are routed, which the take never hands over. A person's request parked on a wait isn't running, so an ending during the park goes the queued way, as today | + +![D2: a person's own turn only, chosen, beside any running request of the session; decided by never skipping the task's own ending work](figures/d2-person-turn-only.svg) + +It comes down to the task's own ending work: a take outside a person's turn can skip it. + +**What would change my mind:** a lab script that needs a worker on a task to hear a result +mid-turn. Then a task session's take has to carry `admitOwnTask` with it, which is a larger change. + +## Decided, not asked + +- **Which notices the take hands over:** the ones the queued handling says as a line or a woken + turn, for a task whose result goes to the filer: a completion, a final failure, a cancel someone + else made, a park that asks. Not a routed result, a retried marker, a held marker or a waited-on row. +- **The visible item is the queued handling's own line**, under the delegate's name, said in the + turn's request by the take. FIX-2153 draws it; no new item kind. The take returns each line's + words so the app can put them in its message. +- **One ending path.** The take runs Workforce's existing handling for a notice, with "say the line + here and hand it back" in place of "say the line and wake a turn". Shared, never copied. +- **A failure the Error Reporter didn't take** stops the take before the acknowledgement. The take + stays with the turn, the result isn't handed back, and the queued copy hears it after the turn. +- **The take reads committed rows**: a turn's snapshot of the board never shows an ending written + after it started (POC, case 1). It reads rows this conversation filed that still owe an + eligible notice, finished rows included, never only open ones. +- **The cap is the shared step's.** At most three answers again per request, the plan's + included, so a source that always returns a message can't loop a turn forever. One named, + exported constant, apart from core's `maxSteps` and the board's `MAX_PASS_ROUNDS`. After the last + allowed answer no source runs and the take hands over nothing: endings stay owed for the queued + `onTaskSettled`. +- **Where it runs.** Wherever `planned` does: every turn of the worker on an installation. In a + task or notice turn the take hands over nothing (D2), so the step answers only for the plan, as + today. An answering turn files no step for itself, as `planned`'s does today; a task for a + delegate is still dispatched. +- **At most once, as today.** The take dedupes and acknowledges before it says the line, the + queued handling's order. A death before the dedupe write (`noteSeen`): the queued copy takes it + over and says it after the turn. A death after it, the acknowledgement included: the line is + dropped, because the copy finds the key seen. No idempotency key on the line. The window is the + queued handling's own today; the shared function keeps it, and the implementer's tests cover a + death between the dedupe write and the acknowledgement. + +## Considered and dropped + +| Alternative | Why not | +|---|---| +| Condition 2 in the issue text: a request holding the filer task's claim may take | Superseded by epic D2 at `a070af58`: the queued handling's `admitOwnTask` would be skipped | +| Run the queued `onTaskSettled` block from inside the turn | A handler doesn't call blocks (BP-011), and the woken-turn half has no place in a running turn | +| Stop the model loop from ending while a notice is owed | Needs a core change; the epic keeps this out of core and engine | +| One flag on the flow that turns the behaviour on: the package owns the take and the answer again, the app only opts in | The smallest public surface, one option instead of a source and a take. It loses on what the app decides: the app can't choose what the worker hears or how it's put, and Jake asked for that in the lab's flow as a showcase | + +## Settled + +Evidence for both is in [`poc/take-in-turn/`](poc/take-in-turn/README.md), on `main` at `3d131544`. + +- **The take record carries a take in the turn, at most once and never lost before the + acknowledgement** — **CONFIRMED** for the take record: cases 1 to 4b, with the line said after + the acknowledgement; case 1 red with the turn's clear removed. The POC has no dedupe write, so + with Workforce's handling the boundary moves earlier, to `noteSeen` (see *At most once* above; + Codex, review round 4). +- **A lab can do the end-of-turn loop on public entries alone** — **REFUTED**: case 5, a turn that + only reads the finished row, is heard twice. The public surface has no take and no + answer-again step (`afterAnswer` is a side step). +- **D2 is not POC evidence.** It rests on the epic's D2 and on reading `isUserTurn`. + +## How it got here + +- **Draft** — the epic's "one durable mark like `steersTakenIn`" turned out to exist as FIX-2123's + take record; the POC confirmed it, so D1 reuses it. +- **Before review** — Jake's preferred build (relayed on the epic's handle) put the end-of-turn + loop in the lab's flow. Tested against the lab bar: the loop fits, the take doesn't. D3 replaced + a package-run answer and a before-each-call context entry with a hook and a public take. +- **Review round 1** — the crash guarantee stated as at most once in the goal (it had read as + no loss); the hook placed on the person's door after the plan's answer; one-flag shape named + as dropped. +- **Review round 2** — Architect's follow-up: the take touches only the take record, never the + hold; the shared handling named as one function with two callers; the bound exported and + closed after its last answer; `planned`, the round-0 post, a park and messages placed. Jake asked + whether this was a block: both pieces are now blocks, the hook a block slot like `afterAnswer`. +- **Review round 3** — Architect: the hook was a second answer-again beside `planned`'s. The step + `planned` uses is now the one answer-again step, with the app's block as a second source and one + cap. Asked to drop the slot entirely; kept as a source only, because the person's door is built + inside the factory and has no other seam (`agent-worker-flow.ts`, `agent-user-turn`). `planned` + answers once with no loop today, so the cap is new to it, not shared from it. +- **Jake** — the option shouldn't require a block: `answerAgain: true` uses the package's + pre-built block, and a block overrides it. A block underneath either way. + +## Notes from review + +- "Have the implementer look at whether `planned`'s loop and the new hook can share one bounded + 'answer again' step (hook supplies the message, `planned` supplies its own). If they can't + share, say why." — second-look review ([review](https://github.com/fixpoint-labs/flow-state-dev/pull/3799#pullrequestreview-5634917017)) +- "The implementer's tests should own the interaction with `planned` explicitly, with the + Error Reporter stop-before-ack and the answer-again bound." — same review + +- "Parameterize `task-settled.ts` (a delivery mode) rather than a second copy of + report/dedupe/free/line order, or FIX-2115, routed and Error Reporter paths drift." — cursor + ([thread](https://github.com/fixpoint-labs/flow-state-dev/pull/3799#discussion_r4364611470)) +- "Finding owed rows: reuse the `owesAnyNotice` prefilter, avoid a full scan plus a committed + read per candidate on every hook call, cap work when many tasks finish together." — cursor + ([thread](https://github.com/fixpoint-labs/flow-state-dev/pull/3799#discussion_r4364611475)) +- *(Adopted after Jake's comment: `answerAgain: true` uses a pre-built block from an exported factory; a block overrides it.)* + "Consider exporting a default `answerAgain` helper (take, format the lines) that an app can use + or override, so each app doesn't copy the same body; the loop stays visible in the flow." — + cursor ([thread](https://github.com/fixpoint-labs/flow-state-dev/pull/3799#discussion_r4364611466)) + +These are inputs, not instructions. Adopt, adapt, or discard. + +**Open: none.** diff --git a/specs/issues/FIX-2159/SPEC.md b/specs/issues/FIX-2159/SPEC.md new file mode 100644 index 0000000000..1ba530d2d4 --- /dev/null +++ b/specs/issues/FIX-2159/SPEC.md @@ -0,0 +1,178 @@ +# FIX-2159 · A person's running turn hears the tasks that finished while it ran + +**Spec** · [Decisions](DECISIONS.md) + +## People, before and after + +| Someone who… | Today | After | +|---|---|---| +| **asks the main session for work, and it starts two background tasks** | Sees the first result only after the reply ends, as a second turn that answers again | Sees the result appear in the reply that is still running, and the same reply answers once more with it | +| **builds an app on Workforce and wants that behaviour** | Can't: nothing public takes a result, and reading one leaves the after-the-turn notice to say it again | Sets `answerAgain: true` on the agent flow, or passes a block to change what the worker is told ([D3](DECISIONS.md#d3)) | +| **has a worker that runs a task, or two workers talking** | Results arrive after the turn | Unchanged. Only a turn a person's own message started can take one ([D2](DECISIONS.md#d2)) | +| **gets a failed result the Error Reporter didn't take yet** | Heard after the turn, once reported | Unchanged: the take never hands over a failure that wasn't reported | +| **loses the process mid-reply** | The result is never heard twice. A death after the dedupe write (`noteSeen`, just before the acknowledgement) drops the line | The same, both ways ([D1](DECISIONS.md#d1)) | + +Claude Code shows a background result inside the running turn. Step 4 of FIX-2153's script asks +for it, and the epic signed it as [D2](../../epics/FIX-2152/DECISIONS.md#d2). + +## The goal, and how we'll know it's met + +**A person who asks the main session for work that starts background tasks sees the first +result inside the reply that is still running, once, and that reply goes on to use it.** + +| Is it the right goal? | | +|---|---| +| **The real need** | The epic's leg a, step 4: "one result shows in the main thread while that turn is still running" ([FIX-2152](../../epics/FIX-2152/SPEC.md#the-goal-and-how-well-know-its-met)). FIX-2153's signal 4 checks that the result, the working indicator and the later text share the first request's id | +| **Smaller, and rejected** | "The app reads finished tasks after its answer." Doable in the lab today, and every result is then heard twice: once by the lab, once by the notice turn after the reply ([D1](DECISIONS.md#d1)) | +| **Bigger, and not this issue's** | A message from another worker reaching a running turn. A message is not an ending (FIX-2103); FIX-2070 owns where messages land | +| **Not done if** | The result shows only in a second request · it is heard twice · a crash before the dedupe write loses it (after it the line is dropped, as today: at most once) · the app can't choose what the worker answers about | + +```mermaid +flowchart LR + I["main worker · real model · files two tasks to a fast delegate"] --> M["leg 1 · first ending lands while the reply runs · leg 2 · second lands during the answer again"] + M --> S["the session's items"] + S -->|"each result line in the respond request, once, then text that uses it"| P["PASS · goal met"] + C["control · the app reads without taking"] -.-> M + S -.->|"under the control"| F["must FAIL · the result is said twice"] +``` + +The check reads the session's items, which is what the lab draws, never the take record. + +| How we verify | | +|---|---| +| **Goal check** | `goals/hand-offs/result-reaches-the-running-turn/` · `openai/gpt-5.4-mini` · run by the implementer at completion · verdict in the implementation PR | +| **Signal** | Each result line under the delegate's name carries the respond request's id, appears once in the session, and is followed in that request by text naming the result's nonce | +| **Input** | Each delegate answers with a nonce fixed per run. A different nonce, or the second task ending first, must pass too | +| **Anti-game** | Don't assert on the take record, the app block's return or a mocked model. All three pass while the line lands in a second request | +| **Control that must fail** | `GOAL_CONTROL=read-only`: the app's block reads finished rows instead of taking them. It must FAIL on *appears once in the session*, and today's `main` on *carries the respond request's id*. The PR shows both FAILs before the PASS | + +## What changes + +![Three timelines of one person's turn. Today the ending waits and a second request answers; after, the app's flow takes it when the answer ends and answers again in the same request; a second ending during that answer loops once more](figures/what-changes.svg) + +The top row is today. The middle row is the take after the answer and the answer again; the +bottom row is a second ending, which loops once more within the bound ([D3](DECISIONS.md#d3)). + +**The app's side, as a lab writes it in its flow file:** + +```diff + export default defineAgentWorkerFlow({ + installation, ++ // In the same request, answer again with anything that finished while the worker answered. ++ answerAgain: true + }); +``` + +`true` uses the package's pre-built block. An app that wants its own wording passes a block +instead, usually the package's factory with an option, or its own sequencer around the take: + +```ts +answerAgain: sequencer({ name: "lab-answer-again" }) + .step(takeFinishedTasks) + .step(handler({ + name: "lab-finished-message", + execute: (finished) => finished.length === 0 ? {} : { message: `Done while you answered:\n${finished.map((f) => f.line).join("\n")}` } + })) +``` + +**One way to answer again, not two.** `planned` (FIX-2076) already wraps every turn of the +worker: the turn runs, its steps drain, and the worker answers once more, told how each step +ended. That answer-once-more step is extracted into one block with two sources: the plan's +ended steps, and the app's `answerAgain` block. After the turn it answers while a source has a +message, under one exported cap, built on core's `doWhile` as the board's round loop is. The +plan's answer counts toward the cap like any other. An answering turn files no step for itself, +as `planned`'s does today; a task for a delegate is still dispatched. After the last allowed +answer no source runs, so later endings stay owed for the queued `onTaskSettled` rather than +being taken with no answer to use them. + +**A block underneath, never required.** The option is `true` or a block. `true` is the +package's pre-built block from an exported factory: take what finished, then turn the lines into +a message. A block replaces it. Either way the source is a block, so it shows in the trace and +composes like any other. An option is needed at all because the person's door is built inside the +factory (`agent-user-turn` runs `run`), and its one seam, `afterAnswer`, is a side step that can't +answer. The option adds no loop and no cap of its own: it is a second source for the existing +step. `takeFinishedTasks` is a handler the package exports. All names are working names. + +**Where it runs.** Wherever `planned` does, which is every turn of the worker on an installation. +The take hands over nothing outside a person's turn ([D2](DECISIONS.md#d2)), so in a task or +notice turn the app's source finds nothing and the step answers only for the plan, as today. + +**Docs:** rule 7 of `docs/internal/design/workforce-coordination-concept.md` gains the third +destination. The workforce README documents the `answerAgain` source and the take, with the lab's lines as the +example. No `apps/docs` page. + +## How it reaches the turn + +```mermaid +flowchart LR + D["delegate's request · records the ending"] -->|"owed marker on the row"| B["conversation ledger"] + A["person's turn · the answer ends"] -->|"the shared answer step asks the app's block, which calls the take"| K["takeFinishedTasks"] + K -->|"committed read · take in the turn's name · handle · acknowledge"| B + K -->|"line under the delegate's name"| S["session items"] + K -->|"message"| A2["the same turn answers again"] + B -.->|"after the turn · finds nothing owed"| Q["queued onTaskSettled"] +``` + +The take is the package's; the decision to answer again is the app's. The queued copy then +finds nothing owed ([POC](poc/take-in-turn/README.md)). + +## What stays as it is + +- **Core and engine.** The model loop and request concurrency are untouched. +- **Rules 5 and 6.** A take records no ending and settles nothing. +- **The queued `onTaskSettled`.** It still runs for every notice no turn took: in a task session, + in a worker-to-worker exchange, between turns, after a crash, and in any app that sets no `answerAgain` source. +- **A wait.** A request waiting on the task with `getTask` resumes with the result; that row owes + no notice to take. +- **Routed results.** A task whose result goes to the conversation stays with its routing. +- **`afterAnswer`.** It stays a side step that can't change the answer. +- **Messages.** A message from another worker, including FIX-2070's coming `{ session: id }` form, never goes through the take. It is not an ending (FIX-2103), so FIX-2070's spec doesn't widen it. +- **A parked turn.** While the person's request is parked, the queued copy isn't held for it, so an ending during a park goes the queued way. The take runs only in a running request, after an answer. + +## What's already here, and the debt + +| Already here | What this does with it | +|---|---| +| FIX-2123's take record: `takeNotice` / `noticeTakeWrite`, the `noticeTaken:` record, the takeover once a taker ended | **Builds on.** The take goes only through `takeNotice` with `by:` the turn's request. It is the durable "taken in R" mark: no new metadata key ([D1](DECISIONS.md#d1)) | +| The hold on a running filer: `heldFor`, the deferred notice's `whileRunning` (FIX-2123, FIX-2149) | **Neither read nor written by the take**, so `held`, `noticeTaken` and `whileRunning` can later fold into one marker. The queued copy turned away with `whileRunning: R` while R runs comes back after R, finds the notice cleared, and does nothing | +| FIX-2078's one ending path: `taskSettledEntry` and Workforce's handling in `task-settled.ts` | **Factors, then builds on.** The end, report, dedupe (`noteSeen`) and acknowledge part of the queued `settle` becomes one function that `settle` and the take both call. One handling, two callers: only where the line goes differs, said here and handed back, or a woken turn | +| FIX-2086's steer entry (`steer-context.ts`, `steersTakenIn`) | **Leaves alone.** It stays task-only; nothing reads a result before each model call | +| `isUserTurn` (FIX-1945) | **Builds on.** The gate inside the take ([D2](DECISIONS.md#d2)) | +| The worker turn's answer-once-more after its plan (FIX-2076) | **Extracts and shares.** It becomes the one answer-again step, with the plan and the app's block as its two sources and one exported cap. No second answer-again | +| `afterAnswer` on the agent flow | **Leaves alone.** A side step that can't answer, which is why the app's source needs its own slot | +| `AFTER_REPLY_CONCURRENCY` | **Leaves alone.** The queued copy still waits; with a source set it usually finds nothing owed | +| `maxSteps` (core, the tool loop) and `MAX_PASS_ROUNDS` (the board's drain rounds) | **Leaves alone.** The shared step's cap counts answers again in one request, which neither counts. Built on `doWhile` like the round loop | +| Rule 7 | **Amended** by epic D2, approved at its merge | +| Anything else that hands an ending to a running request | **None for a conversation.** Searched `prepareStep`, `takeNotice`, `takenIn`, `noticeTaken`, `afterAnswer` across `packages/`; only steers reach a running request, and only a task's | + +| The debt | | +|---|---| +| **Removes** | Nothing | +| **Adds** | One public take on the workforce package · one source slot on the agent worker flow, feeding an existing step · one exported cap on that step · a second caller of the take record and of the factored handling, the person's turn | +| **Leaves** | The queued notice turn, as the path for every notice no turn took. Not debt: task sessions and worker-to-worker exchanges still need it | + +**Net: up, a little.** One public take and one source slot; no new mark, no second ending path, no second answer-again, no context entry. + +## Sign off + +**[The goal](#the-goal-and-how-well-know-its-met):** the result shows inside the running reply, +once, measured on the session's items. If wrong: the lab's step 4 passes while the person sees +the result twice. + +**[The debt](#whats-already-here-and-the-debt), up a little:** a public take and a source slot +on the answer step `planned` already runs, nothing removed. If wrong: two callers of one ending +handling that someone must keep in step. + +1. **[D3](DECISIONS.md#d3) · Finished tasks feed the one answer-again step `planned` already + runs (`answerAgain: true`, or a block to override); the package adds only the take and its + default block.** If wrong: a factory option stands where a public way to compose the person's + door should be. +2. **[D1](DECISIONS.md#d1) · The take is FIX-2123's take record, in the turn's name, with the + queued handling's order.** If wrong: a result taken in the turn has weaker guarantees than one after it. +3. **[D2](DECISIONS.md#d2) · Only a turn a person's own message started can take a result.** If + wrong: a worker on a task, or two workers talking, wait for results Claude Code would show at once. + +**Open: none.** D3 is the one to weigh: the app decides what to answer about, the package keeps +one way to answer again and the part a lab can't do safely, the take. + +Feature · `workforce` · small · epic [FIX-2152](../../epics/FIX-2152/SPEC.md) diff --git a/specs/issues/FIX-2159/figures/d1-one-take-record.svg b/specs/issues/FIX-2159/figures/d1-one-take-record.svg new file mode 100644 index 0000000000..a6b6bc279f --- /dev/null +++ b/specs/issues/FIX-2159/figures/d1-one-take-record.svg @@ -0,0 +1,95 @@ + + + + + + D1 · THE CALL + What marks a result as taken by the running turn? + + + + CHOSEN + FIX-2123's take record + + INSTEAD OF + A new taken-in-R list + + + + + THE QUEUED + ENTRY OBEYS IT + ▸ DECIDES IT + + + Already, today + skips, waits, takes over + − + Only once taught to + a second rule to keep in step + + + CRASH + SAFETY + + + Proven by the POC + taken over after a failed turn + = + Same, once built + the same write, written again + + + + WHAT IT + COSTS + − + Two kinds of taker + the entry or a person's turn + − + A new field + and its read-back + + + + + LOCKS IN + A result taken in the turn has today's guarantees + never twice; a death after the ack drops the line, as today + + + + FLIPS IF + A store can't keep the take record after the clear + then the turn needs its own list + + diff --git a/specs/issues/FIX-2159/figures/d2-person-turn-only.svg b/specs/issues/FIX-2159/figures/d2-person-turn-only.svg new file mode 100644 index 0000000000..28ee2c265c --- /dev/null +++ b/specs/issues/FIX-2159/figures/d2-person-turn-only.svg @@ -0,0 +1,95 @@ + + + + + + D2 · THE CALL + Which running requests may take a finished task's result? + + + + CHOSEN + A person's own turn only + + INSTEAD OF + Any running request + + + + + A TASK'S OWN + ENDING WORK + ▸ DECIDES IT + + + Always runs + the queued handling keeps it + − + Can be skipped + a cleared notice is refused + + + WHAT A PERSON + SEES + = + The main session + as Claude Code shows it + = + The main session + and more no script needs + + + + WORKERS ON TASKS + AND WORKER TALK + − + After the turn + as today + + + Mid-turn + if the take carried admitOwnTask + + + + + LOCKS IN + A take outside a person's turn hands over nothing + whatever the app's hook asks + + + + FLIPS IF + A lab script needs a task session to hear it mid-turn + then the take must carry admitOwnTask + + diff --git a/specs/issues/FIX-2159/figures/d3-app-flow-answers-again.svg b/specs/issues/FIX-2159/figures/d3-app-flow-answers-again.svg new file mode 100644 index 0000000000..0d4c6cdd60 --- /dev/null +++ b/specs/issues/FIX-2159/figures/d3-app-flow-answers-again.svg @@ -0,0 +1,107 @@ + + + + + + D3 · THE CALL + Who notices a finished task at the end of an answer, and who takes it? + + + + CHOSEN + App's block · shared answer step + + INSTEAD OF + All in the lab + + INSTEAD OF + Package, every model call + + + + + EACH RESULT + HEARD ONCE + ▸ DECIDES IT + + + Once + the take clears the notice + − + Twice + read here, said again after + + + Once + the take clears the notice + + + WHERE THE + LOOP LIVES + + + The plan's answer step + the app's block says what about + + + The app's flow file + but glue for package work + − + Package code + no app can see or change it + + + + NEW PACKAGE + ENTRIES + − + A take and a source slot + on the step the plan already runs + + + None + the lab carries it all + − + A context entry + and an answer step + + + + + LOCKS IN + One answer-again step, shared with the plan + fed by the app's block and a public take; one exported cap + + + + FLIPS IF + A lab may call the notice handling directly + then the take is lab code and only the source slot is new + + diff --git a/specs/issues/FIX-2159/figures/what-changes.svg b/specs/issues/FIX-2159/figures/what-changes.svg new file mode 100644 index 0000000000..3b4daa4be3 --- /dev/null +++ b/specs/issues/FIX-2159/figures/what-changes.svg @@ -0,0 +1,99 @@ + + + + + + ONE PERSON'S TURN · REQUEST R · TIME RUNS RIGHT + ◆ a task ends · ┃ the take · ● the result line in the session · grey bar = a request + + + TODAY + line waits for the reply + R + + answer · tool calls · last text + + task 1 ends + + A SECOND REQUEST + + notice turn answers again + + + + + AFTER + taken at the answer end + R + + answer + + task 1 ends + + + + answer again · shared step + line in R + queued copy, after R:finds nothing owed + + + + A SECOND ENDING + loops again, at most 3 + R + + answer + + task 1 ends + + + + answer again + + task 2 ends + + + + answer again + + diff --git a/specs/issues/FIX-2159/poc/take-in-turn/README.md b/specs/issues/FIX-2159/poc/take-in-turn/README.md new file mode 100644 index 0000000000..a96fc9d384 --- /dev/null +++ b/specs/issues/FIX-2159/poc/take-in-turn/README.md @@ -0,0 +1,59 @@ +# POC · a running turn takes a settled notice through the existing take record + +Retained design evidence for [FIX-2159](../../SPEC.md). Throwaway code, excluded from every +default test and typecheck run: nothing under `specs/` is in a package's vitest `include` or +`tsc` roots, and ESLint ignores `specs/**/poc/**`. `run.sh` copies the case into +`packages/orchestration/test/tasks/` for the run and removes it afterwards. + +```bash +bash specs/issues/FIX-2159/poc/take-in-turn/run.sh +``` + +## The question + +Epic D2 asks for "one durable *taken in request R* mark, like `steersTakenIn`", and changes its +mind if the take can't be made crash-safe. `onTaskSettled` already writes a durable take record +naming its request (FIX-2123), and a later copy takes the notice over once that request ended +without clearing it. Can a **running conversation request** take the notice in its own name +through that same record, so the queued `onTaskSettled` copy never handles it twice and never +loses it? + +## What it runs + +The real engine, a durable host, a resource-backed board. A `respond` action stands in for the +person's turn: it reads the board, waits on a gate (a model call), then does what the context +entry would do before its next model call: a committed read, `takeNotice({ by: its request })`, +the clear, and only then the line (the queued handling's order, D1). The ending is written by another request while the turn waits. Then the +queued `onTaskSettled` copy runs, as it does after the turn. + +## What it showed · 2026-10-23, on `main` at `3d131544` + +``` +✓ 1+2 · sees the ending by a committed read, takes it, and the queued copy finds nothing owed +✓ 3 · when the queued copy took it first, the turn's take is refused: heard once, by the copy +✓ 4 · a turn that took it and failed before its acknowledgement: the copy takes it over, heard once +✓ 4b · a turn that failed after its acknowledgement, before its line: dropped, never twice (at most once) +✓ 5 · a turn that only reads the finished row: the queued copy says it again, heard twice +Tests 5 passed (5) +``` + +- The turn's own snapshot of the board does **not** show the ending (`sawInSnapshot: false`); a + committed read does. The context entry must read committed, as `takeRunningSteers` does. +- The take record stays after the clear, naming the turn's request: that is the durable + "taken in R" mark, the way `steersTakenIn` names the read that took a steer. +- **Control:** with the turn's clear removed, case 1 goes red (`expected { owed: true, … } to + deeply equal { owed: false }`): the queued copy takes the notice over and it is heard twice. + So the check reaches the clear. + +## Verdict + +**CONFIRMED.** No new mark is needed: the take record FIX-2123 added is crash-safe and already +transfers a notice between requests in one conditional write. [D1](../../DECISIONS.md#d1) rests +on this. + +Case 5 is the evidence that a lab can't do this on public entries alone +([D3](../../DECISIONS.md#d3)): a turn that reads a finished row without taking it leaves the +notice owed, and the queued copy hears it again. Cases 4b and 5 were added in review; all five are green on the same base. + +Not covered here, and left to the implementation's tests: the Workforce handling (Error Reporter, +dedupe, freeing the session, the line) and the answer-again hook. diff --git a/specs/issues/FIX-2159/poc/take-in-turn/run.sh b/specs/issues/FIX-2159/poc/take-in-turn/run.sh new file mode 100755 index 0000000000..ded0de003c --- /dev/null +++ b/specs/issues/FIX-2159/poc/take-in-turn/run.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env bash +# Run the FIX-2159 POC from the repository root: +# bash specs/issues/FIX-2159/poc/take-in-turn/run.sh +# +# Not a package: the case is copied into packages/orchestration/test/tasks for +# the run (where `../../src` and `@flow-state-dev/*` resolve, and which the +# package's vitest config already includes), and removed afterwards. +set -euo pipefail +here="$(cd "$(dirname "$0")" && pwd)" +root="$(cd "$here/../../../../.." && pwd)" +dest="$root/packages/orchestration/test/tasks/zz-fix2159-take-in-turn.poc.test.ts" +cp "$here/take-in-turn.poc.test.ts" "$dest" +trap 'rm -f "$dest"' EXIT +cd "$root/packages/orchestration" +env -u FSDEV_DEFAULT_MODEL ../../node_modules/.bin/vitest run "test/tasks/$(basename "$dest")" "$@" diff --git a/specs/issues/FIX-2159/poc/take-in-turn/take-in-turn.poc.test.ts b/specs/issues/FIX-2159/poc/take-in-turn/take-in-turn.poc.test.ts new file mode 100644 index 0000000000..377d6428c3 --- /dev/null +++ b/specs/issues/FIX-2159/poc/take-in-turn/take-in-turn.poc.test.ts @@ -0,0 +1,271 @@ +/** + * POC for FIX-2159 — retained design evidence, not production code. + * + * The question: can a running conversation request take a settled notice + * itself, through the take record `onTaskSettled` already writes (FIX-2123), + * so the queued `onTaskSettled` copy never handles it twice and never loses it? + * That holds only if, on the real engine with a durable host: + * + * 1. a request that started BEFORE the ending sees the owed marker with a + * committed read (its own snapshot of the board does not show it); + * 2. the request takes it (`takeNotice({ by: its own id })`), handles it, + * clears it, and the queued copy that runs after finds nothing owed: + * heard once, in the turn; + * 3. when the queued copy took it first, the turn's take is refused and the + * turn shows nothing: heard once, by the queued copy; + * 4. when the turn took it and failed before acknowledging it (it says the + * line only after the acknowledgement, the queued handling's order), the + * queued copy takes it over once the turn has ended: heard once; and a + * turn that failed after the acknowledgement drops it: at most once, as + * today; + * 5. a turn that only READS the finished row (all a lab can do on public + * entries) leaves the notice owed, and the queued copy says it again: + * heard twice. + * + * The "turn" is a handler held open on a gate, standing in for a generator + * between two model calls; the take is what its context entry would run. + * Run with `bash specs/issues/FIX-2159/poc/take-in-turn/run.sh`. + */ +import { DEFAULT_ORG_ID, defineFlow, handler } from "@flow-state-dev/core"; +import type { BlockContext } from "@flow-state-dev/core/types"; +import { createFlowState, inMemoryStores, runAction } from "@flow-state-dev/engine"; +import { describe, expect, it } from "vitest"; +import { z } from "zod"; +import { taskSettledEntry, type TaskSettledInput } from "../../src"; +import { + clearNotice, + defineTaskCollection, + getOrCreateTaskCollection, + isNoticeOwed, + readCommittedTask, + resolveResourceCollection, + type TaskCollectionRef +} from "../../src/tasks"; + +const BOARD = "conv-board"; +const USER = "u_filer"; +const SESSION = "s_main"; +const NOTICE = { boardId: BOARD, taskId: "t1", attempt: 1, ending: "completed" as const, output: "the first result" }; + +async function boardOf(ctx: BlockContext): Promise { + const collection = resolveResourceCollection(ctx, BOARD)!; + return getOrCreateTaskCollection({ ctx, backing: "resource", collectionId: BOARD, collection }); +} + +interface TurnLog { + sawInSnapshot?: boolean; + sawCommitted?: boolean; + take?: string; +} + +function host(options: { turnFailsAt?: "before-ack" | "after-ack"; entryGate?: Promise; readOnly?: boolean } = {}) { + const heardInTurn: string[] = []; + const heardByEntry: TaskSettledInput[] = []; + const log: TurnLog = {}; + let release!: () => void; + const turnGate = new Promise((resolve) => (release = resolve)); + let turnStarted!: () => void; + const started = new Promise((resolve) => (turnStarted = resolve)); + + const seed = handler({ + name: "seed", + inputSchema: z.object({}), + outputSchema: z.any(), + execute: async (_input, ctx) => { + await (await boardOf(ctx)).addTask({ id: "t1", goal: "Find the fact" }); + return {}; + } + }); + // The delegate's ending, written by another request: the row owes this session its notice. + const end = handler({ + name: "end", + inputSchema: z.object({}), + outputSchema: z.any(), + execute: async (_input, ctx) => { + await (await boardOf(ctx)).patchMetadata("t1", { "noticeOwed:1:completed": { attempt: 1, ending: "completed", due: Date.now() } }); + return {}; + } + }); + const read = handler({ + name: "read", + inputSchema: z.object({}), + outputSchema: z.any(), + execute: async (_input, ctx) => (await boardOf(ctx)).get("t1")?.metadata ?? null + }); + // The person's turn: it reads the board at its start, then waits (a model call), then takes before its next call. + const turn = handler({ + name: "turn", + inputSchema: z.object({}), + outputSchema: z.any(), + execute: async (_input, rawCtx) => { + const ctx = rawCtx as unknown as BlockContext; + const ref = await boardOf(ctx); + ref.get("t1"); + turnStarted(); + await turnGate; + // Before the next model call: what the context entry would do. + log.sawInSnapshot = isNoticeOwed(ref.get("t1")!, NOTICE); + const stored = await readCommittedTask(ref, "t1"); + log.sawCommitted = stored !== undefined && isNoticeOwed(stored, NOTICE); + if (!log.sawCommitted) return {}; + // A lab on public entries alone can only read the finished row, not take it. + if (options.readOnly === true) { + heardInTurn.push(String(NOTICE.output)); + return {}; + } + const took = await ref.takeNotice!("t1", NOTICE, { by: ctx.request.identity.id }); + log.take = took.outcome; + if (took.outcome !== "recorded") return {}; + // The queued handling's order: acknowledge, then say the line (D1). + if (options.turnFailsAt === "before-ack") throw new Error("the turn failed after its take, before its acknowledgement"); + await ref.patchMetadata("t1", clearNotice(NOTICE)); + if (options.turnFailsAt === "after-ack") throw new Error("the turn failed after its acknowledgement, before its line"); + heardInTurn.push(String(NOTICE.output)); + return {}; + } + }); + + const flow = defineFlow({ + kind: "take-host", + resources: { [BOARD]: defineTaskCollection({ id: BOARD, scope: "session", delivery: {} }) }, + actions: { seed: { block: seed }, end: { block: end }, read: { block: read }, respond: { block: turn } }, + internal: { + actions: { + onTaskSettled: taskSettledEntry({ + block: handler({ + name: "record-heard", + inputSchema: z.any(), + outputSchema: z.any(), + execute: async (notice: TaskSettledInput) => { + heardByEntry.push(notice); + await options.entryGate; + return {}; + } + }) + }) + } + } + })({ id: "take-host" }); + const state = createFlowState({ flows: { "take-host": flow }, stores: { default: { primary: inMemoryStores() } }, durable: true }); + const act = async (actionName: string, input: unknown = {}, internal = false) => { + await state.getRouter(); + const runtime = await state.getRuntime(); + const result = await runAction({ + orgId: DEFAULT_ORG_ID, + flow, + actionName, + input, + userId: USER, + sessionId: SESSION, + stores: runtime.stores, + runtimeConfig: runtime.runtimeConfig, + ...(internal ? { source: "internal" } : {}) + } as never); + if ((result as { error?: unknown }).error !== undefined) throw new Error(`${actionName}: ${JSON.stringify((result as { error?: unknown }).error)}`); + return (result as { output?: unknown }).output; + }; + return { act, heardInTurn, heardByEntry, log, release, started, dispose: () => state.dispose() }; +} + +describe("a running conversation request takes a settled notice (FIX-2159 POC)", () => { + it("1+2 · sees the ending by a committed read, takes it, and the queued copy finds nothing owed", async () => { + const h = host(); + try { + await h.act("seed"); + const turn = h.act("respond"); + await h.started; + await h.act("end"); + h.release(); + await turn; + expect(h.log).toEqual({ sawInSnapshot: false, sawCommitted: true, take: "recorded" }); + // The queued onTaskSettled runs after the turn ends. + expect(await h.act("onTaskSettled", NOTICE, true)).toEqual({ owed: false }); + expect(h.heardInTurn).toEqual(["the first result"]); + expect(h.heardByEntry).toEqual([]); + const metadata = (await h.act("read")) as Record; + expect(metadata["noticeOwed:1:completed"] ?? null).toBeNull(); + // The take record stays as the durable "taken in request R" mark. + expect(metadata["noticeTaken:1:completed"]?.by).toEqual(expect.any(String)); + } finally { + await h.dispose(); + } + }); + + it("3 · when the queued copy took it first, the turn's take is refused: heard once, by the copy", async () => { + let open!: () => void; + const entryGate = new Promise((resolve) => (open = resolve)); + const h = host({ entryGate }); + try { + await h.act("seed"); + const turn = h.act("respond"); + await h.started; + await h.act("end"); + const copy = h.act("onTaskSettled", NOTICE, true); + for (let i = 0; i < 300 && h.heardByEntry.length === 0; i += 1) await new Promise((r) => setTimeout(r, 10)); + h.release(); + await turn; + expect(h.log.take).toBe("unchanged"); + open(); + await copy; + expect(h.heardInTurn).toEqual([]); + expect(h.heardByEntry).toHaveLength(1); + } finally { + open(); + await h.dispose(); + } + }); + + it("4 · a turn that took it and failed before its acknowledgement: the copy takes it over, heard once", async () => { + const h = host({ turnFailsAt: "before-ack" }); + try { + await h.act("seed"); + const turn = h.act("respond").catch((error: Error) => error); + await h.started; + await h.act("end"); + h.release(); + expect(await turn).toBeInstanceOf(Error); + expect(h.log.take).toBe("recorded"); + await h.act("onTaskSettled", NOTICE, true); + expect(h.heardInTurn).toEqual([]); + expect(h.heardByEntry).toHaveLength(1); + const metadata = (await h.act("read")) as Record; + expect(metadata["noticeOwed:1:completed"] ?? null).toBeNull(); + } finally { + await h.dispose(); + } + }); + + it("4b · a turn that failed after its acknowledgement, before its line: dropped, never twice (at most once)", async () => { + const h = host({ turnFailsAt: "after-ack" }); + try { + await h.act("seed"); + const turn = h.act("respond").catch((error: Error) => error); + await h.started; + await h.act("end"); + h.release(); + expect(await turn).toBeInstanceOf(Error); + expect(await h.act("onTaskSettled", NOTICE, true)).toEqual({ owed: false }); + expect(h.heardInTurn).toEqual([]); + expect(h.heardByEntry).toEqual([]); + } finally { + await h.dispose(); + } + }); + + it("5 · a turn that only reads the finished row: the queued copy says it again, heard twice", async () => { + const h = host({ readOnly: true }); + try { + await h.act("seed"); + const turn = h.act("respond"); + await h.started; + await h.act("end"); + h.release(); + await turn; + await h.act("onTaskSettled", NOTICE, true); + expect(h.heardInTurn).toEqual(["the first result"]); + expect(h.heardByEntry).toHaveLength(1); + } finally { + await h.dispose(); + } + }); +});