Repository navigation
spec(FIX-1629): DevTool Tasks tab: inspect a task in an accordion row, and manage its state with the framework's standard tools #2346
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| # FIX-1629 · Business rules | ||
|
|
||
| [Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) | ||
|
|
||
| When → then → proved by. CI = unit test in the owning package. VG = the goal check. | ||
|
|
||
| ## Reading a row | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-1 | A board has tasks | One row per task, collapsed. Status comes first; goal (or title) and reason share the rest, one line each, clipped with the full text on hover | CI | | ||
| | BR-2 | The window is 1280 wide, panels at default | Status and ≥40px of the reason are in view on every row; the pane does not scroll sideways | VG read | | ||
| | BR-3 | A row is clicked, or Enter/Space on it | It expands in place, below itself, inside the pane. No overlay, nothing floats | CI · VG read | | ||
| | BR-4 | A row is expanded | Every field the task carries is shown: id, full goal wrapped, title, status, attempts / max, assignee, priority, labels, deps, reason, error, input, output, metadata, revision, created / updated, lease holder, dispatch run, latest change (kind, was, ×N). Absent fields are omitted, not faked | CI · VG read | | ||
| | BR-5 | A row is expanded | The raw JSON of the task is available folded inside the row, complete and unchanged | CI | | ||
| | BR-6 | A task updates while its row is open | The row stays open and shows the new values | CI | | ||
| | BR-7 | A value is huge, markup, or one unbroken token | It wraps or scrolls inside the row; the pane never widens | CI | | ||
| | BR-8 | Reason, per FIX-1481 BR-4 / BR-8 | Shown whenever `feedback` is present, whatever the status, verbatim; the slot is absent on a board where no task carries it | CI (existing tests kept) | | ||
|
|
||
| ## Changing a task from its row | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-9 | The viewed flow has public actions whose input requires a string `taskId` | The expanded row lists them. Of the eight task tools that is six: `addTask` and `listTasks` take no `taskId` | CI · VG answer | | ||
| | BR-10 | Such an action's name ends with `_<suffix>` of any board the tab lists for the flow | It is listed only on that board's rows. One that matches no listed board's suffix is listed on every board | CI | | ||
| | BR-11 | No action qualifies | The row says so in one line and links the docs on exposing task actions | CI | | ||
| | BR-12 | An action is picked | Its form opens in the row with `taskId` filled and locked; other fields as the action bar draws them | CI | | ||
| | BR-13 | The action is submitted | It runs through the panel's existing action dispatch against the viewed flow and session; nothing else is called | CI · VG answer | | ||
| | BR-14 | It succeeds | The row shows the new state from the change item, without a reload | VG answer · VG tool | | ||
| | BR-15 | A tool returns `{ ok: false, error }`, or the request fails | The row shows the refusal or error, in words, read from the root `block_trace` output of the request the row dispatched (matched by that request id), or from the failed request. With no trace for it (observability off), the row says the outcome isn't visible. Never shown as success | CI · VG refuse | | ||
| | BR-16 | Two submits race on one task | Each gets its own verb's answer; the second may be refused. No client-side lock | CI (tool level, existing) | | ||
|
|
||
| ## The ready-made actions | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-17 | A flow spreads `taskToolActions(board)` into `actions` | It gains the eight task tools as actions, named `<tool>_<board suffix>`, each running the same guarded verb a model's tool does. A request- or sequencer-backed board is refused when `taskToolActions` is called, naming its backing: its tasks don't outlive the request, so a later action could never find them | CI | | ||
| | BR-18 | One of them targets a settled task, or an illegal move | Refused by the verb, returned as a value | CI | | ||
| | BR-25 | `completeTask`, `failTask`, `blockTask` or `cancelTask` runs as an action on a row a live worker holds | It runs with no claim, as a coordinator's call does today, and lands if the transition is legal. The worker's own later result is refused `lost-claim` and dropped | CI | | ||
| | BR-19 | A channel declares `boardActions: true` | Each of its boards gets the eight actions. Without it, the channel's public actions are exactly today's | CI | | ||
| | BR-26 | A channel board's action is invoked while addressing any session but that channel's | Refused by name before the ledger is read, the same check `fileTask` and `readBoard` make. Channels share one flow, so the action map alone does not fence them | CI | | ||
| | BR-20 | `boardActions` is anything but `true`, `false` or absent | Refused at bind, by name, like any other bad value in the closed key list (which grows from six keys to seven) | CI | | ||
| | BR-21 | The reference app's `support.help` | Per the open fork | CI · hand check on Jake's screen | | ||
|
|
||
| ## What none of this may do | ||
|
|
||
| | # | Rule | Proved by | | ||
| |---|---|---| | ||
| | BR-22 | No engine or core route, type or verb is added | Diff review · CI (route table test unchanged) | | ||
| | BR-23 | No action claims or drains a board (FIX-1457 ER-1) | CI | | ||
| | BR-24 | Nothing Workforce-specific (seats, rosters, channels) enters orchestration, engine or core | Diff review | | ||
|
|
||
| ## Failure taxonomy | ||
|
|
||
| A refused verb is a value on the row. A thrown error or HTTP failure is shown on the row and the | ||
| form stays filled for a retry. Nothing is fatal to the panel; a render error in one row must not | ||
| blank the tab. | ||
|
|
||
| ## Acceptance criteria this issue owns | ||
|
|
||
| - The goal check passes, and both controls fail at their named legs. | ||
| - FIX-1481's `the-checklist-rows` row-4 leg and FIX-1497's VB leg pass against the new row. | ||
| - FIX-1523 closes. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,109 @@ | ||
| # FIX-1629 · Decisions | ||
|
|
||
| [Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) | ||
|
|
||
| One decision to sign, one fork to call. The rest was decided and is listed so nobody re-derives it. | ||
|
|
||
| ## The tree | ||
|
|
||
| ```mermaid | ||
| flowchart TD | ||
| I["FIX-1629"] --> D1["D1 · change a task only through flow actions<br/>ready-made set is the eight task tools"] | ||
| D1 -.->|"rejected"| X1["edit the record as JSON<br/>needs an engine write that skips the task guards"] | ||
| D1 -.->|"rejected"| X2["a debug route for task verbs<br/>puts task-board knowledge in the engine"] | ||
| I --> O1["Open · support.help opts in now, or waits for FIX-1591"] | ||
| I --> E1["accordion rows · status and reason lead"] | ||
| E1 -.->|"absorbs"| X3["FIX-1523 · reason off screen at 1280"] | ||
| ``` | ||
|
|
||
| Solid edges are what you're signing. Dashed edges lost or were absorbed. | ||
|
|
||
| <a name="d1"></a> | ||
| ## D1 · A task changes only through the flow's own actions. The ready-made set is the eight task tools. No record editor, no DevTool-only route | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | An editable JSON view of the task record in the Tasks tab or the Resources panel, or a debug-gated engine route that runs task verbs for the DevTool | | ||
| | **Because** | Every way a task moves already exists as a guarded verb (terminal rows refuse, a lost claim refuses, `parked → pending` is fenced). The eight task tools (`addTask`, `assignTask`, `completeTask`, `failTask`, `blockTask`, `cancelTask`, `updateTask`, `listTasks`) are the framework's own surface over those verbs, already given to models. Exposing them as flow actions reuses the action path the DevTool already calls. A record editor needs a state-write route that no client has today and would bypass every guard. A debug verb route puts task-board knowledge in the engine (L1) and is a DevTool-only mutation path. Tenets 2 and 5: refine what exists, one convergence point for writes | | ||
| | **Locks in** | What you can do to a task from the DevTool is exactly what the flow exposes. A flow that exposes nothing shows nothing to press, with a line saying how to expose the set. Fields no verb writes (the goal, attempts, revision) can't be changed from the DevTool. Adding an editor later means a new write route and a decision about which guards it skips | | ||
|
|
||
|  | ||
|
|
||
| It comes down to the task guards: an editor writes a row the verbs would have refused. | ||
|
|
||
| <a name="open"></a> | ||
| ## Open · Should the reference app's `support.help` channel turn its escalation actions on now? | ||
|
|
||
| **Plain terms.** Workforce channels gain an opt-in that exposes their boards' eight task | ||
| tools as actions, off by default. Turning it on for `support.help` makes the screen you sent | ||
| manageable. It also means anyone who can reach that channel can cancel, complete or reassign an | ||
| escalation, including one a seat is working on right now; that seat's own result is then refused | ||
| and dropped. FIX-1591 ("who attends escalations") is parked waiting on you. | ||
|
|
||
| **Trade-off.** On now: your screenshot works end to end, and the demo shows the feature on its | ||
| headline board. Off until FIX-1591: nothing pre-empts that hold, but the reference app's only | ||
| board stays read-only in the tab; the feature is proved only on the lab hire. | ||
|
|
||
| **Recommendation: on now.** It is a developer's tool on a demo board with no production users, | ||
| and the change is one line to reverse. It does not decide FIX-1591's question: nothing drains | ||
| `escalations` and no person-side screen is built. | ||
|
|
||
| **What would change my mind:** if you mean `support.help` to demo "nobody works this board" as | ||
| the point of the unattended-board warning, off is right. | ||
|
|
||
| **If wrong:** on, and you wanted the hold: revert one line, nothing else moves. Off, and you | ||
| wanted it: the tab stays read-only on the board you use most until a follow-up. | ||
|
|
||
|  | ||
|
|
||
| It comes down to your screenshot: off, the board you asked about stays read-only. | ||
|
|
||
| ## Decided, not asked | ||
|
|
||
| - **FIX-1523 is absorbed and closes when this ships.** The collapsed row leads with status, then | ||
| the goal and the reason sharing the remaining width; nothing scrolls sideways at 1280. | ||
| - **Which actions a row offers:** every public action on the viewed flow whose input has a | ||
| required string `taskId`. One whose name ends with the suffix of any board the tab lists | ||
| (`_support_help_escalations`) shows only on that board's rows; the rest show on every board. | ||
| Generic, so an app's own `answer` action shows too. Of the eight task tools, `addTask` and | ||
| `listTasks` take no `taskId`, so a row offers six. | ||
| - **`taskId` is filled in and locked;** other fields use the action bar's existing form. | ||
| - **The row reads the result from the request's root trace.** The dispatch returns only a | ||
| request id and a refusal writes nothing, so the tool's `{ ok, error }` lives only in the root | ||
| `block_trace` of the request the row sent. With traces off, the row says the outcome isn't | ||
| visible. A refusal never shows as success. | ||
| - **An action's settlement overrides a worker's claim.** An action has no claim ticket, so it | ||
| settles as a coordinator does today: legal transitions only, no ownership check. The holding | ||
| seat's later result is refused (`lost-claim`). Clearing a stuck row is the debugging job, and | ||
| refusing would need a new substrate guard. It is why channel exposure stays opt-in. | ||
| - **Durable boards only.** A request- or sequencer-backed ledger is gone before the row's action | ||
| runs, so `taskToolActions` refuses those backings by name, as `unparkAndDrain` does. | ||
| - **A channel's actions work only in its own session.** Channels share one flow, so each action | ||
| runs the session check `fileTask` and `readBoard` already make. | ||
| - **One PR, not two.** You asked for both halves together; Cursor's review agreed. | ||
| - **The row reads the item stream, as today.** It updates from the change item the action's | ||
| own request emits. Changes made by another session stay FIX-1506's. | ||
| - **One orchestration export, `taskToolActions`,** so a non-Workforce board gets the set without | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| reaching for an internal resolver. The suffix rule moves from Workforce into orchestration so | ||
| names have one home. | ||
| - **Several rows can be open at once;** a live update never collapses an open row. | ||
| - **The Resources panel is untouched.** It stays the ledger view. | ||
|
|
||
| ## Considered and dropped | ||
|
|
||
| | Option | Why it lost | | ||
| |---|---| | ||
| | Accordion only, actions later | Half of what was asked | | ||
| | Match actions by a fixed name list | Misses an app's own `answer`; `taskId` in the input is the honest signal | | ||
| | Always expose channel board actions | Opens every production channel's rows to any caller | | ||
| | Offer `unpark` as a ninth tool | Not in the eight; answering a parked row stays the app's action (FIX-1457 ER-1) | | ||
| | A POC of the row | The UI is an extension of an existing table and form; the goal check renders it on a live hire | | ||
|
|
||
| ## How it got here | ||
|
|
||
| - **Draft** — Framed as read-in-place plus change-through-actions; chose the eight task tools as | ||
| flow actions over a record editor, a Workforce opt-in with one open fork on `support.help`, | ||
| one PR. | ||
| - **Review, round 2** — The refusal path moved to the request's root trace, because the dispatch | ||
| response and the change items carry no refused result. Added the claim-override, durable-board | ||
| and channel-session rules the second look and Codex found missing. D1 and the fork stand. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,113 @@ | ||
| # FIX-1629 · Documentation draft | ||
|
|
||
| [Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · **Docs** · [Evolution](EVOLUTION.md) | ||
|
|
||
| Drafted by the spec author; this session could not dispatch `docs-writer`. The implementer runs | ||
| `docs-writer` then `docs-editor` over these drafts against what shipped, before publishing. | ||
| Quoted text is the proposed prose. | ||
|
|
||
| ## UPDATE · `apps/docs/docs/devtool/overview.md` · "Task boards" (replace the section body) | ||
|
|
||
| > The Tasks tab lists the task boards the open session emitted. A task board is the queue a flow | ||
| > files work into for workers to claim. Each task is one row: its status first, then its goal, | ||
| > then a short note about it when there is one. | ||
| > | ||
| > Click a row, or focus it and press Enter, to open it in place. The open row shows everything | ||
| > the task carries: the full goal, attempts, assignee, priority, labels, the note and any error, | ||
| > input and output, metadata, revision and timestamps, and the dispatch run working it. The raw | ||
| > record is folded at the bottom if you want the JSON. Rows stay open while the task changes | ||
| > underneath them. | ||
| > | ||
| > The note is the task's `feedback` field. Parking a task for review records why it is | ||
| > waiting, or clears the note when you give no reason. A failure with retries left records the | ||
| > error and sends the row back to `pending`. Resuming a parked task writes the answer you hand | ||
| > it. The row shows whichever wrote last, and the note slot appears only on boards where some | ||
| > task carries one. A note is not an error: a failure with no retries left writes `error`. | ||
| > | ||
| > ### Changing a task from its row | ||
| > | ||
| > An open row lists the flow's actions that take a `taskId`. Pick one and its form opens in the | ||
| > row with the task's id filled in. Submit it and the DevTool runs the action exactly as the | ||
| > action bar would, in the session you are looking at. The row updates when the task changes. | ||
| > | ||
| > If the task can't move that way, say you cancel a task that already finished, the action | ||
| > refuses and the row shows why. Nothing is written. The row reads that answer from the | ||
| > request's trace, so with trace observability off it tells you the outcome isn't visible. | ||
| > | ||
| > The DevTool changes tasks only through your flow's actions. There is no way to edit a | ||
| > task's record directly, which keeps every change going through the same checks a worker's | ||
| > would. If a row says the flow has no task actions, see | ||
| > [exposing task actions](/docs/orchestration/task-board#changing-tasks-from-outside-a-run). | ||
|
|
||
| ## UPDATE · `apps/docs/docs/orchestration/task-board.md` · new section after "Commanding the board with its capability" | ||
|
|
||
| > ## Changing tasks from outside a run | ||
| > | ||
| > Workers change tasks while a board drains. Sometimes a person needs to as well: cancel a task | ||
| > nobody needs, bump a priority, mark one failed. `taskToolActions` gives your flow the same | ||
| > eight task tools a model can hold, as actions any caller of the flow can run: | ||
| > | ||
| > ```ts | ||
| > import { taskBoard, taskToolActions } from "@flow-state-dev/orchestration/task-board"; | ||
| > | ||
| > const board = taskBoard({ name: "todos", collection: todos, workers }); | ||
| > | ||
| > defineFlow({ | ||
| > kind: "ops", | ||
| > resources: { [todos.id]: todos }, | ||
| > actions: { | ||
| > drain: { block: board.drain }, | ||
| > ...taskToolActions(board), | ||
| > }, | ||
| > }); | ||
| > ``` | ||
| > | ||
| > The actions are named for the board: `addTask_todos`, `assignTask_todos`, `completeTask_todos`, | ||
| > `failTask_todos`, `blockTask_todos`, `cancelTask_todos`, `updateTask_todos` and | ||
| > `listTasks_todos`. Each runs the same checked transition a worker's would, so a move the task | ||
| > can't make comes back as `{ ok: false, error }` rather than a write. None of them claims or | ||
| > drains the board. Settling a task a worker is still running is allowed, as it is for a | ||
| > coordinator: your write lands and the worker's own result is refused when it arrives. | ||
| > | ||
| > The board needs a collection that outlives a request (`defineTaskCollection`). A board on | ||
| > the default request-scoped ledger is refused, because a later action could never find its | ||
| > tasks. | ||
| > | ||
| > They are public actions. Anyone who can call your flow can call them, so add them only to a | ||
| > flow whose callers you trust with the board. The DevTool's Tasks tab offers them on each row. | ||
|
|
||
| ## UPDATE · `apps/docs/docs/workforce/channels.md` · "Working the rows", after the paragraph on `channelBoardTaskTools` | ||
|
|
||
| > A channel can offer the same eight tools to callers, as actions. Add `boardActions: true` to | ||
| > its `CHANNEL.md`: | ||
| > | ||
| > ```md | ||
| > --- | ||
| > description: Ask the support team anything. | ||
| > members: [support.devices, support.accounts] | ||
| > boards: [escalations] | ||
| > boardActions: true | ||
| > --- | ||
| > ``` | ||
| > | ||
| > Each board gains `cancelTask_support_help_escalations` and its seven siblings beside | ||
| > `fileTask` and `readBoard`. It is off by default because anyone who can reach the channel can | ||
| > then settle or reassign its rows, including one a seat is working on, and `author` checks on | ||
| > filing don't apply to these. Each action works only in its own channel's session. Turn it on | ||
| > for boards people are meant to work from outside, and for development. | ||
|
|
||
| And in "What the file is checked for": *"the closed list of six keys"* → *"seven"*. | ||
|
|
||
| ## UPDATE · `packages/orchestration/README.md` · task-board exports | ||
|
|
||
| > - `taskToolActions(board)` — the eight task tools over `board`, as a flow `actions` map named | ||
| > `<tool>_<board>`. Public actions; see the docs before exposing them. | ||
|
|
||
| ## UPDATE · `packages/workforce/README.md` · channels | ||
|
|
||
| > - `CHANNEL.md` `boardActions: true` — expose each board's task tools as channel actions. Off by default. | ||
|
|
||
| ## Changesets | ||
|
|
||
| `@flow-state-dev/orchestration` (minor: new export), `@flow-state-dev/workforce` (minor: new key), | ||
| `@flow-state-dev/devtool` (patch: Tasks tab). |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.