Each session can have its own terminal with an isolated working directory and environment, so users can run separate shells side-by-side in the same container.
JavaScript
// Multiple isolated terminals in the same sandbox
constdev=awaitsandbox.getSession("dev");
returndev.terminal(request);
TypeScript
// Multiple isolated terminals in the same sandbox
constdev=awaitsandbox.getSession("dev");
returndev.terminal(request);
xterm.js addon
The new @cloudflare/sandbox/xterm export provides a SandboxAddon for xterm.js with automatic reconnection (exponential backoff + jitter), buffered output replay, and resize forwarding.
JavaScript
import {SandboxAddon} from "@cloudflare/sandbox/xterm";
constaddon=newSandboxAddon({
getWebSocketUrl:({sandboxId,origin})=>
`${origin}/ws/terminal?id=${sandboxId}`,
onStateChange:(state,error)=>updateUI(state),
});
terminal.loadAddon(addon);
addon.connect({ sandboxId:"my-sandbox"});
TypeScript
import {SandboxAddon} from "@cloudflare/sandbox/xterm";
Get your content updates into AI Search faster and avoid a full rescan when you do not need it.
Reindex individual files without a full sync
Updated a file or need to retry one that errored? When you know exactly which file changed, you can now reindex it directly instead of rescanning your entire data source.
Go to Overview > Indexed Items and select the sync icon next to any file to reindex it immediately.
Crawl only the sitemap you need
By default, AI Search crawls all sitemaps listed in your robots.txt, up to the maximum files per index limit. If your site has multiple sitemaps but you only want to index a specific set, you can now specify a single sitemap URL to limit what the crawler visits.
For example, if your robots.txt lists both blog-sitemap.xml and docs-sitemap.xml, you can specify just https://example.com/docs-sitemap.xml to index only your documentation.
Configure your selection anytime in Settings > Parsing options > Specific sitemaps, then trigger a sync to apply the changes.
The latest release of the Agents SDK brings readonly connections, MCP protocol and security improvements, x402 payment protocol v2 migration, and the ability to customize OAuth for MCP server connections.
Readonly connections
Agents can now restrict WebSocket clients to read-only access, preventing them from modifying agent state. This is useful for dashboards, spectator views, or any scenario where clients should observe but not mutate.
New hooks: shouldConnectionBeReadonly, setConnectionReadonly, isConnectionReadonly. Readonly connections block both client-side setState() and mutating @callable() methods, and the readonly flag survives hibernation.
JavaScript
classMyAgentextendsAgent{
shouldConnectionBeReadonly(connection){
// Make spectators readonly
returnconnection.url.includes("spectator");
}
}
TypeScript
classMyAgentextendsAgent{
shouldConnectionBeReadonly(connection){
// Make spectators readonly
returnconnection.url.includes("spectator");
}
}
Custom MCP OAuth providers
The new createMcpOAuthProvider method on the Agent class allows subclasses to override the default OAuth provider used when connecting to MCP servers. This enables custom authentication strategies such as pre-registered client credentials or mTLS, beyond the built-in dynamic client registration.
Upgraded the MCP SDK to 1.26.0 to prevent cross-client response leakage. Stateless MCP Servers should now create a new McpServer instance per request instead of sharing a single instance. A guard is added in this version of the MCP SDK which will prevent connection to a Server instance that has already been connected to a transport. Developers will need to modify their code if they declare their McpServer instance as a global variable.
MCP OAuth callback URL security fix
Added callbackPath option to addMcpServer to prevent instance name leakage in MCP OAuth callback URLs. When sendIdentityOnConnect is false, callbackPath is now required — the default callback URL would expose the instance name, undermining the security intent. Also fixes callback request detection to match via the state parameter instead of a loose /callback URL substring check, enabling custom callback paths.
Deprecate onStateUpdate in favor of onStateChanged
onStateChanged is a drop-in rename of onStateUpdate (same signature, same behavior). onStateUpdate still works but emits a one-time console warning per class. validateStateChange rejections now propagate a CF_AGENT_STATE_ERROR message back to the client.
x402 v2 migration
Migrated the x402 MCP payment integration from the legacy x402 package to @x402/core and @x402/evm v2.
Breaking changes for x402 users:
Peer dependencies changed: replace x402 with @x402/core and @x402/evm
PaymentRequirements type now uses v2 fields (e.g. amount instead of maxAmountRequired)
X402ClientConfig.account type changed from viem.Account to ClientEvmSigner (structurally compatible with privateKeyToAccount())
npmuninstallx402
npminstall@x402/core@x402/evm
Network identifiers now accept both legacy names and CAIP-2 format:
// Legacy name (auto-converted)
{
network:"base-sepolia",
}
// CAIP-2 format (preferred)
{
network:"eip155:84532",
}
Other x402 changes:
X402ClientConfig.network is now optional — the client auto-selects from available payment requirements
Server-side lazy initialization: facilitator connection is deferred until the first paid tool invocation
Payment tokens support both v2 (PAYMENT-SIGNATURE) and v1 (X-PAYMENT) HTTP headers
Added normalizeNetwork export for converting legacy network names to CAIP-2 format
Re-exports PaymentRequirements, PaymentRequired, Network, FacilitatorConfig, and ClientEvmSigner from agents/x402
Other improvements
Fix useAgent and AgentClient crashing when using basePath routing
CORS handling delegated to partyserver’s native support (simpler, more reliable)
Client-side onStateUpdateError callback for handling rejected state updates
Each session can have its own terminal with an isolated working directory and environment, so users can run separate shells side-by-side in the same container.
JavaScript
// Multiple isolated terminals in the same sandbox
constdev=awaitsandbox.getSession("dev");
returndev.terminal(request);
TypeScript
// Multiple isolated terminals in the same sandbox
constdev=awaitsandbox.getSession("dev");
returndev.terminal(request);
xterm.js addon
The new @cloudflare/sandbox/xterm export provides a SandboxAddon for xterm.js with automatic reconnection (exponential backoff + jitter), buffered output replay, and resize forwarding.
JavaScript
import {SandboxAddon} from "@cloudflare/sandbox/xterm";
constaddon=newSandboxAddon({
getWebSocketUrl:({sandboxId,origin})=>
`${origin}/ws/terminal?id=${sandboxId}`,
onStateChange:(state,error)=>updateUI(state),
});
terminal.loadAddon(addon);
addon.connect({ sandboxId:"my-sandbox"});
TypeScript
import {SandboxAddon} from "@cloudflare/sandbox/xterm";
Get your content updates into AI Search faster and avoid a full rescan when you do not need it.
Reindex individual files without a full sync
Updated a file or need to retry one that errored? When you know exactly which file changed, you can now reindex it directly instead of rescanning your entire data source.
Go to Overview > Indexed Items and select the sync icon next to any file to reindex it immediately.
Crawl only the sitemap you need
By default, AI Search crawls all sitemaps listed in your robots.txt, up to the maximum files per index limit. If your site has multiple sitemaps but you only want to index a specific set, you can now specify a single sitemap URL to limit what the crawler visits.
For example, if your robots.txt lists both blog-sitemap.xml and docs-sitemap.xml, you can specify just https://example.com/docs-sitemap.xml to index only your documentation.
Configure your selection anytime in Settings > Parsing options > Specific sitemaps, then trigger a sync to apply the changes.
The Workers Observability dashboard has some major updates to make it easier to debug your application’s issues and share findings with your team.
You can now:
Create visualizations — Build charts from your Worker data directly in a Worker’s Observability tab
Export data as JSON or CSV — Download logs and traces for offline analysis or to share with teammates
Share events and traces — Generate direct URLs to specific events, invocations, and traces that open standalone pages with full context
Customize table columns — Improved field picker to add, remove, and reorder columns in the events table
Expandable event details — Expand events inline to view full details without leaving the table
Keyboard shortcuts — Navigate the dashboard with hotkey support
These updates are now live in the Cloudflare dashboard, both in a Worker’s Observability tab and in the account-level Observability dashboard for a unified experience. To get started, go to Workers & Pages > select your Worker > Observability.
The Workers Observability dashboard has some major updates to make it easier to debug your application’s issues and share findings with your team.
You can now:
Create visualizations — Build charts from your Worker data directly in a Worker’s Observability tab
Export data as JSON or CSV — Download logs and traces for offline analysis or to share with teammates
Share events and traces — Generate direct URLs to specific events, invocations, and traces that open standalone pages with full context
Customize table columns — Improved field picker to add, remove, and reorder columns in the events table
Expandable event details — Expand events inline to view full details without leaving the table
Keyboard shortcuts — Navigate the dashboard with hotkey support
These updates are now live in the Cloudflare dashboard, both in a Worker’s Observability tab and in the account-level Observability dashboard for a unified experience. To get started, go to Workers & Pages > select your Worker > Observability.
Cloudflare Workflows now automatically generates visual diagrams from your code
Your Workflow is parsed to provide a visual map of the Workflow structure, allowing you to:
Understand how steps connect and execute
Visualize loops and nested logic
Follow branching paths for conditional logic
You can collapse loops and nested logic to see the high-level flow, or expand them to see every step.
Workflow diagrams are available in beta for all JavaScript and TypeScript Workflows. Find your Workflows in the Cloudflare dashboard to see their diagrams.
Cloudflare Queues is now part of the Workers free plan, offering guaranteed message delivery across up to 10,000 queues to either Cloudflare Workers or HTTP pull consumers. Every Cloudflare account now includes 10,000 operations per day across reads, writes, and deletes. For more details on how each operation is defined, refer to Queues pricing.
All features of the existing Queues functionality are available on the free plan, including unlimited event subscriptions. Note that the maximum retention period on the free tier, however, is 24 hours rather than 14 days.
If you are new to Cloudflare Queues, follow this guide or try one of our tutorials to get started.
Cloudflare Workflows now automatically generates visual diagrams from your code
Your Workflow is parsed to provide a visual map of the Workflow structure, allowing you to:
Understand how steps connect and execute
Visualize loops and nested logic
Follow branching paths for conditional logic
You can collapse loops and nested logic to see the high-level flow, or expand them to see every step.
Workflow diagrams are available in beta for all JavaScript and TypeScript Workflows. Find your Workflows in the Cloudflare dashboard to see their diagrams.
