cloudflare / cloudflare/agents
[Think] Add client projection hooks for server-only message context
- Dominant language
- TypeScript
- Stars
- 5.6k
- Forks
- 711
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 53
Description
## Problem
Think Session is the canonical history used for model execution, tools, compaction, and recovery. Applications may need to persist server-owned, model-visible context with a turn, such as retrieval snapshots, system reminders, or internal tool details, without exposing it to browser clients.
Today, Think uses the same `this.messages` view for model assembly and client synchronization. Persisting internal parts therefore risks exposing them through broadcasts, `/get-messages`, reconnects, rollback, or resumable replay. `beforeTurn` is too late to persist context, while Agent lifecycle hooks do not cover every client output path. This forces applications to either split conversation state into sidecars or replace the built-in browser transport.
## Proposal
Please consider stable hooks such as:
```ts
prepareMessageForSession(message, context): SessionMessage
projectMessagesForClient(messages, context): UIMessage[]
projectStreamChunkForClient(chunk, context): UIMessageChunk | null
```
The exact API may differ, but the important guarantees are:
- server-only fields are created or validated before Session persistence;
- model execution, compaction, and recovery use the complete canonical history;
- every client-facing history, broadcast, reconnect, rollback, and replay path uses the client projection;
- stream projection preserves complete tool-call lifecycles and terminal events;
- clients cannot mark their own content as trusted/internal.
## Why
A single canonical Session transcript should be able to support different audiences without requiring application-level transcript joins or a second chat protocol. This would provide one extensible boundary for retrieval snapshots, reminders, private server tools, and future model-only context.
Observed with `@cloudflare/think@0.13.0` and `agents@0.17.3`.
(co-authored by gpt-5.6-sol)
Contributor guide
Assessment
This issue has not been assessed yet.