Invalidate query cache on disconnect to fix stale auth tokens (#28084)

* Document async query cache invalidation on reconnect in useAgent

Updates documentation to reflect that useAgent automatically invalidates
the query cache when the WebSocket connection closes. This ensures that
async query functions (e.g., for fetching auth tokens) are re-executed
on reconnect, providing fresh tokens after network interruptions.

Changes:
- Added missing query, queryDeps, cacheTtl, and other parameters to UseAgentOptions type
- Added dedicated section on authentication with async query functions
- Added client-side authentication example in calling-agents.mdx
- Documented automatic token refresh behavior on reconnection

Related to cloudflare/agents#839

* Add complete useAgent return type documentation

Extends the useAgent return type documentation to include:
- agent: The agent class name in kebab-case
- name: The agent instance name
- identified: Whether agent identity has been received
- ready: Promise that resolves when identity is received
- call: Method for calling Agent methods with RPC
- stub: Stub object for direct Agent method calls

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* Document query cache invalidation on disconnect for useAgent hook

Documents the cache invalidation behavior when WebSocket connections close,
ensuring users understand that async query functions are re-executed on reconnect.

This change corresponds to PR #839 in cloudflare/agents which fixes stale
auth token issues by invalidating the query cache on disconnect.

Adds documentation for:
- Using static and async query parameters for authentication
- Cache invalidation behavior on connection close
- cacheTtl option for controlling cache duration

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* Fix merge conflict resolution: restore cache invalidation docs

The merge conflict resolution discarded all meaningful content from this
PR because agents-api.mdx was completely rewritten on production (from
1143 lines to 211 lines) after this PR was created.

Most of the PR's intended content (UseAgentOptions type, async query
params, useAgent return type) already exists in the new client-sdk.mdx.
The one missing piece was the disconnect cache invalidation behavior
(the core feature from cloudflare/agents#839).

Changes:
- Revert whitespace-only changes to agents-api.mdx
- Add disconnect cache invalidation documentation to client-sdk.mdx
- Document that async query cache is invalidated on WebSocket close
- Update reconnection best practice to mention token refresh

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-authored-by: Matt Silverlock <matt@eatsleeprepeat.net>
Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com>

Author: 5 people

src/content/docs/agents/api-reference/client-sdk.mdx

@@ -174,8 +174,15 @@ The query function is cached and only re-called when:
 
 - `queryDeps` change
 - `cacheTtl` expires
+- The WebSocket connection closes (automatic cache invalidation)
 - The component remounts
 
+:::note[Automatic cache invalidation on disconnect]
+
+When the WebSocket connection closes — whether due to network issues, server restarts, or explicit disconnection — the async query cache is automatically invalidated. This ensures that when the client reconnects, the query function is re-executed to fetch fresh data. This is particularly important for authentication tokens that may have expired during the disconnection period.
+
+:::
+
 ## State synchronization
 
 Agents can maintain state that syncs bidirectionally with all connected clients.
@@ -464,7 +471,7 @@ const user = await agent.call("getUser", [id]);
 
 ### 2. Reconnection is automatic
 
-The client auto-reconnects and the agent automatically sends the current state on each connection. Your `onStateUpdate` callback will fire with the latest state — no manual re-sync is needed.
+The client auto-reconnects and the agent automatically sends the current state on each connection. Your `onStateUpdate` callback will fire with the latest state — no manual re-sync is needed. If you use an async `query` function for authentication, the cache is automatically invalidated on disconnect, ensuring fresh tokens are fetched on reconnect.
 
 ### 3. Optimize query caching