[ParidelPooya]

Summary

This PR adds two MicroVM examples and their cloud tests. The Python 3.13 cloud-test job builds a MicroVM image from this repo, deploys both examples, and runs both tests against the real Lambda MicroVMs service. It mirrors the JavaScript SDK examples (microvm/run-job and microvm/session).

The PR has four commits, one per step. Each commit can be reviewed alone, in order.

Why

The extras package and the MicroVM worker have only fake-client and in-process tests. No test runs them against a real MicroVM. The language testing stack in the CI account now has the MicroVM roles, the artifact bucket, and the MicroVM policies. So the cloud tests can launch MicroVMs.

Commits

1. feat(examples): deploy MicroVM examples only with an image

1. The SAM template declares MicrovmImageArn and MicrovmExecutionRoleArn, both with default "".
2. The condition HasMicrovmImage holds when both are set. A catalog example with "usesMicrovm": true and its log group carry the condition. Its function gets MICROVM_IMAGE_ARN and MICROVM_EXECUTION_ROLE_ARN.
3. The catalog key timeout sets the function timeout.
4. generate_function_name_map.py leaves out MicroVM examples unless --include-microvm is passed. A test missing from the map is skipped.
5. @pytest.mark.durable_execution(..., cloud_only=True) skips a test in local mode, because the local runner cannot launch a MicroVM.

The template for the current catalog gains only the two parameters. sam validate --lint reports nothing new.

2. feat(examples): build the MicroVM image

1. microvm-image/ holds the app that the image runs, a python:3.13-alpine Dockerfile, and exact pins for boto3 1.43.118 and its dependencies. The app's default handler counts the words of a text and hashes it. Its routes /write and /read write and read files under /tmp/session.
2. scripts/ensure_microvm_image.py is a port of the JavaScript ensure-microvm-image.ts:
   1. It builds the worker wheel from the repo and zips it with the image files.
   2. It names the image sdk-python-examples-<12 hex>. The hash covers the worker source, the image files, and the CreateMicrovmImage settings. It does not cover the wheel bytes, because two builds of one source can produce different wheels.
   3. It reuses an image with that name. Otherwise it uploads the zip and calls CreateMicrovmImage with the JavaScript settings.
   4. It handles each image state as the JavaScript script does, including two CI runs that build or delete the same image at the same time.
3. cloud-tests.yml: only the Python 3.13 job runs the script. It passes the image to sam deploy and --include-microvm to the name map. The worker runs in the MicroVM, not in the function. So one image serves every function runtime. The other jobs do not change.

3. feat(examples): add the MicroVM run-job example

1. src/microvm/microvm_run_job.py calls microvm(context, "count-words", job_input={"text": ...}).
2. build_examples.py installs the extras into the Lambda bundle. The examples package does not depend on the extras, because the extras are not on PyPI. So the examples and dev-examples environments add the extras as a workspace member.
3. test/microvm/test_microvm_run_job.py is cloud-only. It checks the result, the operation tree, and that the MicroVM terminated.
4. test/microvm/microvm_helpers.py adds expect_microvm_terminated(). A failed TerminateMicrovm does not fail the operation. So the helper reads the state with GetMicrovm, every 2 seconds for up to 30 seconds.

4. feat(examples): add the MicroVM session example

1. src/microvm/microvm_session.py calls microvm_session(context, "file-session", ...). Its handler sends write to /write, waits 5 seconds, and sends read to /read.
2. The catalog entry sets "timeout": 120. Every session job goes over HTTP, which needs a function timeout of at least 71 seconds.
3. The cloud-only test checks that the second job read the file that the first job wrote, and that both jobs ran in the session's MicroVM. It also checks termination and the operation tree.

Testing

• The operation trees in both tests come from a local run of each example against a fake MicroVMs client and the real worker on a loopback port. Both test bodies passed against those local results.
• Unit tests cover the template condition, the name map, cloud_only, the image state handling with a fake service and clock, the CreateMicrovmImage request against the botocore model, hash stability, _require_microvm_env, and expect_microvm_terminated.
• A local build of the image zip twice gave the same hash and a 60 KB zip. A local container build of the zip answered the ready and run hooks.
• hatch run test:all on the whole repo: 5721 passed, 4 skipped. Both MicroVM tests skip locally with the cloud-only reason.

The first cloud run of this PR verifies what a local run cannot: the real image build, the S3 upload, the IAM permissions, the MicroVM boot, callbacks from the MicroVM to the function, and the 120-second session timeout.

Cloud effect

On the Python 3.13 job, in the CI account, us-west-2:

1. The first run creates one MicroVM image, sdk-python-examples-<hash>, and one S3 object, examples/<name>.zip, in microvm-image-artifacts-<account>-us-west-2. A later run with the same inputs reuses the image.
2. The deploy adds two functions to the Py313-python-examples stack: Py313-MicrovmRunJob and Py313-MicrovmSession.
3. Each run launches 2 MicroVMs. The operations terminate them, and the tests check it.

The other Python versions do not change.

Not in this PR

• No cleanup of old images. Each change to the image inputs keeps one more image. The JavaScript examples have no cleanup either.
• cli.py has its own runtime package list without the extras. A deploy through cli.py would lack the extras and the MicroVM variables.