agents-vue 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,6 +1,39 @@
 # Changelog
 
 
+## v0.4.0
+
+[compare changes](https://github.com/ymansurozer/agents-vue/compare/v0.3.0...v0.4.0)
+
+### 🚀 Enhancements
+
+- `sendOnlyNewMessages` option: a send carries only the messages after the last one the server is known to hold, naming it as `afterMessageId` in the request body, rather than the whole transcript. An edit, or a bare `sendMessage()` resubmitting after an approval or a tool output, carries the message it rewrote; a regenerate carries the full list. The server must rebuild the full list before it persists or broadcasts the request: when the first message sent is one it stores, its stored messages before that one, then the ones sent; otherwise its whole stored transcript, then the sent messages it does not already store, so a client that missed another's messages does not erase them. The option is off by default, and with it off a request body is unchanged.
+
+## v0.3.0
+
+Rebased onto AI SDK v7 and `agents` 0.27, with upstream's own transport and the four client-side bugs the Vue port carried fixed against the React client.
+
+### ⚠️ Breaking changes
+
+- Peer dependencies: `ai ^7`, `@ai-sdk/vue ^4`, `agents >=0.27.0 <1`, `vue ^3.5`
+- `WebSocketChatTransport` and `WebSocketLike` are no longer exported: the hand-rolled transport is deleted and the composable wires upstream's `WebSocketChatTransport` from `agents/chat/transport`. Import it from `agents` if you were using it directly.
+
+### 🩹 Fixes
+
+- Client-side tool calls are dispatched off the rendered transcript, deduped by tool-call id, rather than off the AI SDK's own callback alone. A call in a turn this client only observed — a resumed turn, a turn another tab started — used to render as a chip and never run.
+- An early `cf_agent_stream_resuming` is either fed to the continuation this client armed or observed as the server's own turn, never both. Doing both delivered the same turn twice.
+- The continuation is armed before the `cf_agent_tool_result` / `cf_agent_tool_approval` frame is sent, so the common case does not race at all.
+- A streaming assistant tail that matches nothing in an incoming sync is dropped rather than appended, which is what put the same turn on screen twice.
+- Message ids are minted with `crypto.randomUUID` and otherwise from `crypto.getRandomValues`, never `Math.random`.
+- A turn another tab started can be stopped from the watching tab, and an errored observed turn completes: the chunk handler registers a turn this client is only watching, and the completion branch reads an error frame as an ending rather than waiting for a done that never comes.
+- A continuation handed to the server is released when the socket carrying that turn is replaced: the reconnect probe runs for exactly that case, and a `cf_agent_stream_resume_none` settles the continuation it answers. Without it a dropped socket left the page unable to auto-continue after any later tool result.
+
+### 🚀 Enhancements
+
+- `onFrame` option: every socket frame, parsed, before the chat protocol reads it; return `true` to consume it. This is where an application's own frames belong.
+- `mergeMessages` option: how a reconnect's read of the stored transcript joins the one on screen. Defaults to merge-by-id with the stored copy winning.
+- `onStateUpdate` forwarded to the `AgentClient`, `setAgent()` exposed, `connectionState` derived from the socket's own open/close, `retryPendingResume()` on open, and an async `get-messages` seed with a re-read on a replacement socket.
+
 ## v0.2.1
 
 [compare changes](https://github.com/ymansurozer/agents-vue/compare/v0.2.0...v0.2.1)

package/README.md

@@ -6,7 +6,9 @@ Vue 3 composable for [Cloudflare Agents](https://github.com/cloudflare/agents)
 
 ## Status
 
-Covers the surface needed for a working chat UI — streaming responses, client-side tools, tool approvals, stream resumption, broadcast handling — at parity with upstream `@cloudflare/ai-chat` 0.9.x on resume/recovery: resume dedupe, `isRecovering`, `cancelOnClientAbort`, pre-stream `cf_agent_stream_pending`, and `connectionError`. Deeper upstream features (the `useAgent` connection hook, initial-message HTTP cache, `isServerStreaming` / `isStreaming` flags) are on the roadmap.
+Covers the surface needed for a working chat UI — streaming responses, client-side tools, tool approvals, stream resumption, broadcast handling — at parity with upstream `@cloudflare/ai-chat` 0.12.x on resume/recovery: resume dedupe, `isRecovering`, `cancelOnClientAbort`, pre-stream `cf_agent_stream_pending`, and `connectionError`. Deeper upstream features (the `useAgent` connection hook, the cross-tab observer, `isServerStreaming` / `isStreaming` flags) are on the roadmap.
+
+0.3.0 moves the transport to upstream's own `WebSocketChatTransport` from `agents/chat/transport` and fixes four client-side bugs — see [CHANGELOG](./CHANGELOG.md).
 
 ## Install
 
@@ -18,10 +20,10 @@ Peer dependencies (must also be installed):
 
 | Peer | Version |
 |---|---|
-| `vue` | `^3.3.4` |
-| `@ai-sdk/vue` | `^3.0.0` |
-| `ai` | `^6.0.0` |
-| `agents` | `>=0.17.0 <1.0.0` |
+| `vue` | `^3.5.0` |
+| `@ai-sdk/vue` | `^4.0.0` |
+| `ai` | `^7.0.0` |
+| `agents` | `>=0.27.0 <1.0.0` |
 
 ## Usage
 
@@ -98,6 +100,98 @@ Returns:
 | `onClose` | `(event: CloseEvent) => void` | — | WebSocket close. |
 | `onSocketError` | `(event: Event) => void` | — | Connection-level error. |
 | `onError` | `(error: Error) => void` | — | Chat-turn error from the AI SDK. |
+| `onStateUpdate` | `(state: State, source: "server" \| "client") => void` | — | The agent's state, on connect and on every change the server broadcasts. |
+| `onFrame` | `(frame: unknown) => boolean \| void` | — | Every socket frame, parsed, **before** the chat protocol reads it. Return `true` to consume it. |
+| `mergeMessages` | `(onScreen, stored) => ChatMessage[]` | merge by id | How a reconnect's read of the stored transcript joins the one on screen. |
+| `sendOnlyNewMessages` | `boolean` | `false` | A send carries only the messages after the last one the server is known to hold, named as `afterMessageId`. The server must rebuild the rest. |
+
+### `onFrame` — your own frames
+
+The chat protocol parser narrows a frame to the fields `cf_agent_*` messages have and drops every
+other one, so a frame of your own would arrive with its contents removed. `onFrame` runs first and
+sees the frame whole; returning `true` consumes it, and the protocol handling never sees it.
+
+```ts
+useAgentChat({
+  client: { /* ... */ },
+  onFrame: (frame) => {
+    if (!isRecord(frame) || frame.type !== "my_app_event") return;
+    showBanner(frame);
+    return true; // consumed
+  },
+});
+```
+
+### `mergeMessages` — what a reconnect does to the transcript
+
+Nothing pushes a snapshot on connect, so a replacement socket re-reads the stored transcript — and
+that read is a round trip of its own: it can be issued before a turn is persisted and land after the
+socket has already delivered the finished answer. The default merges by id with the stored copy
+winning and anything only on screen kept after it. Pass your own policy to decide differently.
+
+```ts
+import type { UIMessage } from "ai";
+
+const textLength = (message: UIMessage) =>
+  message.parts.reduce((total, part) => total + (part.type === "text" ? part.text.length : 0), 0);
+
+/** The stored copy can be behind the stream, so the longer of the two wins. */
+const fresher = (stored: UIMessage, onScreen: UIMessage | undefined) =>
+  onScreen && textLength(onScreen) > textLength(stored) ? onScreen : stored;
+
+useAgentChat({
+  client: { /* ... */ },
+  mergeMessages: (onScreen, stored) => {
+    const live = new Map(onScreen.map((message) => [message.id, message]));
+    const storedIds = new Set(stored.map((message) => message.id));
+
+    return [
+      ...stored.map((message) => fresher(message, live.get(message.id))),
+      // Anything only on screen — a question typed while the socket was down — is kept after.
+      ...onScreen.filter((message) => !storedIds.has(message.id)),
+    ];
+  },
+});
+```
+
+### `sendOnlyNewMessages` — sending what the server does not have
+
+By default every send carries the whole transcript, so a request grows with the session. With
+`sendOnlyNewMessages: true` it carries only the messages after the last one the server is known to
+hold — usually just the new question — and names that message as `afterMessageId`, beside
+`messages` in the request body. Known to hold means seen arriving from the server: `initialMessages`,
+the `get-messages` read, a broadcast, a `cf_agent_message_updated` frame, or a stream that finished
+without an error with a part in its reply. A message only this client has never counts. A request
+that rewrites a message in place carries it too: an edited question, or the assistant message a
+bare `sendMessage()` resubmits after an approval or a tool output. A regenerate, and a send before
+the server is known to hold anything, carry the full list and no `afterMessageId`.
+
+A client tool's output is not part of any request: it reaches the server in a `cf_agent_tool_result`
+frame, with the option on or off. What changes is the next request. A question typed after a tool
+output carries only the question, where the full list re-sent the output along with everything
+else; only a request a bare `sendMessage()` makes carries the rewritten assistant message.
+
+**The server's half.** A request with `afterMessageId` holds only part of the transcript, so the
+server must rebuild the full list before it persists the request or broadcasts it — `AIChatAgent`
+broadcasts a request's list to the other clients as it arrived. When the first message sent is one
+it already stores, at index `k`, the request rewrites in place, and the full list is its stored
+messages before `k`, then the ones sent. Otherwise the messages sent are new and go after the whole
+stored transcript, less any it already stores, so a client that missed messages another client
+added does not erase them. The rebuild reads `afterMessageId` only to know the list is partial: its
+value, the last message the client saw the server hold, is a hint, and can name a reply the server
+never stored. A request without the field carries the full list, as before. `AIChatAgent` does none
+of this on its own: it takes a request's list for the whole transcript and deletes the stored
+messages missing from it, which is why the option is off by default.
+
+```ts
+function rebuild(stored: UIMessage[], sent: UIMessage[], afterMessageId?: string): UIMessage[] {
+  if (afterMessageId === undefined) return sent;
+  const rewriteAt = stored.findIndex((message) => message.id === sent[0]?.id);
+  if (rewriteAt >= 0) return [...stored.slice(0, rewriteAt), ...sent];
+  const storedIds = new Set(stored.map((message) => message.id));
+  return [...stored, ...sent.filter((message) => !storedIds.has(message.id))];
+}
+```
 
 ### Client-side tools
 
@@ -133,25 +227,27 @@ The composable matches the approval id against a `tool-approve` part in `chat.me
 
 ### `WebSocketChatTransport`
 
-Exported for advanced use cases. The composable wires this internally; you only need it directly if you're building a non-`@ai-sdk/vue` flow over the same `cf_agent_*` wire protocol.
+No longer exported from here. Since 0.3.0 the composable wires upstream's own transport, so import
+it from `agents` directly if you are building a non-`@ai-sdk/vue` flow over the same `cf_agent_*`
+wire protocol:
 
 ```ts
-import { WebSocketChatTransport, type WebSocketLike } from "agents-vue";
+import { WebSocketChatTransport } from "agents/chat/transport";
 
 const transport = new WebSocketChatTransport({
-  socket,        // any WebSocketLike
+  agent,         // an AgentClient
   prepareBody,   // optional
 });
 ```
 
 ## Coverage vs upstream
 
-`agents-vue@0.1` covers the surface real apps use. Wire protocol is identical to upstream — same `cf_agent_*` message shapes, same resumable streaming, same broadcast transitions, same tool continuation flow.
+`agents-vue` covers the surface real apps use. Wire protocol is identical to upstream — same `cf_agent_*` message shapes, same resumable streaming, same broadcast transitions, same tool continuation flow.
 
 | Feature | Status |
 |---|---|
 | `useAgentChat` composable | ✅ |
-| `WebSocketChatTransport` | ✅ |
+| `WebSocketChatTransport` (upstream's, from `agents/chat/transport`) | ✅ |
 | Streaming responses | ✅ |
 | Client-side tools with `execute` | ✅ |
 | Tool approvals (HITL) | ✅ |
@@ -166,8 +262,16 @@ const transport = new WebSocketChatTransport({
 | Pre-stream `cf_agent_stream_pending` (extended resume probe) | ✅ |
 | `connectionError` (terminal WebSocket close) | ✅ |
 | Reconnect resume serialization (in-flight gate, `agents` 0.17.2 / #1837) | ✅ |
+| `setAgent()`, which invalidates the transport's resume generation | ✅ |
+| `connectionState`, from the socket's own open/close | ✅ |
+| `onStateUpdate`, forwarded to the `AgentClient` | ✅ |
+| Initial `get-messages` seed, and a re-read on a replacement socket | ✅ |
+| Client-side tool calls dispatched off the rendered transcript | ✅ |
+| Early-continuation branch (observe the announced turn, or launch — never both) | ✅ |
+| Continuation armed before the tool frame is sent | ✅ |
+| An unmatchable streaming tail dropped rather than appended | ✅ |
 | `useAgent` connection hook | 🚧 roadmap |
-| Initial-message HTTP cache | 🚧 roadmap |
+| Cross-tab observer | 🚧 roadmap |
 | `isServerStreaming` / `isStreaming` flags | 🚧 roadmap |
 
 ## Contributing
@@ -175,7 +279,7 @@ const transport = new WebSocketChatTransport({
 ```bash
 pnpm install
 pnpm exec playwright install chromium
-pnpm test       # 80 tests in chromium (vitest-browser-vue)
+pnpm test       # chromium (vitest-browser-vue)
 pnpm typecheck
 pnpm lint
 pnpm build

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as vue from 'vue';
 import * as ai from 'ai';
-import { UIMessage, Tool, JSONSchema7, ChatTransport, ChatRequestOptions, UIMessageChunk } from 'ai';
+import { UIMessage, Tool, JSONSchema7 } from 'ai';
 import { Chat } from '@ai-sdk/vue';
 import { AgentClientOptions, AgentClient, AgentConnectionError } from 'agents/client';
 
@@ -53,6 +53,54 @@ interface UseAgentChatOptions<AgentT = unknown, ChatMessage extends UIMessage =
     onSocketError?: (event: Event) => void;
     /** Called for chat-turn errors (AI SDK). */
     onError?: (error: Error) => void;
+    /**
+     * Called with every socket frame, parsed, **before** the chat protocol reads it. Return `true`
+     * to consume the frame, which stops the protocol handling below from seeing it at all.
+     *
+     * This is where an application's own frames belong. The protocol parser narrows a frame to the
+     * fields the chat protocol has and drops every other one, so a frame of your own would otherwise
+     * arrive with its contents removed.
+     */
+    onFrame?: (frame: unknown) => boolean | void;
+    /**
+     * How a transcript read back from the server is merged into the one on screen, used when a
+     * replacement socket re-reads `get-messages`.
+     *
+     * The read is a round trip of its own: it can be issued before a turn is persisted and land
+     * after the socket has already delivered the finished answer, so replacing the transcript with
+     * it wholesale would erase a reply that is on screen. The default merges by id with the stored
+     * copy winning and anything only on screen appended after; pass your own policy to decide
+     * differently — which copy of a message is fresher, say.
+     */
+    mergeMessages?: (onScreen: ChatMessage[], stored: ChatMessage[]) => ChatMessage[];
+    /**
+     * When true, a send carries only the messages after the last one the server is known to hold, and
+     * names that message in the request body as `afterMessageId`. Known to hold means seen arriving
+     * from the server — in `initialMessages`, the `get-messages` read, a `cf_agent_chat_messages`
+     * broadcast, a `cf_agent_message_updated` frame, or a stream that finished without an error with
+     * a part in its reply — never a message only this client has.
+     *
+     * A request that rewrites a message in place carries it too: an edited question, or the assistant
+     * message a bare `sendMessage()` resubmits after an approval or a tool output. A tool output itself
+     * travels in its own frame, so a question typed after one no longer carries it. A regenerate, and a
+     * send before the server is known to hold anything, carry the full list and no `afterMessageId`.
+     *
+     * Turn it on only against a server that rebuilds the transcript before it persists or broadcasts
+     * the request: when the first message sent is one it stores, its stored messages before that one,
+     * then the ones sent; otherwise its whole stored transcript, then the sent messages it does not
+     * already store, so a client that missed another's messages does not erase them. `AIChatAgent` on
+     * its own takes a request's list for the whole transcript, and would keep only the messages sent.
+     */
+    sendOnlyNewMessages?: boolean;
+    /**
+     * Called with the agent's state, on connect and on every change the server broadcasts.
+     *
+     * The same option the React hook passes to `useAgent`. It is forwarded to `AgentClient`, which
+     * owns the `cf_agent_state` frame; the dispatcher below never sees one. `source` is `"server"` for
+     * a broadcast and `"client"` for this client's own `setState` — which a server-owned state refuses,
+     * so nothing here sends one.
+     */
+    onStateUpdate?: (state: State, source: "server" | "client") => void;
 }
 declare function useAgentChat<AgentT = unknown, ChatMessage extends UIMessage = UIMessage, State = StateOf<AgentT>>(options: UseAgentChatOptions<AgentT, ChatMessage, State>): {
     addToolApprovalResponse: (args_0: {
@@ -77,104 +125,17 @@ declare function useAgentChat<AgentT = unknown, ChatMessage extends UIMessage =
     clearHistory: () => void;
     chat: Chat<ChatMessage>;
     socket: AgentClient<AgentT, State>;
+    setAgent: (next: AgentClient<AgentT, State>) => void;
     stop: () => Promise<void>;
+    /** Reactive: true once the `get-messages` seed has settled (or was skipped). */
+    initialMessagesLoaded: vue.Ref<boolean, boolean>;
     /** Reactive: true while the server is recovering a durable chat turn. */
     isRecovering: vue.Ref<boolean, boolean>;
     /** Reactive: terminal WebSocket connection failure, or null. */
     connectionError: vue.Ref<AgentConnectionError | null, AgentConnectionError | null>;
+    /** Reactive: whether the socket is up, for the header's "Reconnecting…". */
+    connectionState: vue.Ref<"connected" | "reconnecting", "connected" | "reconnecting">;
 };
 
-/** Minimal interface a WebSocket must satisfy for the transport. */
-interface WebSocketLike {
-    send(data: string): void;
-    addEventListener(type: string, listener: (event: MessageEvent) => void, options?: AddEventListenerOptions): void;
-}
-interface StreamResumingData {
-    type: string;
-    id: string;
-}
-interface WebSocketChatTransportOptions {
-    socket: WebSocketLike;
-    activeRequestIds?: Set<string>;
-    prepareBody?: (options: {
-        messages: UIMessage[];
-        trigger: "submit-message" | "regenerate-message";
-        messageId?: string;
-    }) => Record<string, unknown> | Promise<Record<string, unknown>>;
-    /**
-     * Whether a generic client-side abort (e.g. the AI SDK aborting the request
-     * signal, or the stream being cancelled on teardown) should cancel the
-     * *server* turn. Local-only by default — the server turn keeps running and can
-     * be resumed/observed. Explicit `stop()` always cancels via
-     * `cancelActiveServerTurn()`, regardless of this flag. Matches upstream 0.7.0.
-     * @default false
-     */
-    cancelOnClientAbort?: boolean;
-}
-/**
- * ChatTransport that communicates with a Cloudflare Agent over WebSocket.
- * Mirrors the protocol implemented by `@cloudflare/ai-chat`'s
- * `WebSocketChatTransport`: same `cf_agent_*` message shapes, same resumable
- * streaming handshake, same tool continuation flow. Framework-agnostic — the
- * Vue composable consumes this; another framework binding could too.
- */
-declare class WebSocketChatTransport implements ChatTransport<UIMessage> {
-    private socket;
-    private prepareBody?;
-    private activeRequestIds;
-    _resumeResolver: ((data: StreamResumingData) => void) | null;
-    _resumeNoneResolver: (() => void) | null;
-    private _expectToolContinuation;
-    private _abortToolContinuation;
-    private cancelOnClientAbort;
-    private _activeServerTurnId;
-    private _cancelAttachedStream;
-    private _onStreamPending;
-    constructor(options: WebSocketChatTransportOptions);
-    /** Mark that the next reconnectToStream() should attach to a server-initiated tool continuation. */
-    expectToolContinuation(): void;
-    /** Abort the active client-side tool continuation stream. */
-    abortActiveToolContinuation(): boolean;
-    /** Send a server-turn cancel frame for a request id (best-effort). */
-    private sendCancelFrame;
-    private setActiveServerTurn;
-    private clearActiveServerTurn;
-    /** Register a server-observed (broadcast / resume-fallback) turn as the cancellable one. */
-    observeServerTurn(requestId: string): void;
-    /** Mark a server turn complete so it is no longer the cancellable turn. */
-    handleServerTurnCompleted(requestId: string): void;
-    /**
-     * Explicitly cancel the active server turn (and any tool continuation). Unlike a
-     * generic client abort, this always signals the server. Drives `useAgentChat.stop()`.
-     */
-    cancelActiveServerTurn(): boolean;
-    /** Called by the composable on cf_agent_stream_pending — extend the in-flight resume probe. */
-    handleStreamPending(): boolean;
-    /** True when the transport is waiting for a resume handshake. */
-    isAwaitingResume(): boolean;
-    /** Called by the composable when it receives cf_agent_stream_resuming. */
-    handleStreamResuming(data: StreamResumingData): boolean;
-    /** Called by the composable when it receives cf_agent_stream_resume_none. */
-    handleStreamResumeNone(): boolean;
-    sendMessages(options: {
-        trigger: "submit-message" | "regenerate-message";
-        chatId: string;
-        messageId: string | undefined;
-        messages: UIMessage[];
-        abortSignal: AbortSignal | undefined;
-    } & ChatRequestOptions): Promise<ReadableStream<UIMessageChunk>>;
-    reconnectToStream(_options: {
-        chatId: string;
-    } & ChatRequestOptions): Promise<ReadableStream<UIMessageChunk> | null>;
-    /**
-     * Creates a deferred ReadableStream for client-side tool continuations.
-     * Returned immediately so AI SDK status becomes "submitted" right after tool output,
-     * then waits for the server to announce continuation via STREAM_RESUMING.
-     */
-    private _createToolContinuationStream;
-    /** Creates a ReadableStream that receives resumed stream chunks. */
-    private _createResumeStream;
-}
-
-export { WebSocketChatTransport, useAgentChat };
-export type { UseAgentChatOptions, WebSocketChatTransportOptions, WebSocketLike };
+export { useAgentChat };
+export type { UseAgentChatOptions };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as vue from 'vue';
 import * as ai from 'ai';
-import { UIMessage, Tool, JSONSchema7, ChatTransport, ChatRequestOptions, UIMessageChunk } from 'ai';
+import { UIMessage, Tool, JSONSchema7 } from 'ai';
 import { Chat } from '@ai-sdk/vue';
 import { AgentClientOptions, AgentClient, AgentConnectionError } from 'agents/client';
 
@@ -53,6 +53,54 @@ interface UseAgentChatOptions<AgentT = unknown, ChatMessage extends UIMessage =
     onSocketError?: (event: Event) => void;
     /** Called for chat-turn errors (AI SDK). */
     onError?: (error: Error) => void;
+    /**
+     * Called with every socket frame, parsed, **before** the chat protocol reads it. Return `true`
+     * to consume the frame, which stops the protocol handling below from seeing it at all.
+     *
+     * This is where an application's own frames belong. The protocol parser narrows a frame to the
+     * fields the chat protocol has and drops every other one, so a frame of your own would otherwise
+     * arrive with its contents removed.
+     */
+    onFrame?: (frame: unknown) => boolean | void;
+    /**
+     * How a transcript read back from the server is merged into the one on screen, used when a
+     * replacement socket re-reads `get-messages`.
+     *
+     * The read is a round trip of its own: it can be issued before a turn is persisted and land
+     * after the socket has already delivered the finished answer, so replacing the transcript with
+     * it wholesale would erase a reply that is on screen. The default merges by id with the stored
+     * copy winning and anything only on screen appended after; pass your own policy to decide
+     * differently — which copy of a message is fresher, say.
+     */
+    mergeMessages?: (onScreen: ChatMessage[], stored: ChatMessage[]) => ChatMessage[];
+    /**
+     * When true, a send carries only the messages after the last one the server is known to hold, and
+     * names that message in the request body as `afterMessageId`. Known to hold means seen arriving
+     * from the server — in `initialMessages`, the `get-messages` read, a `cf_agent_chat_messages`
+     * broadcast, a `cf_agent_message_updated` frame, or a stream that finished without an error with
+     * a part in its reply — never a message only this client has.
+     *
+     * A request that rewrites a message in place carries it too: an edited question, or the assistant
+     * message a bare `sendMessage()` resubmits after an approval or a tool output. A tool output itself
+     * travels in its own frame, so a question typed after one no longer carries it. A regenerate, and a
+     * send before the server is known to hold anything, carry the full list and no `afterMessageId`.
+     *
+     * Turn it on only against a server that rebuilds the transcript before it persists or broadcasts
+     * the request: when the first message sent is one it stores, its stored messages before that one,
+     * then the ones sent; otherwise its whole stored transcript, then the sent messages it does not
+     * already store, so a client that missed another's messages does not erase them. `AIChatAgent` on
+     * its own takes a request's list for the whole transcript, and would keep only the messages sent.
+     */
+    sendOnlyNewMessages?: boolean;
+    /**
+     * Called with the agent's state, on connect and on every change the server broadcasts.
+     *
+     * The same option the React hook passes to `useAgent`. It is forwarded to `AgentClient`, which
+     * owns the `cf_agent_state` frame; the dispatcher below never sees one. `source` is `"server"` for
+     * a broadcast and `"client"` for this client's own `setState` — which a server-owned state refuses,
+     * so nothing here sends one.
+     */
+    onStateUpdate?: (state: State, source: "server" | "client") => void;
 }
 declare function useAgentChat<AgentT = unknown, ChatMessage extends UIMessage = UIMessage, State = StateOf<AgentT>>(options: UseAgentChatOptions<AgentT, ChatMessage, State>): {
     addToolApprovalResponse: (args_0: {
@@ -77,104 +125,17 @@ declare function useAgentChat<AgentT = unknown, ChatMessage extends UIMessage =
     clearHistory: () => void;
     chat: Chat<ChatMessage>;
     socket: AgentClient<AgentT, State>;
+    setAgent: (next: AgentClient<AgentT, State>) => void;
     stop: () => Promise<void>;
+    /** Reactive: true once the `get-messages` seed has settled (or was skipped). */
+    initialMessagesLoaded: vue.Ref<boolean, boolean>;
     /** Reactive: true while the server is recovering a durable chat turn. */
     isRecovering: vue.Ref<boolean, boolean>;
     /** Reactive: terminal WebSocket connection failure, or null. */
     connectionError: vue.Ref<AgentConnectionError | null, AgentConnectionError | null>;
+    /** Reactive: whether the socket is up, for the header's "Reconnecting…". */
+    connectionState: vue.Ref<"connected" | "reconnecting", "connected" | "reconnecting">;
 };
 
-/** Minimal interface a WebSocket must satisfy for the transport. */
-interface WebSocketLike {
-    send(data: string): void;
-    addEventListener(type: string, listener: (event: MessageEvent) => void, options?: AddEventListenerOptions): void;
-}
-interface StreamResumingData {
-    type: string;
-    id: string;
-}
-interface WebSocketChatTransportOptions {
-    socket: WebSocketLike;
-    activeRequestIds?: Set<string>;
-    prepareBody?: (options: {
-        messages: UIMessage[];
-        trigger: "submit-message" | "regenerate-message";
-        messageId?: string;
-    }) => Record<string, unknown> | Promise<Record<string, unknown>>;
-    /**
-     * Whether a generic client-side abort (e.g. the AI SDK aborting the request
-     * signal, or the stream being cancelled on teardown) should cancel the
-     * *server* turn. Local-only by default — the server turn keeps running and can
-     * be resumed/observed. Explicit `stop()` always cancels via
-     * `cancelActiveServerTurn()`, regardless of this flag. Matches upstream 0.7.0.
-     * @default false
-     */
-    cancelOnClientAbort?: boolean;
-}
-/**
- * ChatTransport that communicates with a Cloudflare Agent over WebSocket.
- * Mirrors the protocol implemented by `@cloudflare/ai-chat`'s
- * `WebSocketChatTransport`: same `cf_agent_*` message shapes, same resumable
- * streaming handshake, same tool continuation flow. Framework-agnostic — the
- * Vue composable consumes this; another framework binding could too.
- */
-declare class WebSocketChatTransport implements ChatTransport<UIMessage> {
-    private socket;
-    private prepareBody?;
-    private activeRequestIds;
-    _resumeResolver: ((data: StreamResumingData) => void) | null;
-    _resumeNoneResolver: (() => void) | null;
-    private _expectToolContinuation;
-    private _abortToolContinuation;
-    private cancelOnClientAbort;
-    private _activeServerTurnId;
-    private _cancelAttachedStream;
-    private _onStreamPending;
-    constructor(options: WebSocketChatTransportOptions);
-    /** Mark that the next reconnectToStream() should attach to a server-initiated tool continuation. */
-    expectToolContinuation(): void;
-    /** Abort the active client-side tool continuation stream. */
-    abortActiveToolContinuation(): boolean;
-    /** Send a server-turn cancel frame for a request id (best-effort). */
-    private sendCancelFrame;
-    private setActiveServerTurn;
-    private clearActiveServerTurn;
-    /** Register a server-observed (broadcast / resume-fallback) turn as the cancellable one. */
-    observeServerTurn(requestId: string): void;
-    /** Mark a server turn complete so it is no longer the cancellable turn. */
-    handleServerTurnCompleted(requestId: string): void;
-    /**
-     * Explicitly cancel the active server turn (and any tool continuation). Unlike a
-     * generic client abort, this always signals the server. Drives `useAgentChat.stop()`.
-     */
-    cancelActiveServerTurn(): boolean;
-    /** Called by the composable on cf_agent_stream_pending — extend the in-flight resume probe. */
-    handleStreamPending(): boolean;
-    /** True when the transport is waiting for a resume handshake. */
-    isAwaitingResume(): boolean;
-    /** Called by the composable when it receives cf_agent_stream_resuming. */
-    handleStreamResuming(data: StreamResumingData): boolean;
-    /** Called by the composable when it receives cf_agent_stream_resume_none. */
-    handleStreamResumeNone(): boolean;
-    sendMessages(options: {
-        trigger: "submit-message" | "regenerate-message";
-        chatId: string;
-        messageId: string | undefined;
-        messages: UIMessage[];
-        abortSignal: AbortSignal | undefined;
-    } & ChatRequestOptions): Promise<ReadableStream<UIMessageChunk>>;
-    reconnectToStream(_options: {
-        chatId: string;
-    } & ChatRequestOptions): Promise<ReadableStream<UIMessageChunk> | null>;
-    /**
-     * Creates a deferred ReadableStream for client-side tool continuations.
-     * Returned immediately so AI SDK status becomes "submitted" right after tool output,
-     * then waits for the server to announce continuation via STREAM_RESUMING.
-     */
-    private _createToolContinuationStream;
-    /** Creates a ReadableStream that receives resumed stream chunks. */
-    private _createResumeStream;
-}
-
-export { WebSocketChatTransport, useAgentChat };
-export type { UseAgentChatOptions, WebSocketChatTransportOptions, WebSocketLike };
+export { useAgentChat };
+export type { UseAgentChatOptions };