feat(compute): add EC2 fleet compute strategy

[MichaelWalker-git]

Summary

• Add EC2 fleet compute strategy with SSM Run Command dispatch — a third compute backend alongside AgentCore (default) and ECS Fargate
• New Ec2ComputeStrategy handler: finds idle instances via tags, uploads payload to S3, dispatches via SSM AWS-RunShellScript, polls GetCommandInvocation, cancels with CancelCommand
• New Ec2AgentFleet CDK construct: Auto Scaling Group with launch template (AL2023 ARM64), security group (443 egress only), S3 payload bucket, IAM role with scoped permissions, Docker user data for pre-pulling images
• Wire orchestrator polling, cancel-task SSM dispatch, and task-api SSM permissions for EC2
• Stack wiring is commented-out (same pattern as ECS) — ready to enable per-repo via blueprint compute_type: 'ec2'
• Add instance_type field to RepoConfig and BlueprintConfig for future GPU/custom instance type support

Test plan

• mise //cdk:compile — no TypeScript errors
• mise //cdk:test — 43 suites, 697 tests all passing (including new ec2-strategy and ec2-agent-fleet tests)
• mise //cdk:synth — synthesizes without errors (EC2 block commented out)
• mise //cdk:build — full build including lint passes
• Deploy with EC2 block uncommented and run an end-to-end task with compute_type: 'ec2'

[Copilot]

Pull request overview

This PR adds a third compute backend (“ec2” fleet) alongside AgentCore and ECS, enabling task dispatch via SSM Run Command to tagged EC2 instances and adding the supporting CDK construct and runtime wiring.

Changes:

• Introduces Ec2ComputeStrategy (S3 payload upload + EC2 instance selection/tagging + SSM dispatch/poll/cancel).
• Adds Ec2AgentFleet CDK construct (ASG + instance role/SG + payload bucket + user data) and optional stack wiring.
• Extends config/types and handlers to support compute_type: 'ec2' and EC2 cancellation/polling.

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
yarn.lock	Locks new AWS SDK client dependencies used by EC2/SSM/S3 integration.
cdk/package.json	Adds @aws-sdk/client-ec2, client-ssm, client-s3 dependencies.
cdk/test/handlers/shared/strategies/ec2-strategy.test.ts	Unit tests for EC2 strategy start/poll/stop behavior.
cdk/test/handlers/shared/compute-strategy.test.ts	Ensures compute_type: ec2 resolves to Ec2ComputeStrategy.
cdk/test/constructs/ec2-agent-fleet.test.ts	Asserts key resources/permissions created by Ec2AgentFleet.
cdk/src/stacks/agent.ts	Adds commented wiring to enable EC2 fleet backend.
cdk/src/handlers/shared/strategies/ec2-strategy.ts	Implements EC2 fleet compute strategy via S3 + EC2 tags + SSM.
cdk/src/handlers/shared/repo-config.ts	Extends ComputeType to include ec2; adds instance_type.
cdk/src/handlers/shared/orchestrator.ts	Propagates instance_type into BlueprintConfig.
cdk/src/handlers/shared/compute-strategy.ts	Adds EC2 handle type + resolver case.
cdk/src/handlers/orchestrate-task.ts	Stores EC2 compute metadata and enables compute polling for EC2.
cdk/src/handlers/cancel-task.ts	Adds SSM CancelCommand support for EC2-backed tasks.
cdk/src/constructs/task-orchestrator.ts	Adds EC2 env vars and IAM policies for orchestrator Lambda.
cdk/src/constructs/task-api.ts	Adds ssm:CancelCommand permission option for cancel-task Lambda.
cdk/src/constructs/ec2-agent-fleet.ts	New ASG-based fleet construct with IAM/SG/S3/log group/user data.
cdk/src/constructs/blueprint.ts	Allows blueprint compute.type to be ec2.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[MichaelWalker-git]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[MichaelWalker-git]

End-to-End EC2 Compute Strategy Test Results

Deployed the stack with EC2 fleet enabled and ran a live test task against aws-samples/sample-autonomous-cloud-coding-agents using compute_type: 'ec2'.

Bugs Found and Fixed

1. Python module path (/app -> /app/src): The Docker image copies src/ to /app/src/, so entrypoint.py lives at /app/src/entrypoint.py. The boot script's sys.path.insert was pointing to /app, causing ModuleNotFoundError: No module named 'entrypoint'.

2. Missing GITHUB_TOKEN_SECRET_ARN: The ECS strategy passes this env var to the container so the agent can fetch the GitHub PAT from Secrets Manager. The EC2 strategy was missing it, causing ValueError: github_token is required. Fixed by extracting the ARN from blueprintConfig and passing it via docker run -e.

