[nvignola]

Context

Agent Core needs to send the asking comment's ID when posting an answer, so the backend can notify the question's audience. The exported comment request schema drops this field today.

This prepares the SDK for the backend change. Agent Core adoption follows once the SDK version is published.

What was changed

• comments.createComment accepts optional clientRequestId, sent as client_request_id. Schema parsing preserves it; existing calls omit the key.
• The JSDoc and README explain that this is the ID of the comment being answered, and only Agent Core's replies honour it. Other callers' values are ignored.
• The feat: title requests a minor release through the existing version and changelog automation, currently targeting 5.1.0.

Proof

• The MSW regression failed before the schema change and passed afterward. It asserts the exact request body with clientRequestId: 'abc' and with the field omitted.
• npm run verify, the docs site build, and npm run attw passed.
• Task review, compatibility review, and verified local Doistbot review found no issues.

Not verified: real Comms API behavior, an Agent Core consumer integration, or Node 26 locally.

Refs

• Related: https://app.todoist.com/app/task/6hxhcqFQQWPVJRJH
• Backend counterpart: https://github.com/todoist/comms-backend/pull/1442

[nvignola]

This PR stays in draft until https://github.com/todoist/comms-backend/pull/1442 is merged.

[doistbot]

This PR adds an optional clientRequestId to comment creation, flowing through the existing schema, serialization path, and docs, with an MSW regression test covering both supplied and omitted values — a clean, small, additive change with no inline issues flagged.

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

Optional follow-up notes (2)

• README.md:70: The public README names the internal "Agent Core" service. This repository is public and the README ships in the npm package; the repo privacy check calls out documenting Todoist-internal tools. Rephrase to describe which replies honour clientRequestId without the internal product name (the JSDoc in comments-client.ts has the same wording).
• src/types/requests.ts:70: Adding clientRequestId to CreateCommentArgsSchema also widens CloseThreadArgs/ReopenThreadArgs, since they derive from CreateCommentArgs via ThreadActionCommentArgs. threads.closeThread/reopenThread now accept and forward client_request_id, but the JSDoc and README only document comments.createComment. If that forwarding is intended, document the option on those two methods too; otherwise exclude it there, e.g. Omit<CreateCommentArgs, 'threadId' | 'clientRequestId'> & { id: string }.

_{Share Feedback • Review Logs • Trace}

[nvignola]

Addressed both optional follow-ups in 686922b.

Rephrase to describe which replies honour clientRequestId without the internal product name.

The README and JSDoc now say "Comms' agent service".

If that forwarding is intended, document the option on those two methods too.

Added the parameter documentation to threads.closeThread and threads.reopenThread, and included both in the README. Their shared argument type and runtime behavior stay unchanged; both methods post comments through /comments/add.

npm run verify and the docs site build passed.

[doist-release-bot]

🎉 This PR is included in version 5.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