feat(think): add per-turn chat metadata

[cjol]

This PR adds ChatOptions.metadata to @cloudflare/think as a server-written, per-turn metadata carrier that persists on the turn's user message and can be read through Think.activeTurnMetadata. Fixes #1915.

Why

• Messenger and RPC turns can be initiated by different authenticated principals in the same session or thread, and tool access, audit, and RBAC need identity for the current turn.
• Agent-wide state is unsafe for this because overlapping turns can race and attribute work to the wrong user.
• submitMessages({ metadata }) carries immutable per-submission metadata, but it uses the submission delivery path, so chat surfaces lose incremental streaming.
• The existing channel stamp already has the right trust model: server-written, persisted on the user message, and re-resolved during recovery. This extends that model instead of adding transient turn state or trusting client-supplied metadata.

Public API Surface

Symbol	Kind	Notes
ChatOptions.metadata	Option	Additive server-side per-turn metadata for chat() and chatWithMessengerContext() callers.
Think.activeTurnMetadata	Getter	Additive turn-scoped reader that resolves the stamped metadata from durable message history.

Architectural Changes

Before:

chat({ channel })
  -> stamp metadata.channel on user message
  -> activeChannel re-resolves from durable history

After:

chat({ channel, metadata })
  -> stamp metadata.channel and metadata.turnMetadata on user message
  -> activeChannel and activeTurnMetadata re-resolve from durable history

client-supplied message intake
  -> strips reserved server-written keys: channel, turnMetadata

Code Changes

• packages/think/src/think.ts adds ChatOptions.metadata, stamps it as metadata.turnMetadata, and exposes it through activeTurnMetadata.
• Client-supplied messages now have reserved server-written metadata keys stripped at intake, so clients cannot forge channel or turnMetadata while other metadata is preserved.
• The Think test agent records activeTurnMetadata during turns and exposes helpers for recovery and intake tests.
• A changeset marks @cloudflare/think for a minor release.

Compatibility

• ChatOptions.metadata and Think.activeTurnMetadata are additive.
• Client-supplied message metadata keys named channel or turnMetadata are now stripped before persistence. Other client metadata keys are preserved.

---

[changeset-bot]

🦋 Changeset detected

Latest commit: 04da1b4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@cloudflare/think	Minor
@cloudflare/agent-think	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@1921

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@1921

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@1921

create-think

npm i https://pkg.pr.new/create-think@1921

hono-agents

npm i https://pkg.pr.new/hono-agents@1921

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@1921

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@1921

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@1921

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@1921

commit: 04da1b4