AIChatAgent cleanup is per-DO and only triggered on local stream completion, which can leave cf_ai_chat_stream_* rows indefinitely for inactive DO instances

[duz52]

Hi Cloudflare Agents team,

First of all, thank you for @cloudflare/agents and @cloudflare/ai-chat — they’ve been really helpful for building resumable streaming on Workers.

I am using AIChatAgent with a common pattern: one Durable Object instance per chat (e.g. DO name = chatId). While reviewing storage growth, I noticed the built-in cleanup logic runs inside _completeStream() via _maybeCleanupOldStreams().

From the current implementation, cleanup is:

• Triggered only when a stream completes in the same DO instance
• Throttled by CLEANUP_INTERVAL_MS (10 minutes)
• Deletes only status = 'completed' streams older than CLEANUP_AGE_THRESHOLD_MS (24 hours)
• Targets cf_ai_chat_stream_chunks and cf_ai_chat_stream_metadata

This seems to imply the following behavior:
If a given DO instance (chatId) becomes inactive after a single conversation (i.e. no more stream completions happen in that DO), then its SQLite tables (cf_ai_chat_stream_chunks, cf_ai_chat_stream_metadata) may never be cleaned up, because _maybeCleanupOldStreams() will not be called again for that DO.

In our app, we persist final messages to Postgres as the source of truth, so we don’t need the DO to retain completed stream chunks long-term. We currently override _completeStream() to delete that stream’s chunks/metadata immediately to keep DO storage bounded, but we’re not sure if that’s the recommended approach.

Questions / request for guidance:

1. Is this “cleanup only on local completion” behavior intended / expected?
2. Are there recommended best practices for bounding DO storage in this pattern (one DO per chat)?
3. Would you consider supporting one of the following:
   • A public method/API to trigger cleanup explicitly (useful for cron/admin jobs)
   • A configurable retention policy / TTL for completed streams (e.g. minutes instead of 24h)
   • An option to eagerly delete completed stream chunks when the app persists messages elsewhere

[aniruddhaadak80]

This does look like a lifecycle mismatch in the current cleanup model. If retention cleanup only runs when the same Durable Object later completes another stream, then one-chat-per-DO deployments will naturally accumulate old rows even when the application no longer needs them.nnAn explicit cleanup hook or configurable retention policy would make a lot of sense here. Otherwise users end up overriding internal methods just to keep storage bounded, which is usually a sign the public abstraction is missing one important control.

[spinsirr]

The implementation has changed since this report. On current main, AIChatAgent delegates stream storage to ResumableStream; the old completion-triggered, 24-hour cleanup isn't the current lifecycle.

Normal message persistence now settles the stream and drops its buffer rows in the same transaction. Remaining terminal streams are reclaimed on the next stream start. The adapter also includes migration of the legacy cf_ai_chat_stream_* tables.

Sources:

• AIChatAgent persistence/cutover (search for #pendingCutover)
• ResumableStream lifecycle and legacy migration

I would check your installed agents and @cloudflare/ai-chat versions against this implementation before maintaining the _completeStream() override. These links describe main, not a verified minimum published release, and they don't establish that already-inactive DOs have been migrated. Could you share the versions you're currently running?