feat(extras): add microvm_session

[ParidelPooya]

Summary

Part 5 of the MicroVM port: microvm_session() runs several jobs in one MicroVM. It follows microvmSession in @aws/durable-execution-sdk-js-extras.

A session launches one MicroVM and runs a handler with a MicrovmSession handle. Each vm.invoke sends one job to the MicroVM and returns its result. The jobs share the MicroVM's files and processes, so a later job can use what an earlier job wrote. The MicroVM is terminated when the handler returns or raises.

def pipeline(vm: MicrovmSession, ctx: DurableContext) -> Any:
    build = vm.invoke(ctx, "build", job_input=event, options=MicrovmInvokeOptions(path="/build", timeout=Duration.from_minutes(15)))
    return vm.invoke(ctx, "test", job_input=build, options=MicrovmInvokeOptions(timeout=Duration.from_minutes(10)))

result = microvm_session(context, "pipeline", config=SESSION, handler=pipeline)

Durable operations

The session runs in one child context named name:

1. <name>.session generates a random session ID and checkpoints it.
2. <name>.launch calls RunMicrovm. The client token is the SHA-256 hex digest of the session ID. So a retried or replayed launch returns the same MicroVM.
3. The handler runs. Each vm.invoke creates a child context named after the job, with a callback <job>.callback and a request step <job>.request. Every job goes over HTTP, and the MicroVM gets the ALL_INGRESS connector.
4. <name>.terminate calls TerminateMicrovm.

vm.invoke takes the context that the call runs in, as microvm does. So it works in the session's context, a nested child context, and map and parallel items. It raises TypeError for the context that microvm_session was called with. A job created there lands outside the session's child context. The core SDK does not refuse that, and the next replay fails with NonDeterministicExecutionError after the job has run. JS refuses an operation in a parent context at the first call. Checking every context outside the session would need support in the core SDK.

Suspending an idle MicroVM

A session can suspend its MicroVM between jobs:

1. auto_suspend_on_idle=True sends autoSuspendIdleSeconds in the run hook payload. The worker then suspends its own MicroVM when no job has run for that long. The default is 60 seconds, or the session timeout if that is shorter.
2. idle_policy sets the RunMicrovm idle policy.

With either setting, each request step calls GetMicrovm first, resumes a suspended MicroVM, and sends the job to the endpoint that GetMicrovm reports. The MicroVM can suspend itself between that check and the request. So after a 502, 503, or 504, or a request without an answer, the step checks the state again before it retries. A MicroVM that is terminating, terminated, or removed fails the job at once with the new MicrovmNotRunningError, a subclass of MicrovmDeliveryError.

The Python worker reads autoSuspendIdleSeconds but does not suspend its MicroVM yet. That comes with the worker's suspend and terminate hooks, in the next PR. The JavaScript worker suspends today. The README states this.

Errors and termination

1. A failed vm.invoke raises its MicroVM error inside the handler. The handler can catch it and send another job to the same MicroVM.
2. A MicroVM error that the handler raises itself reaches the caller with its own class. Any other error stays the SDK's ChildContextError, as from run_in_child_context. This includes a MicroVM error that leaves a child context that the handler created, because that child context records ChildContextError as its error type. The caller then gets the MicroVM error's message, but not its class. JS behaves the same way for that nested case. JS differs for an SDK error that leaves the handler, such as the StepError of a failed step: JS passes it to the caller with its own class. This PR follows run_in_child_context, so the caller gets ChildContextError with the SDK error as its __cause__.
3. The session terminates the MicroVM after the handler returns, and after an error that ends the session.
4. It does not terminate for SuspendExecution, so a handler that waits keeps its MicroVM.
5. It does not terminate for a retryable InvocationError, such as RetryableSerDesError. Lambda runs the invocation again, and the handler replays on the same MicroVM. A terminate step recorded for it would take the position of the handler's next operation, and the replay would fail with NonDeterministicExecutionError.
6. It does not terminate for an ExecutionError, such as NonDeterministicExecutionError after a deploy that changes the handler. The core SDK lets that error leave a child context without a checkpoint, and the execution fails without a retry. A terminate step would add an operation to that history, or take the ID of an operation already in it. So the MicroVM runs until its maximum duration, as in JS.

The job wait in microvm() and in vm.invoke also passes an InvocationError or an ExecutionError through, instead of recording it as a job failure. JS does not have this gap, because its SDK ends the invocation with a promise that never settles.

