Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
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
82 changes: 82 additions & 0 deletions specs/issues/FIX-2381/DECISIONS.md
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`
Comment thread
jhoffner marked this conversation as resolved.
Resolved
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.
Comment thread
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.
124 changes: 124 additions & 0 deletions specs/issues/FIX-2381/SPEC.md
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`,
Comment thread
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
Comment thread
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
Comment thread
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)
Loading