Get Orchestration History

[YunchuWang]

Summary

What changed?

• Added getOrchestrationHistory(instanceId: string) method to TaskHubGrpcClient that retrieves the complete history of an orchestration instance as an array of typed HistoryEvent objects
• Created comprehensive TypeScript type definitions for all 30+ history event types (ExecutionStartedEvent, TaskScheduledEvent, TaskCompletedEvent, TimerCreatedEvent, SubOrchestrationInstanceCreated, etc.)
• Implemented protobuf-to-TypeScript converter utilities for transforming gRPC history events
• Added TraceContext and ParentInstanceInfo types for distributed tracing and sub-orchestration support
• Exported all new types from the package index

Why is this change needed?

• Feature parity with the .NET SDK's GetOrchestrationHistoryAsync method
• Enables users to inspect orchestration execution history for debugging, monitoring, and analysis purposes
• Required for building dashboards and tooling that display orchestration execution details

Issues / work items

• Resolves Get Orchestration History #88

---

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: None - this is a new additive API
    • 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 (Claude)
• AI-assisted areas/files:
  • packages/durabletask-js/src/orchestration/history-event.ts - Type definitions for all history events
  • packages/durabletask-js/src/utils/history-event-converter.ts - Proto to TS conversion logic
  • packages/durabletask-js/src/client/client.ts - getOrchestrationHistory method implementation
  • test/e2e-azuremanaged/history.spec.ts - Comprehensive E2E tests
• What you changed after AI output: Reviewed and validated all type definitions against proto schema, fixed edge cases in converter, clarified behavior for non-existent instances

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

---

Testing

Automated tests

• Result: Passed
• 11 E2E tests in test/e2e-azuremanaged/history.spec.ts covering:
  • Simple orchestration history
  • Orchestrations with activities
  • Timer events
  • Sub-orchestration events
  • External events
  • Error handling (terminated, failed orchestrations)
  • Empty instanceId validation
  • Non-existent orchestration handling (returns empty array per DTS behavior)
  • Event ID ordering
  • Suspend/resume events
  • Complete history event sequence validation with exact position checks

Manual validation (only if runtime/behavior changed)

• Environment: Windows, Node.js, DTS Emulator (Docker)
• Steps + observed results:
  1. Started DTS emulator container
  2. Ran npx jest test/e2e-azuremanaged/history.spec.ts --runInBand --forceExit
  3. All 11 tests passed

---

Notes for reviewers

• The DTS backend returns an empty stream (resulting in empty array) for non-existent orchestration instances, rather than throwing NOT_FOUND. This differs from what the .NET SDK expects but matches the actual backend behavior in PartitionGrain.ClientOperations.cs. The implementation includes NOT_FOUND error handling for future-proofing.
• Stream event listeners are properly cleaned up with removeAllListeners() to prevent memory leaks.
• The OrchestrationStatus enum from protobuf doesn't have a reverse mapping, so an explicit ORCHESTRATION_STATUS_MAP is used for conversion.

[Copilot]

Pull request overview

This pull request adds the ability to retrieve orchestration execution history through a new getOrchestrationHistory API method. The PR introduces comprehensive type definitions for all history event types, implements conversion from protobuf messages to TypeScript objects, and includes extensive E2E test coverage.

Changes:

• Added getOrchestrationHistory method to TaskHubGrpcClient for retrieving instance execution history
• Introduced StartOrchestrationOptions interface to support passing tags and other metadata when scheduling orchestrations
• Created comprehensive type definitions for 26+ history event types covering orchestration lifecycle, activities, timers, sub-orchestrations, external events, and entities
• Implemented protobuf-to-TypeScript conversion logic for all history event types

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/durabletask-js/src/orchestration/history-event.ts	Defines TypeScript interfaces for all history event types including ExecutionStarted, TaskScheduled, TimerCreated, etc.
packages/durabletask-js/src/utils/history-event-converter.ts	Implements conversion from protobuf HistoryEvent messages to TypeScript HistoryEvent objects
packages/durabletask-js/src/client/client.ts	Adds getOrchestrationHistory method and extends scheduleNewOrchestration to support tags via StartOrchestrationOptions
packages/durabletask-js/src/index.ts	Exports history event types and StartOrchestrationOptions for public API consumption
test/e2e-azuremanaged/history.spec.ts	Comprehensive E2E tests validating history retrieval for various orchestration patterns including activities, timers, sub-orchestrations, and external events

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[torosent]

1. Inconsistent error handling for NOT_FOUND

Location: client.ts#L836-L845

The implementation throws an error when an orchestration is not found:

if (err.code === grpc.status.NOT_FOUND) {
  reject(new Error(`An orchestration with the instanceId '${instanceId}' was not found.`));
}

However, the E2E test expects an empty array:

// test/e2e-azuremanaged/history.spec.ts:267-270
it("should return empty array for non-existent orchestration", async () => {
  const history = await taskHubClient.getOrchestrationHistory("non-existent-instance-id");
  expect(history).toEqual([]);
});

Recommendation: Either fix the test to expect an error, or change the implementation to return an empty array for NOT_FOUND (which is more user-friendly and consistent with other SDKs).

---

2. Missing unit tests for convertProtoHistoryEvent

Location: history-event-converter.ts

The converter utility is ~300 lines with a complex switch statement covering 25+ event types. There are no unit tests for it—only E2E tests exist.

Impact: Edge cases where protobuf fields are missing/undefined may not be caught.

Recommendation: Add unit tests covering:

• Each event type conversion
• Missing optional fields
• Null/undefined handling
• Invalid event type case (default branch)