Behavior change in microvm()

A non-retryable InvocationError during the job wait used to become MicrovmJobFailedError. It now becomes a plain MicrovmError, with the original message and error type. The job did not fail, so the new class is more accurate. A caller that catches only MicrovmJobFailedError no longer catches this case. A caller that catches MicrovmError still does. An ExecutionError during the job wait used to become MicrovmJobFailedError, and the operation terminated the MicroVM. It now passes through unchanged, and the execution fails with it.

Shared code

microvm() and the session share the launch, request, and terminate steps in _MicrovmScope. MicrovmBaseConfig holds the settings that MicrovmConfig and MicrovmSessionConfig share. MicrovmInvokeOptions extends MicrovmRequestConfig with the job's timeout and heartbeat_timeout. microvm() keeps its behavior, and its tests pass unchanged except two that patch the renamed launch method.

send_job gains two options for the session: window_started_at, so the state check and the request share one retry window, and recheck, for the state check after a gateway error. require_time_for_call runs before the state check, so a session job with less than 11 seconds left gets the message that names the function timeout.

Differences from JS

• A ResumeMicrovm answer of ResourceNotFoundException fails the job at once with MicrovmNotRunningError, as a GetMicrovm answer does. JS ignores only ConflictException at that call and rethrows every other error, so its job likely fails with a plain MicrovmDeliveryError. MicroVM session: record the resume mode at launch, map a removed MicroVM on resume aws-durable-execution-sdk-js#1006 proposes the Python behavior for JS.
• An SDK error that leaves the session handler reaches the caller as ChildContextError, as described above. JS passes it with its own class.
• A request step checks the time left before the state check, so a session job with less than 11 seconds left names the function timeout. JS does the same since fix(extras): name a short timeout, keep the MicroVM path aws-durable-execution-sdk-js#1005.

Not in this PR

• The worker's own suspend when idle, with the suspend and terminate hooks.
• Recording the resume mode in the launch checkpoint. Today it comes from the current config on each replay, as in JS. Both SDKs need the same checkpoint field, so MicroVM session: record the resume mode at launch, map a removed MicroVM on resume aws-durable-execution-sdk-js#1006 tracks it.
• No vm.suspend(ctx), because JS has none.
• Custom subtypes. The package records the SDK's default subtypes until the core SDK accepts custom ones.

Testing

• Package: 257 tests pass, with 100% line and branch coverage. mypy and ruff are clean.
• Repository: 4,960 tests pass. One worker test, test_answers_400_to_a_chunked_body_over_the_limit_that_the_client_sends, failed once in the full run with a 401, and passed 5 of 5 runs alone. This PR does not change the worker package.
• session_test.py runs sessions on the local test runner against a local HTTP endpoint: two jobs on one MicroVM, durable waits between jobs, map and parallel jobs, a caught and an uncaught job failure, the handler's own error, invalid jobs that the handler catches, config validation, the idle time sent to the worker, a resume and its new endpoint, the recheck after 502 and 503, a removed MicroVM, MicrovmNotRunningError on replay, terminate only after the handler ends, the retryable and non-retryable InvocationError paths, the outer context refused by vm.invoke, and a job error that leaves a child context of the handler.
• lifecycle_test.py covers ensure_running: each state, one resume with ConflictException ignored, a removed MicroVM at GetMicrovm and at ResumeMicrovm, the wait limit, and the invocation reserve.
• worker_composed_test.py runs two session jobs through the real Python worker. The second job reads the file that the first job wrote.
• A test checks the RunMicrovm request with an idle policy, GetMicrovm, and ResumeMicrovm against the botocore service model.
• Mutation checks: each of these changes makes a test fail: no recheck, no MicrovmNotRunningError mapping, a terminate for SuspendExecution, a terminate for a retryable InvocationError, every handler error turned into a MicroVM error, no not-found mapping at ResumeMicrovm, no outer-context check, and a terminate or a job failure for an ExecutionError in the handler or in either job wait.
• A sub-agent review found the retryable InvocationError defect before this PR opened. Its probe now ends SUCCEEDED, with one RunMicrovm and one TerminateMicrovm.
• Not run against the live service.

The branch merges main after #776, so the commit list shows the #776 commits. The diff against main has only this change.

[yaythomas]