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

RFC: Checkpoint rewind and fork for off-track tasks

Aperta
#564 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
agent-runtime observability orchestration RFC-proposal
Lingua principale
TypeScript
Stelle
143
Fork
46
Merge medio
3g 10h
PR unite (30g)
24

Descrizione

## Primary area

Cross-cutting / multiple

## Related issue or feature request

- [WORKFLOWS.md](https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/blob/main/docs/design/WORKFLOWS.md) — `workflow_state.json` checkpoints
- #252 (step-aware event supersede on orchestrator replay — distinct concern)
- #484 (S3-backed SDK session store — recommended before v1)
- #560 (workflow commit trailers — git lineage)

## Summary

Expose **operator-driven rewind and fork** for workflow execution: resume a terminal or failed task from an earlier completed step without full cold-start, or branch a new task from a checkpoint to explore an alternate approach.

```bash
bgagent rewind --list
bgagent rewind --to implement
bgagent fork --to plan
```

## Use case and motivation

When an agent goes off-track late in a workflow, operators re-submit tasks or manually check out branches — losing checkpoint context and burning cold-start cost. Rewind reduces waste; fork supports A/B exploration under audit.

Distinct from #252, which fixes **duplicate progress events** when the orchestrator replays durable steps — not operator-initiated rewind to an earlier workflow step.

## Proposal

1. Extend `workflow_state.json` (and TaskRecord metadata) with ordered checkpoint entries: `step_name`, `step_kind`, `sdk_session_id`, `git_commit_sha`, artifact pointers.
2. **Rewind:** new task pinned to checkpoint; skip completed deterministic steps; re-enter agent at selected step; `rewound_from` lineage.
3. **Fork:** same without archiving source; `forked_from` lineage.
4. CLI commands + orchestrator create-task path.

## Out of scope

- Automatic rewind on verify failure (#457)
- Per-step orchestrator durable checkpoints (agent-side only per ADR-014)
- Compensation/rollback of side effects (e.g. unpublish PR)

## Potential challenges

- Session resume without #484 may restart agent at turn 0 even if steps are skipped.
- `ensure_pr` / `deliver_artifact` idempotency on re-entry.
- Admission limits for new RUNNING tasks.

---

**Note:** Non-triaged RFCs may not get timely review. PRs on non-triaged issues might not be accepted.

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Inizia leggendo docs/design/WORKFLOWS.md e il modello dei checkpoint workflow_state.json, quindi traccia i comandi CLI e il percorso create-task dell’orchestrator menzionati nella proposta. Confronta il design con ADR-014 e le issue correlate #252, #484 e #560; il lavoro sarebbe completo quando sarà disponibile un design concordato che copra i metadati dei checkpoint, la lineage di rewind/fork, la gestione delle sessioni, l’idempotenza e i limiti di ammissione.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
aws, git, typescript
Ambito
backend, cli, distributed-systems
Tipo di issue
Funzionalità
Difficoltà
5/5
Tempo stimato
Più di una settimana
Stato di attività
Tranquilla
Chiarezza
Abbastanza chiara
Idoneità per principianti
35/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.