Skip to content

spec(issue): shared task actions on the Inbox client (FIX-2381) - #4373

Merged
jhoffner merged 2 commits into
mainfrom
spec/FIX-2381
Nov 3, 2026
Merged

jhoffner merged 2 commits into
mainfrom
spec/FIX-2381

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

Spec for FIX-2381, child of epic FIX-2369 (#4358). Retained at specs/issues/FIX-2381/.

The one call (D1): the board's task actions hang off the Inbox client apps already have: inbox.board({ flowId, sessionId, board }).cancel(id) / .steer(id, words) / .release(id) / .retry(id) / .refile(row, overrides), bound once per board, with no second constructor (the epic's review folded that out). taskActionName(tool, board) is the one place an app gets an action name.

  • D2: no second answer call. answerOne already answers a row's question or confirm.
  • D3: a re-file copies goal, title, context, assignee, labels and priority, and the overrides win.
  • Retry calls FIX-2383's verb, and the package PR stacks on FIX-2383's branch.
  • Two PRs: the package slice first, then Shift Manager's reads.ts after FIX-2379, following the epic's build order. The Claude Code-style lab's copy is removed in FIX-2382's lab stack.

Approve by merging.


Generated by Claude Code

@jhoffner jhoffner self-assigned this Oct 31, 2026
@vercel

vercel Bot commented Oct 31, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
flow-state-dev-build-site Ready Ready Preview Oct 31, 2026 11:21pm UTC
3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 31, 2026 11:21pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 31, 2026 11:21pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 31, 2026 11:21pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 31, 2026

Copy link
Copy Markdown

FIX-2381

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 31, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-31T23:09:08.914562Z 897774e New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (direction review of FIX-2381)

Verdict: the direction is sound. Hanging the actions off InboxClient, no second answer call, and sharing the send loop are all right. None of the points below changes D1. They tighten the build and the spec. Checked against main (675f614): packages/orchestration/src/inbox/client.ts, skills/task-tools-capability.ts, shift-manager/src/lib/reads.ts.

Worth folding

  1. retry is the one speculative piece, and it forces the stack. SPEC.md says "FIX-2383's verb, in whatever shape its spec settles", but no FIX-2383 spec is on main. That makes the package PR a stack on an unmerged branch for one one-line method, while cancel/steer/release/refile need nothing from it.

    • Leaner: build those four off main now. Add retry as a small follow-on when 2383 merges, or only stack if 2383 lands first. The "goal" line and the retry leg of the verify check then move with it.
    • If you keep the stack, state retry's signature as an assumption the PR must re-confirm.
  2. refile is not idempotent, and the shared routine's timeout text is answer-specific. Today's loop throws "The answer was sent, and the board didn't say in time…" on a status-0 timeout. For cancel, steer and release a retry is harmless. For refile (createTask, which "starts a ready row at once") a user retrying after a timeout files a duplicate. E1 should say the routine takes its own timeout wording, and that refile's says the outcome is unknown and to check the board before filing again. Add a verify leg for it.

  3. refile copying assignee can be refused. task-tools-capability.ts ~L463–470 rejects an assignee on a follow-up row (follow_up_takes_no_assignee). D3 copies assignee unconditionally. Name how a follow-up row refiles: drop assignee for it, or reject with the board's words. Say which, and add it to the refusal leg.

  4. D1's "bound once per board" is weaker than it reads for Shift Manager. reads.ts derives the holder per row (boardOwnerOf uses row.ownerSessionId), so one screen holds rows from many sessions. There, board(at) is called per row, and it works out to inbox.cancel(at, id) with an extra object. The spec also leaves open what LabReader exposes ("the board's actions"), whether a board(at) pass-through or methods that take a session id. That choice decides the shape of FIX-2382's buttons, so settle it here.

    • A row → at helper would fit better than making each app build at by hand. Keep it in ./inbox only if both apps would use it.
  5. E2 needs one fact checked. The board's cancelled is z.array(z.string()).optional() (L1446), not a guaranteed list. Say what cancel resolves to when it is absent ([]?) and whether the list includes the target id. The spec says only "the ids it took along".

Architecture notes (no change requested)

  • The shared send routine is the real deepening. It currently returns void and is welded to row-hold answering, including its error strings. Make it send(action, input, { sessionId, flowId }) → output with the ok:false and 4xx mapping inside. Then answerRowQuestion and the five methods are thin callers. This is the right place to hold the "control that must fail: drop the ok:false read".
  • taskToolSuffix into a leaf module is correct, and the re-export from skills/index.ts and task-board/index.ts keeps imports intact. The DevTool's mirror stays, as the spec says. Consider adding a one-line test that asserts the two agree, so the mirror can't drift silently.
  • Do not add an update(id, patch) escape hatch because four of the five methods are one-line payload builders. The named verbs are the point (no app builds a payload).

