Repository navigation
spec(issue): shared task actions on the Inbox client (FIX-2381) #4373
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
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,82 @@ | ||
| # FIX-2381 · Decisions | ||
|
|
||
| [Spec](SPEC.md) · **Decisions** | ||
|
|
||
| The epic settled the package and the entry: orchestration's `./inbox`, beside | ||
| `createInboxClient`, and not a second constructor. What's left is the shape on that client, what | ||
| happens to the issue's `answer(id, answers)`, and what a re-file copies. | ||
|
|
||
| <a name="d1"></a> | ||
| ## D1 · `inbox.board(at)` returns the board's actions | ||
|
|
||
| | | `inbox.board(at).cancel(id)` (chosen) | `inbox.cancel(at, id)` on every call | `createTaskActions(client, board)` (the issue's) | | ||
| |---|---|---|---| | ||
| | A second constructor | no | no | yes, which the epic's review folded out | | ||
| | The board named once per screen | yes | on every call | yes | | ||
| | Shares the answer path's send routine | yes | yes | only by importing it across | | ||
|
|
||
| - **Because:** a task screen works one board. Binding it once reads like the issue's | ||
| `createTaskActions(client, board)` without a second thing to construct. | ||
| - **`at` names the session and flow, not only the board.** The board's actions run on the session | ||
| that holds it, as the signed-in user, which is how the answer path already routes a row hold. | ||
| - **Locks in:** a method on `InboxClient`. Renaming it later is a one-file change for each app. | ||
|
|
||
| <a name="d2"></a> | ||
| ## D2 · No second answer call | ||
|
|
||
| The issue lists `answer(id, answers)`. `answerOne(hold, answer)` already answers a row's question | ||
| or confirm through the same `updateTask`, typed by what the hold asks. A second call would be a | ||
| second answer path, which the epic refuses for FIX-2389's approvals for the same reason. A screen | ||
| that has a task and wants to answer its question reads the hold off the Inbox item, as both apps | ||
| already do. | ||
|
|
||
| <a name="d3"></a> | ||
| ## D3 · A re-file copies what a browser's row carries | ||
|
|
||
| `refile(row, overrides)` sends `goal`, `title`, `context`, `assignee`, `labels` and `priority` | ||
| from the row, overrides winning. It takes a `RefileRow` of exactly those fields, not an | ||
| `InboxRow`, which carries fewer. It doesn't copy `input`, `metadata` or `deps`: a browser's row | ||
| doesn't carry the first two (BP-015 keeps them on the server), and old `deps` may name finished | ||
| rows. An override can set any of them. | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
|
|
||
| - **`context` joins the conversation board's browser fields.** It is the rest of the brief the | ||
| user or a worker wrote beside `goal`, which is exposed already. Without it, a browser's re-file | ||
| drops part of the brief with no sign. The other way, a server read just for re-file, adds an | ||
| action to fetch text that is no more private than the goal. | ||
|
|
||
| - **Re-file vs retry:** retry (FIX-2383) keeps the id, the history and the spend, and is the | ||
| default after a failure. Re-file is for a task that should run again *changed*, which a started | ||
| task's locked fields otherwise forbid ("cancel it and file it again", in the board's own words). | ||
| - **Debt:** the new row doesn't record what it was re-filed from. A link field is a board change, | ||
| not a client one; file it if an app needs to show the lineage. | ||
|
|
||
| ## Decided, not asked | ||
|
|
||
| - **E1 · Each action resolves on the board's `ok: true` and rejects with its error words** on | ||
| `ok: false`, a failed request, or a 4xx, as the answer path does today. | ||
| - **E2 · `cancel` resolves to the ids it took along**, the `cancelled` list the board returns. | ||
| - **E3 · `taskToolSuffix` moves to a leaf module** and stays exported from where it is now, so | ||
| `./inbox` stays browser-safe (its file header promises that) and no import breaks. | ||
| - **E4 · Two PRs.** The package slice on FIX-2383's branch now; Shift Manager's `reads.ts` after | ||
| FIX-2379's slice merges, per the epic's build order (`2379 → 2381 → 2380`). | ||
| - **E5 · The Claude Code-style lab's copy goes in FIX-2382's lab stack**, which owns `adapter.ts` | ||
| in that wave. This issue's PRs don't touch the lab. | ||
| - **E7 · The send routine pages the session's requests** (20 × 100, as Shift Manager's | ||
| `runAction`), and a finished action whose answer isn't found rejects. | ||
| - **E6 · No changeset unless the package PR adds a public export**, which it does: one `minor` | ||
| fragment for `@flow-state-dev/orchestration`. | ||
|
|
||
| ## How it got here | ||
|
|
||
| - Drafted 2026-10-31 from the issue, the epic's decisions and review record, and the code on | ||
| `main` at `675f61441`. | ||
|
|
||
| ## Notes from review | ||
|
|
||
| - Codex (e813f22): one P2, folded. A browser's row has no `context`, so re-file would drop it. | ||
| The conversation board now exposes `context` (D3). | ||
| - Cursor (e813f22): direction approved. Folded: `retry` lands with FIX-2383's verb; `at.board` is | ||
| the collection id, not a row's ref; `taskActionName` is for readers, and apps call `board(at)`; | ||
| the routine pages requests like `runAction`; `RefileRow` names the copied fields; | ||
| `LabReader.taskActions` is one getter returning `inbox.board(...)`. Its performance note (one | ||
| send-wait-list per action) is inherited from the answer path and left as it is. | ||
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,124 @@ | ||
| # FIX-2381 · Shared task actions: cancel, steer, release, retry, re-file | ||
|
|
||
| **Spec** · [Decisions](DECISIONS.md) | ||
|
|
||
| Child of epic [FIX-2369](../../epics/FIX-2369/SPEC.md) (merged #4358). The epic decided where | ||
| this lives: orchestration's `./inbox` entry, next to `createInboxClient`, and not as a new client | ||
| constructor ([epic Decided](../../epics/FIX-2369/DECISIONS.md#coordination-seams), review finding | ||
| "Task actions as a new constructor", folded). | ||
|
|
||
| ## Who feels it, before and after | ||
|
|
||
| | Someone who… | Today | After | | ||
| |---|---|---| | ||
| | **builds a workforce app** with task cards | Hardcodes `"updateTask_tasks"`, rebuilds each payload (`{ id, status: "cancelled" }`, `{ id, message }`), and writes their own send, wait and read-the-refusal loop | Calls `inbox.board(at).cancel(id)`, `.steer(id, words)`, `.release(id)`, `.retry(id)`, `.refile(row, overrides)`. A refusal rejects with the board's own words | | ||
| | **uses Shift Manager** | Only Interrupt works on a task. A held row shows its *held* tag with no way to release it | Its reader exposes the same actions. The buttons themselves are FIX-2382's | | ||
| | **uses the Claude Code-style lab** | A steer goes through the adapter's own `run` loop and its own copy of the action name | Unchanged by this issue's PRs. FIX-2382's lab stack swaps the copy for the shared call when it adds the buttons | | ||
| | **uses the Teammates lab** | Has no task actions, so no copy yet | Gets them through FIX-2382 and FIX-2380, with nothing to copy | | ||
| | **answers a task's question** | `inbox.answerOne(hold, answer)` | **Unchanged.** Answering stays the Inbox's one answer call ([D2](DECISIONS.md#d2)) | | ||
|
|
||
| ## The goal, and how we'll know it's met | ||
|
|
||
| **An app cancels, steers, releases, retries and re-files a task on a conversation's board with | ||
| one shared call each, imported from `@flow-state-dev/orchestration/inbox`, and no app names the | ||
| board's action or builds its payload.** | ||
|
|
||
| - **Smaller, and rejected:** export only the action-name constant. Every app still rebuilds the | ||
| payloads and the send-wait-read loop, which is where the copies differ today (Shift Manager's | ||
| answer path maps 4xx and a timeout; the lab's `run` does neither). | ||
| - **Bigger, and not this issue's:** the buttons on task cards (FIX-2382), the retry verb itself | ||
| (FIX-2383, this issue's base), and hand-off or reassign (no board verb exists). | ||
| - **Not done if:** an app outside orchestration still spells `updateTask_tasks` or builds one of | ||
| these payloads after FIX-2382 lands (the closure sweep, FIX-2425); or a refusal resolves instead | ||
| of rejecting. | ||
|
|
||
| ```mermaid | ||
| flowchart LR | ||
| App["app: task card, header"] -->|"inbox.board(at).cancel(id)"| B["board actions<br/>(orchestration ./inbox)"] | ||
| App -->|"inbox.answerOne(hold, answer)"| A["answer routing<br/>(unchanged)"] | ||
| B --> S["send, wait, read the output<br/>(one routine)"] | ||
| A --> S | ||
| S -->|"updateTask_‹board›<br/>createTask_‹board›<br/>FIX-2383's retry"| Board["the board's own actions,<br/>on the session that holds it,<br/>as the signed-in user"] | ||
| ``` | ||
|
|
||
| **How we verify.** | ||
|
|
||
| - **Goal check, against a real conversation board** (`packages/workforce/test`, on the | ||
| conversation-board harness that already serves a flow to a real `Client`): file a held task and | ||
| release it, then see it pending; steer an open task and see the words in its `steers`; cancel it | ||
| and see `cancelled`, with the dependents the board names returned; re-file the cancelled row with | ||
| one field overridden and see a new pending row carrying the copied fields and the override; | ||
| retry an errored task and see the same id back in `pending` (FIX-2383's verb). Each step reads | ||
| the row back through the board, never the helper's own return alone. | ||
| - **Refusal leg:** steer a finished task and cancel it again. Both reject with the board's | ||
| `task_finished` words, and nothing is written. | ||
| - **Control that must fail:** point the helper at the wrong board id (`"plan"` for `"tasks"`). | ||
| Every leg must go red, since the action doesn't exist on that flow. A second control drops the | ||
| `ok: false` read from the shared routine: the refusal leg must go red. | ||
| - **Unit:** the existing `test/inbox.test.ts` answer tests keep passing unchanged after the send | ||
| routine is shared, which shows the answer path didn't move. | ||
|
|
||
| ## What changes | ||
|
|
||
| - **`@flow-state-dev/orchestration/inbox`** gains, on `InboxClient`, `board(at)`, which returns | ||
| the board's actions bound to `at = { flowId, sessionId, board }` ([D1](DECISIONS.md#d1)). | ||
| `board` is the **collection id** (Workforce's `"tasks"`), not a row's board ref | ||
| (`<sessionId>.tasks`); a reader holding a ref gets the id with its own `collectionOfBoard`: | ||
| - `cancel(id)` → `updateTask { id, status: "cancelled" }`, resolving to the ids it took along. | ||
| - `steer(id, message)` → `updateTask { id, message }`. | ||
| - `release(id)` → `updateTask { id, status: "pending" }` on a held row. | ||
| - `retry(id)` → FIX-2383's verb. It lands with FIX-2383's implementation: the package PR stacks | ||
| on it, and adds `retry` only once that verb exists on its base. Until then the surface is the | ||
| other four. | ||
| - `refile(row, overrides?)` → `createTask` with the row's `goal`, `title`, `context`, | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| `assignee`, `labels` and `priority`, overrides winning, resolving to the new task id | ||
| ([D3](DECISIONS.md#d3)). Its input is a `RefileRow` with exactly those fields, so a browser's | ||
| row or a server's `Task` fits. | ||
| - **Workforce's conversation board exposes `context` to the browser**, beside `goal`. Without it a | ||
| re-file from a browser's row would silently drop part of the brief ([D3](DECISIONS.md#d3)). | ||
| - **`taskActionName(tool, board)`** is exported from the same entry: the one place an app gets a | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| board's action name, for a reader that builds an `InboxRow.holder` or a test that acts on the | ||
| board directly. An app that changes a task calls `board(at)`, never a name it built. It uses `taskToolSuffix`, which moves to a | ||
| browser-safe leaf module so `./inbox` stays free of the task board's runtime. | ||
| - **One send routine.** The answer path's send, wait, list-the-output, reject-on-`ok:false` loop | ||
|
jhoffner marked this conversation as resolved.
Resolved
|
||
| becomes the routine every board action and every row answer goes through. It pages the | ||
| session's requests to find the answer (20 pages of 100, as Shift Manager's `runAction` does), | ||
| and a finished action whose answer it can't find rejects rather than reading as a yes. | ||
| - **Shift Manager** (second PR, stacked per the build order): `reads.ts` drops its | ||
| `UPDATE_TASK_ACTION` copy for `taskActionName`, and `LabReader.taskActions(conversation)` returns | ||
| `inbox.board(...)` for that conversation, one getter, for FIX-2382's buttons to call. | ||
| - **Docs:** the orchestration README's Inbox section gains the board actions. The epic's guide | ||
| (*building a workforce app from the packages*, FIX-2387) names them; no page of its own. | ||
|
|
||
| ## What stays as it is | ||
|
|
||
| `answer` and `answerOne`, and how they route. The task tools' rules: what the board refuses, and | ||
| why, is still the board's (`updateTask`'s locks, the steer limit, the finished-task rule). The | ||
| engine's abort route, which Shift Manager's Interrupt uses for a running request. Core and the | ||
| engine. Workforce's board id. | ||
|
|
||
| ## What's already here, and the debt | ||
|
|
||
| | Piece | What this does with it | | ||
| |---|---| | ||
| | `createInboxClient` and its `answerRowQuestion` loop | **Extends.** The loop becomes the shared routine; the client gains `board(at)` | | ||
| | The task tools' `updateTask` and `createTask` actions | **Reuses.** No new board verb here; the helper only names and sends them | | ||
| | Workforce's `CONVERSATION_BOARD_CLIENT_FIELDS` | **Extends** by one field, `context` | | ||
| | `taskToolSuffix` in `task-tools-capability.ts` | **Moves** to a leaf module, re-exported where it is today | | ||
| | FIX-2383's retry verb | **Reuses**, as this issue's base branch | | ||
| | Shift Manager's `UPDATE_TASK_ACTION`, the Claude Code-style lab's copy and `run` loop | **Replaced:** Shift Manager's here; the lab's in FIX-2382's lab stack, which owns that file in the wave | | ||
| | The DevTool's own `task-actions.ts` suffix mirror | **Left.** The DevTool depends on client, core and react only, by design | | ||
|
|
||
| **Adds:** one method and one helper on an existing client, and a moved function. **Removes:** two | ||
| copies of the action name and one copy of the send loop. **Debt:** a re-filed row doesn't record | ||
| what it was re-filed from, since a browser's row carries no metadata ([D3](DECISIONS.md#d3)). | ||
| **Net:** smaller. | ||
|
|
||
| ## Sign off | ||
|
|
||
| **Approve by merging.** The one call is **the shape** ([D1](DECISIONS.md#d1)): the board's actions | ||
| hang off the Inbox client you already have, bound once per board, and answering stays the Inbox's. | ||
| *If wrong:* the methods move to another name on the same client; no stored data depends on it. | ||
|
|
||
| Feature · `orchestration`, then `shift-manager` · small · 2 PRs (package on FIX-2383's branch; | ||
| Shift Manager's `reads.ts` after FIX-2379, per the epic's build order) | ||
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.