cloudflare / cloudflare/sandbox-sdk

Add sandbox lifecycle events API with webhook delivery for orchestration

Open
#477 1 comment 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
TypeScript
Stars
1.1k
Forks
114
Avg merge
22h 42m
Merged PRs (30d)
14

Description

## Why

I am building a multi-agent orchestrator/ADE on top of the Cloudflare stack (`@cloudflare/sandbox` + Agents SDK). Right now lifecycle transitions are inferred by polling and side effects, which adds latency and creates race conditions around start/stop/destroy transitions.

Sandbox already has internal lifecycle hook points (`onStart`, `onStop`, `destroy` in `packages/sandbox/src/sandbox.ts`), so this proposal makes those transitions available as a stable public event contract.

## Proposal

Phase 1 (MVP): add a first-class lifecycle event API in SDK/DO.

- Event types: `sandbox.started`, `sandbox.stopped`, `sandbox.destroyed`.
- Each event includes `eventId`, `eventType`, `sandboxId`, `timestamp`, optional `traceId`, and optional event-specific `data`.
- Add `sandbox.listLifecycleEvents(options)` with cursor + limit + optional type filter, so orchestrators can consume events without polling internal state.

Phase 2: add outbound webhook delivery on top of the same event source.

## Semantics and scope

- Delivery semantics: at-least-once, best-effort ordering
- Consumers dedupe using `eventId`
- Non-goals: exactly-once guarantees and global strict ordering
- Backward compatibility: additive only
- Out of scope for initial implementation: webhook management UI and a large integrations framework.

## Maintainer feedback requested

1. Should `sandbox.stopped` represent only DO stop, or any container sleep transition?
2. Is event journal + list API the preferred first release shape?
3. Should webhook delivery live in core repo (phase 2) or example/integration package first?

## Proposed delivery plan

- [ ] PR1: shared lifecycle event types + emission from lifecycle hooks + unit tests
- [ ] PR2: paginated event listing API + tests
- [ ] PR3: webhook adapter with signature, retries, and idempotency
- [ ] PR4: docs + example consumer

Planned sequence: PR1 establishes the lifecycle event contract. PR2 adds the paginated listing API. PR3+ (including webhook delivery) builds on that contract after maintainer sign-off on PR1 semantics.

If this direction looks good, I’ll start with PR1 (event contract + emission + tests) and follow with PR2+.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.