Net

Fold items 1–5 (1 and 4 matter most); the rest is notes for the implementer.


Generated by Claude Code

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/simplify review (spec FIX-2381)

Verdict: The direction is the right simplification relative to the original issue shape. Folding createTaskActions(client, board) and a second answer call (D1/D2) matches the epic and removes the main constructor/API duplication. inbox.board(at) + one extracted send loop is a cleaner end state than exporting constants or payload builders alone (correctly rejected in the goal section).

I do not think a materially different architecture beats this spec; the remaining complexity is mostly surface area and underspecified edges, not the wrong home (./inbox).

What already went the right way

  • Extending createInboxClient instead of a second factory — aligns with FIX-2369 review fold.
  • Keeping answerOne as the only answer path — avoids parallel routing.
  • Leaving DevTool’s suffix mirror alone — good package-boundary restraint.
  • Scoping lab adapter copy to FIX-2382 — avoids a 14-deep adapter stack here.

Where the approach still adds more than necessary (consider trimming in the spec)

  1. refile vs today’s InboxRow — D3/SPEC copy context, labels, and priority from the row, but InboxRow in packages/orchestration/src/inbox/types.ts today only carries board, id, title, goal, assignee, status/holds/holder, etc. Either pin how those fields arrive (FIX-2379 row view? overrides-only? widen the type?) or defer refile to a follow-up slice so the first package PR stays cancel/steer/release (+ maybe retry).

  2. retry(id) before FIX-2383’s verb is spec’d — Public board(at) includes retry “in whatever shape FIX-2383 settles.” That couples direction approval here to a verb not yet retained in-repo. Safer simplification: spec optional retry on the first merge, or state explicitly that the package PR may ship without retry until 2383’s spec merges.

  3. Two public naming stories — taskActionName(tool, board) plus moved/re-exported taskToolSuffix is defensible for Shift Manager’s holder.action, but worth documenting that apps mutating tasks should use board(at).*, and taskActionName is for readers constructing holder (and createTask_* on re-file). Longer-term simpler shape (not required for this merge): store collection id on the holder and resolve the action inside orchestration — would drop the exported constant pattern.

  4. at.board vs InboxRow.board — Spec says at.board is the collection id ("tasks"), while Shift Manager sets InboxRow.board to the board ref (`<sessionId>.tasks`). Callers must use existing collectionOfBoard glue; worth one sentence in SPEC so implementers don’t pass row.board straight into board(at).

  5. Shared send routine should not regress Shift Manager’s listing behavior — Today answerRowQuestion lists one page (limit: 100). Shift Manager’s runAction in packages/shift-manager/src/lib/action.ts paginates up to 20×100 when finding output. If this routine becomes the single path for task-card actions, the spec should require parity with that pagination (or cite extracting from action.ts), not blindly copy the answer path’s single-page list.

  6. LabReader “exposes board actions” — Prefer returning inbox.board({ flowId, sessionId, board }) from a small helper over new methods on LabReader, so FIX-2382 buttons call one API.

Skipped (product / sequencing — mention only)

  • Whether goal-check belongs in packages/workforce/test vs orchestration/integration-tests tier (valid either way; workforce harness is realistic but couples packages).
  • Epic table still lists FIX-2381 with “answer” — this spec correctly drops it (D2); epic wording should follow on a later pass.

Performance note (inherited, amplified)

Centralizing the send/wait/list loop is correct for consistency, but it amplifies an existing chatty pattern (poll + session request list with includeResultOutput). Not a reason to reject the spec; the implementer should treat pagination/timeouts as part of the shared routine contract (see #5).

Recommendation: Merge for direction after tightening refile typing, at.board mapping, and shared-routine listing parity in the spec text. Optional scope cut: ship cancel / steer / release first; add refile and nail-down retry when row types and FIX-2383 are settled.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-2381/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2381/SPEC.md Resolved
Comment thread specs/issues/FIX-2381/SPEC.md Resolved
Comment thread specs/issues/FIX-2381/SPEC.md Resolved
Comment thread specs/issues/FIX-2381/SPEC.md Resolved
Comment thread specs/issues/FIX-2381/SPEC.md Resolved
Comment thread specs/issues/FIX-2381/SPEC.md Resolved
@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

1 similar comment
@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Keep it up!

Reviewed commit: e813f22878

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e813f22878

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread specs/issues/FIX-2381/DECISIONS.md Resolved
…y lands with FIX-2383, paging)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiDLxJJmXUSvc2F7Nrp
@jhoffner
jhoffner added this pull request to the merge queue Nov 3, 2026
Merged via the queue into main with commit c8968b6 Nov 3, 2026
20 checks passed
@jhoffner
jhoffner deleted the spec/FIX-2381 branch November 3, 2026 18:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants