aws-samples / aws-samples/sample-autonomous-cloud-coding-agents

(compute): operator access to active agent sessions for debugging

Open
#391 0 comments 0 reactions 0 assignees View on GitHub
enhancement infra-cdk orchestration
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.