[ParidelPooya]

Summary

This PR adds suspend_after to vm.invoke. A session job with suspend_after=True asks the worker to suspend its MicroVM when the job ends. The next job of the session resumes the MicroVM. So a session can stop paying for a running MicroVM during a long wait, without auto-suspend.

Why

1. A session has one way to suspend its MicroVM today: auto-suspend after an idle time.
2. The developer often knows the exact point where the MicroVM can suspend, such as the job before a long callback or wait.
3. A suspend from the durable function would need its own durable step, and it could freeze a job that still runs.
4. So the worker suspends the MicroVM after the job, once no other work runs. The durable function only marks the job.

The JavaScript SDK adds the same option in aws/aws-durable-execution-sdk-js#1105.

Changes

Worker (aws-durable-execution-sdk-python-microvm-worker):

• The job request can carry "suspendAfter": true. The worker accepts only JSON true. The job document stays version 1, so older workers ignore the field.
• The worker answers such a request with the header X-Microvm-Suspend-After: accepted. A second delivery gets the header when the first request carried the field.
• The worker suspends only the MicroVM that the run hook named, never one from a job request.
• When a suspend_after job ends, after its report, the worker records a request. The request fires when no job, report, run hook, or suspend call runs, and the worker is not terminating, closed, or refusing jobs.
• The call uses the existing suspend path: the refusal of jobs, one attempt, no attempt after a resume hook, the outcome classification, and the 30-second grace.
• A request is done when any suspend starts, or when a suspend refusal is in effect. A terminate hook and close() clear it. A resume hook never sets it.
• Without auto-suspend, a suspend refused for now is not retried.
• New log lines: suspending the MicroVM after a job and cannot suspend the MicroVM after a job: the run hook named no MicroVM. The failed-suspend warning adds trigger (idle or job) as its last field.
• Decisions are made under _locked(), and the actions run after the block.

Extras (aws-durable-execution-sdk-python-extras):

• MicrovmInvokeOptions.suspend_after: bool = False. microvm() rejects it with ValidationError, and a value that is not a bool is rejected, both before any durable operation.
• The session sets an in-memory flag before the job's child context. From then on, each job checks the state before delivery, and resumes a suspended MicroVM, as in resume mode.
• The flag is not rebuilt when a completed map item, parallel branch, or child context replays. So every session job also has a fallback. A delivery that gets HTTP 502 with x-aws-proxy-error: MICROVM_CONNECT_FAILED, or no answer, makes one state check, resumes a suspending or suspended MicroVM, and sends the job again. It runs at most one check per 2 seconds.
• A denied GetMicrovm in the fallback logs one warning per job, and the delivery keeps retrying. A denied ResumeMicrovm while the MicroVM is suspended fails the job at once, and the message names lambda:ResumeMicrovm.
• A 202 without the acknowledgement header logs one warning per session: the worker is too old, and the MicroVM keeps running.
• README sections and docstrings are updated. The docs say when to use the option, and when not: on back-to-back jobs, on map items, and on the last job.

Examples:

• New example microvm_session_suspend_after.py and cloud test test_microvm_session_suspend_after.py. The session has no auto-suspend. The first job writes a file with suspend_after=True. A callback gate holds the second job until the test sees the MicroVM SUSPENDED. The second job resumes the MicroVM and reads the file.

Testing

• Worker unit tests cover each rule: the target, the fire conditions, the re-checks, the clears, the acknowledgement, the logs, and the interaction with auto-suspend and the lifecycle hooks.
• Extras unit tests cover the validation, the field, the warning, the flag, the fallback trigger, the rate limit, and each error rule.
• Composed tests run the session against the real worker: a suspend_after job and then a job that resumes the MicroVM; a map with one suspend_after item; a replay that lost the flag and recovers through the fallback; an old worker without the acknowledgement.
• hatch run dev-microvm-worker:cov: 519 tests pass, worker.py at 100%. hatch run dev-extras:cov: 450 tests pass, 100%. Both typechecks, hatch fmt --check, dev-examples:test, and lintcommit.py pass.
• All 4 MicroVM cloud example tests passed against the live service, including the new one. The MicroVM suspended after the first job, and the second job resumed it and read the file.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.