Test Task: 01KP78GJ6P8G559VH2VGW5CGNJ

Task:   "Add a CONTRIBUTORS.md file listing project contributors"
Repo:   aws-samples/sample-autonomous-cloud-coding-agents
Status: RUNNING (agent completed work, push failed due to PAT permissions on aws-samples org)

What worked end-to-end:

• Task submitted via CLI with compute_type: 'ec2' blueprint
• Orchestrator found idle EC2 instance, tagged it busy, dispatched SSM command
• SSM boot script: S3 payload download, ECR login, docker pull all succeeded
• Agent container started, resolved GitHub token from Secrets Manager
• Agent cloned repo, explored git history, created CONTRIBUTORS.md, committed locally
• Ran 11 turns, cost $0.16

What didn't work (not an infra issue):

• git push and gh pr create failed with Permission denied to MichaelWalker-git — the configured PAT doesn't have write access to the aws-samples org. This is a GitHub permissions issue, not an EC2 strategy bug.

SSM Command Output (key lines)

[00:26:40] TASK Repository: aws-samples/sample-autonomous-cloud-coding-agents
[00:26:40] TASK Model: us.anthropic.claude-sonnet-4-6
[00:26:40] CMD clone: gh repo clone aws-samples/sample-autonomous-cloud-coding-agents /workspace/...
[00:26:41] CMD clone: OK
[00:26:46] CMD mise-install: OK
[00:27:13] TOOL Write: /workspace/.../CONTRIBUTORS.md
[00:27:26] TOOL Bash: git add CONTRIBUTORS.md && git commit -m "..."
[00:27:26] RESULT [ok] 1 file changed, 17 insertions(+)
[00:27:28] TOOL Bash: git push ... 
[00:27:28] RESULT [ERROR] Permission denied to MichaelWalker-git

Conclusion

The EC2 compute strategy works end-to-end. The two bugs in this commit were the only blockers. Instance lifecycle (idle -> busy -> idle tagging) and cleanup trap both function correctly.

[krokoko]

@theagenticguy could you please have a look, I know you have a good understanding of what the devbox should look like

[krokoko]

Output from automated review:

Good points:

Positives

• Well-structured strategy pattern -- follows the existing ECS/AgentCore patterns consistently
• Strong unit tests for ec2-strategy -- race condition handling, all SSM status mappings, error resilience in stopSession, handle type guards
• Good CDK construct design -- proper cdk-nag suppressions, least-privilege SG (egress 443 only), S3 bucket with enforceSSL + blockPublicAccess + lifecycle
• S3 payload pattern eliminates most shell injection -- task data (prompt, repo URL, etc.) correctly flows through S3 JSON rather than shell interpolation
• Tag-then-verify with candidate loop is a reasonable approach for instance claiming with built-in retry

To address:

1. Shell injection via githubTokenSecretArn interpolated into bash script

File: cdk/src/handlers/shared/strategies/ec2-strategy.ts (boot script construction)

The value blueprintConfig.github_token_secret_arn is interpolated directly into single-quoted shell context:
export GITHUB_TOKEN_SECRET_ARN='${githubTokenSecretArn}',
This value is read from DynamoDB at runtime. If it ever contains a single quote (via a future admin API or direct DDB write), it breaks out of the quoting and enables arbitrary shell
execution on the EC2 instance. Other task data (prompt, repo URL) is correctly passed via S3 payload -- this field should follow the same pattern.

Fix: Pass githubTokenSecretArn through the S3 payload JSON instead of interpolating into shell, or validate the value to reject shell-unsafe characters.

2. Instance role ec2:CreateTags/ec2:DeleteTags allows cross-instance tag manipulation

File: cdk/src/constructs/ec2-agent-fleet.ts:174-182

The IAM policy grants ec2:CreateTags/ec2:DeleteTags with resources: ['*'] conditioned only on ec2:ResourceTag/bgagent:fleet. A compromised instance could:

• Modify tags on any fleet instance (steal tasks, set others to idle/busy)
• Add the bgagent:fleet tag to non-fleet resources and then manipulate those too
• Remove the fleet tag from other instances to deny service

Fix: Add aws:TagKeys condition to restrict modifiable tag keys to only bgagent:status and bgagent:task-id, preventing modification of bgagent:fleet itself.

3. Race condition in instance claiming is not atomic

File: cdk/src/handlers/shared/strategies/ec2-strategy.ts (startSession)

The tag-then-verify pattern for claiming idle instances has a TOCTOU gap. Two concurrent orchestrators could both tag the same instance within the EC2 API propagation window, both
verify successfully, and both dispatch SSM commands to the same instance. The verify step helps but isn't fully atomic.

