feat: forward optional suspend and resume reasons

[wangbill (YunchuWang)]

Summary

What changed?

• Add optional reason?: string to suspendOrchestration() and resumeOrchestration(). Send literal strings through the existing protobuf fields, preserving empty strings and omitting undefined/runtime null. One-argument calls remain valid.
• Forward reasons through the classic Functions aliases and into existing in-memory suspension/resumption history events. Update API JSDoc and both affected changelogs.

Why is this change needed?

• Previously the core client sent only the instance ID, and Functions accepted but ignored reasons. This matches .NET's existing literal reason forwarding.

Issues / work items

• N/A

---

Project checklist

• Release notes are not required for the next release
  • Otherwise: Notes added to CHANGELOG.md
• Backport is not required
  • Otherwise: Backport tracked by issue/PR #issue_or_pr
• All required tests have been added/updated (unit tests, E2E tests)
• Breaking change?
  • If yes:
    • Impact: N/A
    • Migration guidance: N/A

---

AI-assisted code disclosure (required)

Was an AI tool used? (select one)

• No
• Yes, AI helped write parts of this PR (e.g., GitHub Copilot)
• Yes, an AI agent generated most of this PR

If AI was used:

• Tool(s): GitHub Copilot
• AI-assisted areas/files: Core client, in-memory client/backend/event helpers, Functions aliases, regression tests, JSDoc, and changelogs.
• What you changed after AI output: No human edits asserted. The agent corrected a test fixture type error before confirming behavioral RED, then implemented the narrow passthrough.

AI verification (required if AI was used):

• I understand the code and can explain it
• I verified referenced APIs/types exist and are correct
• I reviewed edge cases/failure paths (timeouts, retries, cancellation, exceptions)
• I reviewed concurrency/async behavior
• I checked for unintended breaking or behavior changes

Human attestations are left for the reviewer; automated evidence follows.

---

Testing

Automated tests

• Result: Passed locally, 184 tests in 4 focused suites. Added 18 loopback-gRPC cases and 4 in-memory history cases; updated the existing Functions alias test.
• Command: npm exec --no -- jest --config jest.config.js --runInBand --silent --detectOpenHandles --runTestsByPath packages/durabletask-js/test/client-suspend-resume.spec.ts packages/durabletask-js/test/in-memory-backend.spec.ts packages/durabletask-js/test/orchestration_executor.spec.ts packages/azure-functions-durable/test/unit/client.spec.ts
• RED before implementation: 7 expected runtime assertion failures across wire payloads, in-memory history, and Functions forwarding (no TypeScript errors).
• npm run build -w durable-functions passed, including the core build and emitted declarations.
• Scoped ESLint, normal Husky/lint-staged commit hooks, and git diff --check origin/main...HEAD passed.
• Baseline-aware Prettier comparison passed: no new formatting deviations. Raw whole-file checks flag preserved CRLF and pre-existing formatting; no unrelated reformatting was applied.

Manual validation (only if runtime/behavior changed)

• Environment (OS, Node.js version, components): Windows, Node.js 24.14.0; local loopback gRPC and in-memory runtime.
• Steps + observed results:
  1. Automated loopback requests retain exact whitespace, quotes, newline, Unicode, and explicit empty-string wrappers; omitted/undefined/runtime-null reasons remain absent.
  2. Invalid instance IDs still reject before RPC; service failures and existing lifecycle/replay tests pass.
  3. In-memory history retains reasons after completion; Functions aliases forward them. No separate manual service run, emulator, or Azure tests were performed.
• Evidence (optional): Hosted CI is pending and is not claimed as passed.

---

Notes for reviewers

• Scoped only to suspend/resume reasons: no protocol/generated-source changes, DataConverter, AbortSignal, retry, telemetry, or other parity work.
• Functions HTTP management links already include reason={text} and are unchanged; their endpoints are host-owned. Azure-managed clients inherit the core API.
• Base: 6505acd5fce6fb6acfbb7560b4e15c2d0e8b42ea (main), not another parity PR.

[Copilot]

Copilot review overview

🟢 Approval recommended

No unresolved blocking issues were identified.

Review effort: Lite
Findings: None

What changed in this PR

Adds optional suspend/resume reasons across core gRPC clients, in-memory testing, and Azure Functions aliases while preserving empty-string and omission semantics.

Changes:

• Forwards reasons through gRPC and classic aliases.
• Records reasons in in-memory history events.
• Adds regression tests, documentation, and changelog entries.

File	Description
packages/​durabletask-js/​test/​in-memory-backend.spec.ts	Tests reason preservation in in-memory history.
packages/​durabletask-js/​test/​client-suspend-resume.spec.ts	Tests gRPC reason forwarding.
packages/​durabletask-js/​src/​utils/​pb-helper.util.ts	Builds reason-bearing history events.
packages/​durabletask-js/​src/​testing/​test-client.ts	Exposes reason-aware test APIs.
packages/​durabletask-js/​src/​testing/​in-memory-backend.ts	Records suspension and resumption reasons.
packages/​durabletask-js/​src/​client/​client.ts	Sends optional reasons in requests.
packages/​azure-functions-durable/​test/​unit/​client.spec.ts	Tests alias reason forwarding.
packages/​azure-functions-durable/​src/​client.ts	Forwards reasons through classic aliases.
packages/​azure-functions-durable/​CHANGELOG.md	Documents alias behavior.
CHANGELOG.md	Documents the core API change.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.