aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
(compute): operator access to active agent sessions for debugging
- Dominant language
- TypeScript
- Stars
- 143
- Forks
- 46
- Avg merge
- 3d 9h
- Merged PRs (30d)
- 20
Description
## Component
API or orchestration
## Describe the feature
When a task is running or has failed without reaching a clean terminal state, authorized operators should be able to inspect—and optionally interact with—the same compute session the agent used, instead of relying only on log streams, S3 traces, and re-submission.
Capabilities should be tiered: read-only access to session logs and filesystem snapshots first; optional interactive access (shell or attach) behind stricter IAM, Cedar, and audit requirements. All access must be attributable, time-bounded, and revocable when the task is cancelled or completes.
## Use case
I'm always frustrated when debugging a failed agent run requires reproducing the repo state locally or burning another full task attempt blindly. Platform teams need to answer "what did the agent see?" and "why did install/test fail in the sandbox?" quickly. Interactive takeover also builds operator trust during rollout: humans-B can verify environment setup before widening autonomy for a repo.
## Proposed solution
1. **Read path (phase 1)** — API/CLI to list session artifacts: recent stdout/stderr excerpts, progress events, optional read-only file listing or tarball export from `/mnt/workspace` while session is alive or within a short post-terminal retention window.
2. **Pause / hold (phase 1.5)** — Optional operator-initiated pause that stops agent turns but preserves session storage (where compute backend supports stop/resume) for inspection before timeout.
3. **Interactive attach (phase 2)** — Secure break-glass shell or SSM-style session into the MicroVM/ECS task, gated by admin role, per-repo Blueprint flag, and immutable audit events (`operator_session_started`, `operator_session_ended`).
4. **Authorization** — Restrict to task owner plus platform operators; integrate with future principal-to-repo authorization.
5. **Compute backend abstraction** — Implement via `ComputeStrategy` hooks (AgentCore session APIs, ECS exec) with feature matrix documented in `COMPUTE.md`.
## Acceptance criteria
- [ ] Operators with documented IAM/API role can fetch session debug bundle for a `RUNNING` or recently `FAILED` task via CLI or API.
- [ ] All operator access emits audit events on `TaskEvents` with actor identity and action type.
- [ ] Interactive attach (if shipped) is opt-in per Blueprint, time-limited, and disabled by default.
- [ ] Cancelling a task terminates operator access paths within documented bounds.
- [ ] User guide covers supported backends, retention windows, and security expectations.
## Other information
- Related roadmap: **Control panel**, **Emergency session containment**, **Interactive task UX**.
- Related design: `docs/design/COMPUTE.md`, `docs/design/INTERACTIVE_AGENTS.md`, `docs/design/SECURITY.md`.
- AgentCore already exposes persistent session storage at `/mnt/workspace` and stop/resume semantics—leverage rather than reinvent.
- Alternatives considered: trace-only debugging (insufficient for env misconfiguration); always-on SSH per session (too broad an attack surface).
## Acknowledgements
- [ ] I may be able to implement this feature
- [ ] This might be a breaking change
Contributor guide
Research direction
Start with docs/design/COMPUTE.md, docs/design/INTERACTIVE_AGENTS.md, and docs/design/SECURITY.md, then trace the existing ComputeStrategy hooks and TaskEvents path. Compare the supported backend capabilities and existing CLI/API entry points against the phased acceptance criteria. Done means documented, authorized debug access with audit events, bounded retention and cancellation behavior, plus opt-in interactive attach if implemented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, typescript
- Domain
- backend-api-design, cloud, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100