Parent Orchestration Access For SubOrchestration (#92)

* feat: add support for parent orchestration instance in sub-orchestrations

- Introduced ParentOrchestrationInstance type to represent details of the parent orchestration.
- Updated OrchestrationContext to include a parent property for accessing parent orchestration details.
- Enhanced newExecutionStartedEvent function to accept parent instance information.
- Modified OrchestrationExecutor to extract and set parent instance info during execution.
- Added tests to verify parent orchestration info is correctly handled in sub-orchestrations.
- Created FEATURE_PARITY.md to document feature comparison between durabletask-js and durabletask-dotnet.

* Potential fix for pull request finding 'Unused variable, import, function or class'

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

* fix: rename variable for clarity and improve test readability

* cleanup

* fix: remove redundant import of timer events in parent orchestration tests

---------

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

Author: YunchuWang

package-lock.json

@@ -78,6 +78,7 @@ export { TOrchestrator } from "./types/orchestrator.type";
 export { TActivity } from "./types/activity.type";
 export { TInput } from "./types/input.type";
 export { TOutput } from "./types/output.type";
+export { ParentOrchestrationInstance } from "./types/parent-orchestration-instance.type";
 
 // Logger
 export { Logger, ConsoleLogger, NoOpLogger } from "./types/logger.type";

packages/durabletask-js/src/index.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+import { ParentOrchestrationInstance } from "../../types/parent-orchestration-instance.type";
 import { TActivity } from "../../types/activity.type";
 import { TOrchestrator } from "../../types/orchestrator.type";
 import { TaskOptions, SubOrchestrationOptions } from "../options";
@@ -17,6 +18,16 @@ export abstract class OrchestrationContext {
    */
   abstract get instanceId(): string;
 
+  /**
+   * Gets the parent orchestration instance, or `undefined` if this is not a sub-orchestration.
+   *
+   * This property is useful for determining if the current orchestration was started by another
+   * orchestration (i.e., it's a sub-orchestration) and for accessing details about the parent.
+   *
+   * @returns {ParentOrchestrationInstance | undefined} The parent orchestration details, or `undefined` if this is a top-level orchestration.
+   */
+  abstract get parent(): ParentOrchestrationInstance | undefined;
+
   /**
    * Get the current date/time as UTC
    *

packages/durabletask-js/src/task/context/orchestration-context.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+/**
+ * Represents the parent orchestration instance details for a sub-orchestration.
+ *
+ * This information is available when an orchestration is started as a sub-orchestration
+ * by another orchestration. It provides details about the parent that started this
+ * orchestration, which can be useful for debugging and tracing.
+ */
+export interface ParentOrchestrationInstance {
+  /**
+   * The name of the parent orchestration.
+   */
+  name: string;
+
+  /**
+   * The unique instance ID of the parent orchestration.
+   */
+  instanceId: string;
+
+  /**
+   * The task scheduled ID that corresponds to this sub-orchestration in the parent's history.
+   */
+  taskScheduledId: number;
+}

packages/durabletask-js/src/types/parent-orchestration-instance.type.ts

@@ -22,7 +22,7 @@ export function newOrchestratorStartedEvent(timestamp?: Date | null): pb.History
   return event;
 }
 
-export function newExecutionStartedEvent(name: string, instanceId: string, encodedInput?: string): pb.HistoryEvent {
+export function newExecutionStartedEvent(name: string, instanceId: string, encodedInput?: string, parentInstance?: { name: string; instanceId: string; taskScheduledId: number }): pb.HistoryEvent {
   const ts = new Timestamp();
 
   const orchestrationInstance = new pb.OrchestrationInstance();
@@ -33,6 +33,19 @@ export function newExecutionStartedEvent(name: string, instanceId: string, encod
   executionStartedEvent.setInput(getStringValue(encodedInput));
   executionStartedEvent.setOrchestrationinstance(orchestrationInstance);
 
+  // Set parent instance info if provided (for sub-orchestrations)
+  if (parentInstance) {
+    const parentOrchestrationInstance = new pb.OrchestrationInstance();
+    parentOrchestrationInstance.setInstanceid(parentInstance.instanceId);
+
+    const parentInstanceInfo = new pb.ParentInstanceInfo();
+    parentInstanceInfo.setName(getStringValue(parentInstance.name));
+    parentInstanceInfo.setOrchestrationinstance(parentOrchestrationInstance);
+    parentInstanceInfo.setTaskscheduledid(parentInstance.taskScheduledId);
+
+    executionStartedEvent.setParentinstance(parentInstanceInfo);
+  }
+
   const event = new pb.HistoryEvent();
   event.setEventid(-1);
   event.setTimestamp(ts);

packages/durabletask-js/src/utils/pb-helper.util.ts

@@ -129,6 +129,17 @@ export class OrchestrationExecutor {
               throw new OrchestratorNotRegisteredError(executionStartedEvent?.getName());
             }
 
+            // Extract parent instance info if this is a sub-orchestration
+            const parentInstance = executionStartedEvent?.getParentinstance();
+            if (parentInstance) {
+              const parentOrchestrationInstance = parentInstance.getOrchestrationinstance();
+              ctx._parent = {
+                name: parentInstance.getName()?.getValue() ?? "",
+                instanceId: parentOrchestrationInstance?.getInstanceid() ?? "",
+                taskScheduledId: parentInstance.getTaskscheduledid(),
+              };
+            }
+
             // Deserialize the input, if any
             let input = undefined;
 

packages/durabletask-js/src/worker/orchestration-executor.ts

@@ -4,6 +4,7 @@
 import { createHash } from "crypto";
 import { getName } from "../task";
 import { OrchestrationContext } from "../task/context/orchestration-context";
+import { ParentOrchestrationInstance } from "../types/parent-orchestration-instance.type";
 import * as pb from "../proto/orchestrator_service_pb";
 import * as ph from "../utils/pb-helper.util";
 import { CompletableTask } from "../task/completable-task";
@@ -28,6 +29,7 @@ export class RuntimeOrchestrationContext extends OrchestrationContext {
   _newGuidCounter: number;
   _currentUtcDatetime: Date;
   _instanceId: string;
+  _parent?: ParentOrchestrationInstance;
   _completionStatus?: pb.OrchestrationStatus;
   _receivedEvents: Record<string, any[]>;
   _pendingEvents: Record<string, CompletableTask<any>[]>;
@@ -48,6 +50,7 @@ export class RuntimeOrchestrationContext extends OrchestrationContext {
     this._newGuidCounter = 0;
     this._currentUtcDatetime = new Date(1000, 0, 1);
     this._instanceId = instanceId;
+    this._parent = undefined;
     this._completionStatus = undefined;
     this._receivedEvents = {};
     this._pendingEvents = {};
@@ -60,6 +63,10 @@ export class RuntimeOrchestrationContext extends OrchestrationContext {
     return this._instanceId;
   }
 
+  get parent(): ParentOrchestrationInstance | undefined {
+    return this._parent;
+  }
+
   get currentUtcDateTime(): Date {
     return this._currentUtcDatetime;
   }