feat(mcp): item list assignee filter + pagination + lean projection, item cancel action, handoff defaults to inbox

[getappz]

What

1. item(list): assignee_agent was a dead parameter (only state_group was applied). Now filters to items assigned to that agent OR unassigned, sorted open+assigned-to-you first — surfaces claimable work alongside your own. Added limit/offset pagination. Response is now a lean ItemSummary projection (id, name, state name+group resolved from state_id, priority, assignee_agent, parent_id, sequence_id, updated_at) instead of the full 19-field Item row — get is unchanged for full detail.
2. item tool: new cancel action, mirrors done — resolves the project's existing Cancelled state via state::first_in_group and moves the item there. Agentflare already seeds a Cancelled state per project (matches Plane's StateGroup exactly) but nothing could set it.
3. /handoff: bare invocation (no argument) now defaults to inbox instead of printing a usage card.

Verification

• cargo test --bin agentflare: 417 passed, 0 failed (7 new tests)
• cargo clippy --all-targets -- -D warnings -A unsafe_code -A clippy::pedantic: clean
• cargo fmt --check: clean
• Manually confirmed item(claim) auto-creates an isolated worktree (.worktrees/task/36) — this change was built and tested entirely inside that worktree.

Summary by CodeRabbit

• New Features
  • Added support for cancelling items via the item tool, moving them into the cancelled state and releasing the caller’s claim so they aren’t left held.
  • Enhanced item listing with improved filtering and ordering: prioritizes open items, supports state-group filtering, treats “assigned to you” and unassigned items appropriately, and returns concise summaries with human-readable state and group names.
  • Added limit/offset pagination (validated to be non-negative).
  • Bare /handoff now defaults to the inbox view while retaining agent identity.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 37cc2611-655e-4222-bbeb-bd07d1c0a3f3

📥 Commits

Reviewing files that changed from the base of the PR and between d9a7aea and e826e76.

📒 Files selected for processing (1)

• src/mcp_server.rs

---

📝 Walkthrough

Walkthrough

The handoff command now defaults to inbox when no argument is supplied. The item MCP tool adds cancellation and expands listing with filtering, sorting, pagination, and lean state-aware summaries.

Changes

Handoff command defaults

Layer / File(s)	Summary
Default handoff inbox behavior src/mcp_prompts.rs	Bare /handoff now behaves like /handoff inbox, preserving the calling agent identity; tests cover both forms.

Item workflows

Layer / File(s)	Summary
Item listing contract and processing src/mcp_server.rs	Item listing supports state-group and assignee-or-unassigned filters, pagination, open-first ordering, and lean summaries with readable state values.
Item cancellation src/mcp_server.rs	The new cancel action moves an item to the first state in the cancelled state group and releases the caller’s claim lease.
Item workflow validation src/mcp_server.rs	Tests cover cancellation, claim release, filtering, ordering, pagination, validation, and lean projection output.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant MCPCaller
  participant item_inner
  participant ItemStateData
  MCPCaller->>item_inner: request item.list with filters and pagination
  item_inner->>ItemStateData: resolve states and retrieve items
  ItemStateData-->>item_inner: item rows and state definitions
  item_inner-->>MCPCaller: sorted paginated ItemSummary results

Loading

Possibly related PRs

• getappz/agentflare#153: Updates related handoff prompt and tool expectations.
• getappz/agentflare#169: Updates related /handoff prompt and argument grammar.
• getappz/agentflare#172: Updates related handoff prompt wording and flow.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers the changes and verification, but it does not follow the required template sections.	Add the missing 'Test plan' checklist and 'Notes for reviewers' sections, including risk areas and backwards compatibility.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main MCP item, handoff, and cancellation changes.
Docstring Coverage	✅ Passed	Docstring coverage is 90.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch task/36

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/mcp_server.rs`:
- Around line 2626-2643: Update the valid-action lists in the `item_inner`
unknown-action error and the `item()` tool description to include `cancel`,
matching the actions already enumerated by `ItemRequest.action`. Keep the
existing ordering and wording consistent across both locations.
- Around line 2626-2643: The cancel branch must release any active claim in
addition to updating the item state. Within the `with_backend_db` closure for
`"cancel"`, clear the item’s claim after `update_state` succeeds, using the
existing claim-management API, and preserve the current validation and response
behavior.
- Around line 2449-2454: Update the pagination handling around the offset and
limit calculations to reject negative req.offset and req.limit values with the
existing invalid_params error path instead of clamping them to zero. Preserve
zero and positive values and the current skip/take behavior for valid requests.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: fbd42f7f-4385-4704-a095-809e7abe1ffc

📥 Commits

Reviewing files that changed from the base of the PR and between 2e018cd and d9a7aea.

📒 Files selected for processing (2)

• src/mcp_prompts.rs
• src/mcp_server.rs