feat(list-conversations): paginate and find conversations by participant

[rainsjm]

The problem

While troubleshooting an automation where I wanted it to DM myself, I realized that it couldn't find that conversation because the tool didn't have access to my full list of DMs. list-conversations returned one unpaginated page — about 20 conversations. Tested against a real workspace with 239 conversations, only 20 were visible. The other 92% could not be reached by any caller.

What this enables

• Reach every conversation, not the first 20. Standard limit + cursor, matching search-content and get-mentions.
• Find a conversation by who's in it. Ask for the DM with two specific people and get that one conversation — no scanning, no guessing. An empty userIds finds the conversation with only you.
• One call, not a paging loop. Participant lookups walk the pages internally, so callers don't page and decide when to stop. That decision is where automations went wrong.

Notes for review

• Fixes archived handling. includeArchived: false was leaking archived conversations into the default listing, and includeArchived: true was returning every archived conversation twice. Verified against a live workspace: 237 active + 2 archived = 239 combined.
• A partial result never passes as a complete one. If the cursor stalls or the scan runs long, it throws. Silent truncation is what caused the original bug, so it's treated as a failure rather than a result.
• Not covered: no workspace on hand exceeds one page, so multi-page cursor advancement is tested against mocks only.
• Not included: keyword search. This filters by participant, not content — the API has no text search for conversations, and message content is already served by search-content.

Also bumps @doist/comms-sdk 0.9.0 → 1.0.1, which is where the pagination parameters live. Its only breaking change is Node >= 24, already required here.

🤖 Generated with Claude Code

[doistbot]

This PR adds pagination (limit/cursor) and participant filtering (userIds/matchMode) to list-conversations, fixes archived-conversation handling, and bumps the Comms SDK — so callers can finally reach every conversation, not just the first 20.

Few things worth tightening:

• Cursor-exhaustion inference can still hide conversations. Both the unfiltered pagination path and the internal participant scan risk marking hasMore false (or returning a partial result) when a server-capped page is simply shorter than the requested size. Since silent truncation is the exact bug this PR set out to fix, the pagination logic should either emit a continuation cursor for non-empty pages unless the API explicitly signals exhaustion, or use a lookahead request to confirm.
• A stalled cursor is treated as exhaustion instead of throwing. If a subsequent fetch repeats the same capped page, the scan sees no unseen rows but page.length < SCAN_PAGE_SIZE and quietly returns a partial/no-match result — contradicting the stated fail-on-stall guarantee. Detect repeated multi-row pages and throw rather than silently truncating.
• LLM usage guidelines in src/mcp-server.ts are out of sync. The tool instructions still describe list-conversations as a simple listing tool and don't mention participant filtering (userIds to find a specific DM by who's in it) or pagination via cursor/limit. AGENTS.md requires updating these guidelines when adding tool features, and the LLM relies on them to decide when and how to invoke the tool.

I also included a few optional follow-up notes in the details below.

Optional follow-up notes (3)

• src/tools/list-conversations.ts:203: In includes mode, an empty userIds array (targetIds.every(...) with nothing to check) is vacuously true and matches every conversation. The parameter description at L24 says "An empty array matches the conversation containing only you", but that contract only holds in exact mode. A caller passing { userIds: [], matchMode: 'includes' } would get every conversation back — surprising and contrary to the documented behavior. Fix: either extend the empty-array special case to includes mode (e.g., early-return the self-conversation matcher when targetIds.length === 0 regardless of mode), or update the description to clarify that the empty-array behaviour is specific to exact mode.
• src/tools/list-conversations.ts:266: getSessionUser() is called on every participant scan, but buildParticipantMatcher's includes branch never uses sessionUserId — only exact does. For an includes query that finds matches on the first page this doubles the API call count (one getSessionUser + one getConversations). Guard the call with matchMode === 'exact', or fetch the id lazily inside the exact branch of the matcher.
• src/tools/list-conversations.ts:215: [...expected] creates a new array each time the predicate runs during a scan. Since expected is built once when the matcher is created, hoist the spread to the outer scope: ts const expected = new Set([...targetIds, sessionUserId]) const expectedArr = [...expected] return (conversation) => { const participants = new Set(conversation.userIds) return ( participants.size === expected.size && expectedArr.every((id) => participants.has(id)) ) } This avoids re-allocating the array for every size-matching conversation in a workspace-wide walk.

_{Share Feedback • Review Logs}

[scottlovegrove]

I'm wondering whether when there's a filter being applied, we should ignore limits/cursors and just fetch all conversations and filter, otherwise you could end up in a situation where you end up with 1 result, but "hasMore: true" and there's another conversation in the second page, which is a very weird situation to be in that you've asked for 20 (for example), it's returned one, and then told you there are more when there may not even be more for that filter.