feat(sdk): support tenantId in context.invoke() for tenant isolation (#467)

Add `tenantId` option to `InvokeConfig` so durable functions can invoke
tenant-isolated Lambda functions. The `TenantId` is passed through to
`ChainedInvokeOptions`, which the backend already supports.

Author: blimmer

packages/aws-durable-execution-sdk-js-examples/src/examples/invoke/tenant-id/invoke-tenant-id-tenant-id.history.json

@@ -0,0 +1,72 @@
+[
+  {
+    "EventType": "ExecutionStarted",
+    "EventId": 1,
+    "Id": "583741d8-8da7-46b2-a96a-95250aa494d5",
+    "EventTimestamp": "2026-03-05T17:38:24.487Z",
+    "ExecutionStartedDetails": {
+      "Input": {
+        "Payload": "{\"functionName\":\"wait-named\",\"tenantId\":\"tenant-abc-123\"}"
+      }
+    }
+  },
+  {
+    "EventType": "ChainedInvokeStarted",
+    "SubType": "ChainedInvoke",
+    "EventId": 2,
+    "Id": "c4ca4238a0b92382",
+    "EventTimestamp": "2026-03-05T17:38:24.491Z",
+    "ChainedInvokeStartedDetails": {
+      "FunctionName": "",
+      "Input": {
+        "Payload": ""
+      },
+      "DurableExecutionArn": ""
+    }
+  },
+  {
+    "EventType": "InvocationCompleted",
+    "EventId": 3,
+    "EventTimestamp": "2026-03-05T17:38:24.513Z",
+    "InvocationCompletedDetails": {
+      "StartTimestamp": "2026-03-05T17:38:24.487Z",
+      "EndTimestamp": "2026-03-05T17:38:24.513Z",
+      "Error": {},
+      "RequestId": "d2173995-9714-481b-9e9d-3dbc76cab2b8"
+    }
+  },
+  {
+    "EventType": "ChainedInvokeSucceeded",
+    "SubType": "ChainedInvoke",
+    "EventId": 4,
+    "Id": "c4ca4238a0b92382",
+    "EventTimestamp": "2026-03-05T17:38:26.600Z",
+    "ChainedInvokeSucceededDetails": {
+      "Result": {
+        "Payload": "\"wait finished\""
+      }
+    }
+  },
+  {
+    "EventType": "InvocationCompleted",
+    "EventId": 5,
+    "EventTimestamp": "2026-03-05T17:38:26.603Z",
+    "InvocationCompletedDetails": {
+      "StartTimestamp": "2026-03-05T17:38:26.602Z",
+      "EndTimestamp": "2026-03-05T17:38:26.603Z",
+      "Error": {},
+      "RequestId": "d3426f73-673f-4e40-a240-d56bb90d733c"
+    }
+  },
+  {
+    "EventType": "ExecutionSucceeded",
+    "EventId": 6,
+    "Id": "583741d8-8da7-46b2-a96a-95250aa494d5",
+    "EventTimestamp": "2026-03-05T17:38:26.603Z",
+    "ExecutionSucceededDetails": {
+      "Result": {
+        "Payload": "\"wait finished\""
+      }
+    }
+  }
+]

packages/aws-durable-execution-sdk-js-examples/src/examples/invoke/tenant-id/invoke-tenant-id.test.ts

@@ -0,0 +1,28 @@
+import { LocalDurableTestRunner } from "@aws/durable-execution-sdk-js-testing";
+import { createTests } from "../../../utils/test-helper";
+import { handler } from "./invoke-tenant-id";
+import { handler as namedWaitHandler } from "../../wait/named/wait-named";
+
+createTests({
+  handler,
+  tests: function (runner, { functionNameMap, assertEventSignatures }) {
+    it("should invoke with tenantId for tenant isolation", async () => {
+      if (runner instanceof LocalDurableTestRunner) {
+        runner.registerDurableFunction(
+          functionNameMap.getFunctionName("wait-named"),
+          namedWaitHandler,
+        );
+      }
+
+      const result = await runner.run({
+        payload: {
+          functionName: functionNameMap.getFunctionName("wait-named"),
+          tenantId: "tenant-abc-123",
+        },
+      });
+      expect(result.getResult()).toBe("wait finished");
+
+      assertEventSignatures(result, "tenant-id");
+    });
+  },
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/invoke/tenant-id/invoke-tenant-id.ts

@@ -0,0 +1,27 @@
+import {
+  DurableContext,
+  withDurableExecution,
+} from "@aws/durable-execution-sdk-js";
+import { ExampleConfig } from "../../../types";
+
+export const config: ExampleConfig = {
+  name: "Invoke Tenant Id",
+  description:
+    "Demonstrates invoking a tenant-isolated Lambda function using tenantId",
+};
+
+export const handler = withDurableExecution(
+  async (
+    event: {
+      functionName: string;
+      tenantId: string;
+      payload?: Record<string, unknown>;
+    },
+    context: DurableContext,
+  ) => {
+    const result = await context.invoke(event.functionName, event.payload, {
+      tenantId: event.tenantId,
+    });
+    return result;
+  },
+);

packages/aws-durable-execution-sdk-js/src/handlers/invoke-handler/invoke-handler.test.ts

@@ -391,6 +391,74 @@ describe("InvokeHandler", () => {
       });
     });
 
+    it("should pass tenantId through ChainedInvokeOptions when provided", async () => {
+      (mockContext.getStepData as jest.Mock)
+        .mockReturnValueOnce(undefined)
+        .mockReturnValue({
+          Status: OperationStatus.SUCCEEDED,
+          ChainedInvokeDetails: { Result: '{"result":"success"}' },
+        });
+
+      mockSafeDeserialize.mockResolvedValue({ result: "success" });
+
+      const invokeHandler = createInvokeHandler(
+        mockContext,
+        mockCheckpoint,
+        mockCreateStepId,
+        "parent-123",
+      );
+
+      const result = await invokeHandler(
+        "test-function",
+        { test: "data" },
+        { tenantId: "tenant-abc-123" },
+      );
+
+      expect(result).toEqual({ result: "success" });
+      expect(mockCheckpoint.checkpoint).toHaveBeenCalledWith("test-step-1", {
+        Id: "test-step-1",
+        ParentId: "parent-123",
+        Action: OperationAction.START,
+        SubType: OperationSubType.CHAINED_INVOKE,
+        Type: OperationType.CHAINED_INVOKE,
+        Name: undefined,
+        Payload: '{"serialized":"data"}',
+        ChainedInvokeOptions: {
+          FunctionName: "test-function",
+          TenantId: "tenant-abc-123",
+        },
+      });
+    });
+
+    it("should not include TenantId in ChainedInvokeOptions when not provided", async () => {
+      (mockContext.getStepData as jest.Mock)
+        .mockReturnValueOnce(undefined)
+        .mockReturnValue({
+          Status: OperationStatus.SUCCEEDED,
+          ChainedInvokeDetails: { Result: '{"result":"success"}' },
+        });
+
+      mockSafeDeserialize.mockResolvedValue({ result: "success" });
+
+      const invokeHandler = createInvokeHandler(
+        mockContext,
+        mockCheckpoint,
+        mockCreateStepId,
+        "parent-123",
+      );
+
+      await invokeHandler("test-function", { test: "data" });
+
+      const checkpointCall = (mockCheckpoint.checkpoint as jest.Mock).mock
+        .calls[0][1];
+      expect(checkpointCall.ChainedInvokeOptions).toEqual({
+        FunctionName: "test-function",
+      });
+      expect(checkpointCall.ChainedInvokeOptions).not.toHaveProperty(
+        "TenantId",
+      );
+    });
+
     it("should handle invoke with custom serdes", async () => {
       (mockContext.getStepData as jest.Mock)
         .mockReturnValueOnce(undefined)

packages/aws-durable-execution-sdk-js/src/handlers/invoke-handler/invoke-handler.ts

@@ -158,6 +158,7 @@ export const createInvokeHandler = (
           Payload: serializedPayload,
           ChainedInvokeOptions: {
             FunctionName: funcId,
+            ...(config?.tenantId && { TenantId: config.tenantId }),
           },
         });
       }

packages/aws-durable-execution-sdk-js/src/types/invoke.ts

@@ -9,4 +9,6 @@ export interface InvokeConfig<I, O> {
   payloadSerdes?: Serdes<I>;
   /** Serialization/deserialization configuration for result data */
   resultSerdes?: Serdes<O>;
+  /** Tenant identifier for invoking tenant-isolated Lambda functions */
+  tenantId?: string;
 }