Fix: Consider using a DynamoDB conditional write as an atomic claim mechanism, or document this as a known limitation with mitigations (e.g., boot script checks for existing
containers before starting).

---

High Severity Issues

4. Empty catch block in stopSession tag cleanup -- zero logging

File: cdk/src/handlers/shared/strategies/ec2-strategy.ts (stopSession, final try/catch)

} catch {
// Swallow — instance may already be terminated
}
This discards all errors (IAM failures, throttling, network issues) with no logging whatsoever. If cleanup fails for any non-termination reason, the instance is permanently stuck as
"busy" with no diagnostic trail.

Fix: Log at warn level with the error message.

5. Rollback catch blocks log the event but omit the actual error

File: cdk/src/handlers/shared/strategies/ec2-strategy.ts (startSession, two rollback catches)

Both SSM dispatch rollback and verify-claim rollback log "Failed to rollback..." but don't include the error object, making root cause diagnosis impossible.

Fix: Capture and include error: rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr) in both log calls.

6. Unknown SSM statuses silently treated as "running" in pollSession

File: cdk/src/handlers/shared/strategies/ec2-strategy.ts (pollSession default case)

If AWS adds a new terminal SSM status, the system reports the command as "running" indefinitely -- the task polls for up to 8.5 hours before timing out with no indication of the
actual failure.

Fix: Add a logger.warn in the default case logging the unknown status value.

7. Boot script path mismatch: /app/src vs /app

File: cdk/src/handlers/shared/strategies/ec2-strategy.ts (bootScript)

The EC2 boot script sets sys.path.insert(0, "/app/src") but the ECS strategy uses sys.path.insert(0, "/app"). If the Docker image has entrypoint.py at /app/entrypoint.py (matching
ECS), the EC2 strategy will fail at runtime.

Fix: Verify the correct path in the agent Dockerfile and make both strategies consistent.

---

Medium Severity Issues

8. instance_type field threaded through config but never consumed

repo-config.ts and orchestrator.ts add instance_type to BlueprintConfig, but Ec2ComputeStrategy.startSession never reads it. The ASG uses a hardcoded m7g.xlarge default. This is dead
code that creates a misleading API contract.

9. memoryId prop accepted by Ec2AgentFleet but never used

The construct accepts memoryId?: string but never references it in the constructor body (unlike EcsAgentCluster which passes it as a container env var).

10. ec2FleetConfig typed as Record<string, never> -- confusing

In task-api.ts, this type carries no data -- it's just a truthy flag. Either use boolean for clarity or pass fleet identifiers for IAM scoping.

11. ssm:CancelCommand granted with resources: ['*'] without documentation

In task-api.ts, the cancel Lambda gets blanket SSM permissions with no comment explaining the API limitation (SSM doesn't support resource-level restrictions for CancelCommand). Add a
NagSuppression or inline comment.

12. Orchestrator NagSuppression reason not updated for new EC2/SSM wildcard policies

The AwsSolutions-IAM5 reason string in task-orchestrator.ts still only mentions ECS and iam:PassRole -- doesn't cover the new EC2, SSM, or S3 statements.

13. UserData boot failures silently reduce fleet capacity

If docker pull or ECR login fails, the instance never gets tagged as idle, sits in the ASG as "healthy" but unreachable for tasks. No error reporting mechanism exists.

Fix: Add a trap handler that tags the instance as bgagent:status=boot-failed on ERR

Test coverage gaps:

Test Coverage Gaps

┌──────────┬────────────────────────────────────────────────────────────────────────────────────────┬───────────────────────────────────────────────┐
│ Priority │ Gap │ File to Update │
├──────────┼────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
│ 9/10 │ No tests for cancel-task.ts EC2 branch -- 4 scenarios untested │ cdk/test/handlers/cancel-task.test.ts │
├──────────┼────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
│ 8/10 │ No task-orchestrator construct tests for EC2 config -- env vars and IAM policies │ cdk/test/constructs/task-orchestrator.test.ts │
├──────────┼────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
│ 7/10 │ S3 bucket security properties (enforceSSL, blockPublicAccess, encryption) not asserted │ cdk/test/constructs/ec2-agent-fleet.test.ts │
├──────────┼────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
│ 7/10 │ orchestrate-task.ts EC2 compute metadata mapping untested │ cdk/test/handlers/orchestrate-task.test.ts │
├──────────┼────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
│ 6/10 │ S3 upload failure and verify-describe failure rollback paths │ ec2-strategy.test.ts │
├──────────┼────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
│ 5/10 │ No assertion that security group has zero ingress rules │ ec2-agent-fleet.test.ts │
└──────────┴────────────────────────────────────────────────────────────────────────────────────────┴───────────────────────────────────────────────┘