Readonly state

[agents-git-bot]

Summary

Sync documentation for cloudflare/agents PR #610: Readonly state

This PR adds comprehensive documentation for the new readonly connections feature, which allows restricting certain WebSocket connections from modifying agent state while still allowing them to receive state updates and call RPC methods.

Changes

• Added src/content/docs/agents/api-reference/readonly-connections.mdx
• Documented server-side methods: shouldConnectionBeReadonly(), setConnectionReadonly(), isConnectionReadonly()
• Documented client-side API: onStateUpdateError callback
• Included usage examples for query parameters, RBAC, admin dashboards, and dynamic permissions
• Explained behavior details including state synchronization and connection cleanup
• Provided best practices for authentication, user feedback, and permission checks
• Added migration guide for existing agents

Source

• Source Repository: cloudflare/agents
• Source PR: feat: readonly connections — restrict WebSocket clients from modifying agent state agents#610
• Source PR Title: Readonly state

Test plan

• Review documentation for accuracy and completeness
• Verify all code examples are syntactically correct
• Ensure links and references are properly formatted
• Confirm adherence to Cloudflare docs style guide

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/src/content/docs/agents/	@irvinebroque, @rita3ko, @elithrar, @thomasgauvin, @threepointone, @whoiskatrin, @cloudflare/pcx-technical-writing, @cloudflare/ai-agents, @cloudflare/dev-plat-leads

[elithrar]

/bonk review and address the build issues

[ask-bonk]

Summary

The CI build failed with:

Adjacent JSX elements must be wrapped in an enclosing tag. Did you want a JSX fragment <>...</>? (74:5)

Root cause: The "Dynamic permission changes" example at readonly-connections.mdx:252-331 had a single TypeScriptExample code block containing both a TypeScript class (GameAgent with @callable() decorators and Agent<Env, GameState> generics) and a React component (GameComponent with JSX). The TypeScriptExample component strips TypeScript types using ts-blank-space then formats with prettier's babel parser. When the generics were stripped and the decorator syntax combined with JSX in the same code unit, prettier's parser failed to correctly parse the resulting JavaScript.

Fix: Split the single code block into two separate TypeScriptExample blocks:

1. Server-side GameAgent class (```ts) - no JSX, decorators + generics only
2. Client-side GameComponent function (```tsx) - JSX only, no decorators or generics

This follows the same pattern used elsewhere in the agents docs (e.g., routing.mdx uses tsx for JSX examples, client-sdk.mdx keeps JSX examples simple and separate).

github run

[elithrar]

/bonk still failing. Investigate the build issues and run astro check to make sure the touched file is still valid

[ask-bonk]

Summary

The build was failing because two JSX code blocks were wrapped in <TypeScriptExample>, which processes code through ts-blank-space + Prettier's babel parser. This pipeline doesn't support JSX:

Root cause: ts-blank-space treats JSX syntax as TypeScript constructs:

• <div> → interpreted as a generic type comparison, blanked out entirely
• as Player in "Join as Player" → interpreted as as type assertion, blanked out
• !canEdit → interpreted as non-null assertion operator, blanked out

Two blocks fixed in readonly-connections.mdx:

1. GameComponent (was line ~294): The <div> tag being blanked caused Prettier to see adjacent closing JSX elements without matching openers → build-breaking parse error
2. EditButton (was line ~418): disabled={!canEdit} silently became disabled={ canEdit} in the JavaScript tab — semantically wrong (inverted logic)

Fix: Removed the <TypeScriptExample> wrapper from both blocks, using plain ```tsx fenced code blocks instead. This follows the same pattern used in getting-started/quick-start.mdx and guides/webhooks.mdx for React component examples.

Validation:

• astro check: 0 errors, 0 warnings
• All 12 remaining <TypeScriptExample> blocks verified through the ts-blank-space + Prettier pipeline

github run

[github-actions]

Preview URL: https://dc21af5f.preview.developers.cloudflare.com
Preview Branch URL: https://sync-docs-pr-610.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/agents/api-reference/readonly-connections/	https://sync-docs-pr-610.preview.developers.cloudflare.com/agents/api-reference/readonly-connections/