cloudflare / cloudflare/agents

[Think] Add client projection hooks for server-only message context

Open
#1,966 1 comment 0 reactions 1 assignee Claimed by @threepointone View on GitHub
enhancement think
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

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.