Surface JMAP error type when pin/add/remove labels fail#73
Merged
Conversation
When pinEmail, addLabels, or removeLabels gets back a JMAP `notUpdated`
response, the caller sees a generic "Failed to ... email" with no
indication of what JMAP actually rejected — the `type` and
`description` fields on the notUpdated entry are read off the result
shape and then discarded before the throw.
Through the MCP this surfaces as a bare JSON-RPC -32603 ("Internal
error: Tool execution failed: Failed to add labels to email."), with
no way to distinguish a stateMismatch race against a concurrent
delivery filter, vs. forbidden, vs. notFound, vs. serverFail. The
operator sees a write failure they can't act on, and a downstream LLM
agent has nothing to retry against.
The fix mirrors the pattern archiveEmail (jmap-client.ts:1170-1174)
already uses: read `err.type`, append `err.description` if present,
embed both in the thrown message.
Before:
Failed to add labels to email.
After:
Failed to add labels to email: stateMismatch
Failed to add labels to email: notFound - Email not found in this account
Failed to pin email: forbidden
The same defect pattern exists in markEmailRead, deleteEmail,
moveEmail, and the bulk variants (bulkMarkRead, bulkPinEmails,
bulkAddLabels, bulkRemoveLabels). Left for a follow-up so this change
stays focused on the three handlers a real write failure surfaced
through the MCP layer.
Verification:
- bun run build: clean
- bun run test: 196/196 pass. The existing notUpdated tests use
assert.match with partial regex (e.g. /Failed to move/), so the
appended `: <type>` suffix does not break them.
- Manual reproduction on a fresh non-imported email: pin_email,
add_labels, and remove_labels all succeed end-to-end with verified
mailbox state changes — confirming the success path is unchanged.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
When
pinEmail,addLabels, orremoveLabelsgets back a JMAPnotUpdatedresponse, the caller sees a genericFailed to ... emailwith no indication of what JMAP actually rejected — thetypeanddescriptionfields on thenotUpdatedentry are read off the result shape and then discarded before the throw.Through the MCP this surfaces as a bare JSON-RPC
-32603(Internal error: Tool execution failed: Failed to add labels to email.), with no way to distinguish astateMismatchrace against a concurrent delivery filter, vs.forbidden, vs.notFound, vs.serverFail. The operator sees a write failure they can't act on, and a downstream LLM agent has nothing to retry against.The fix mirrors the pattern
archiveEmail(jmap-client.ts:1170-1174) already uses: readerr.type, appenderr.descriptionif present, embed both in the thrown message.Before:
After:
The same defect pattern exists in
markEmailRead,deleteEmail,moveEmail, and the bulk variants (bulkMarkRead,bulkPinEmails,bulkAddLabels,bulkRemoveLabels). Left for a follow-up so this change stays focused on the three handlers a real write failure surfaced through the MCP layer.Test plan
npm run buildcleannpm test— 176/176 pass. The existingnotUpdatedtests useassert.matchwith partial regex (e.g./Failed to move/), so the appended: <type>suffix does not break them.pin_email,add_labels, andremove_labelsall succeed end-to-end with verified mailbox state changes — confirming the success path is unchanged.This PR was drafted with Claude Opus 4.7; I reviewed and tested each commit.