Add sandbox lifecycle events API with webhook delivery for orchestration

[Puneet-Pal-Singh]

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+.

[vmsp]

Maybe I'm missing something but can't you just subclass Sandbox and override whichever lifecycle methods you want? E.g.

export class AppSandbox extends Sandbox {
  override onStop(): Promise<void> {
    // ...
    return super.onStop();
  }
}

I haven't tried it but I don't see why it wouldn't work.