agents-vue 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,6 +1,14 @@
 # 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.

package/README.md

@@ -103,6 +103,7 @@ Returns:
 | `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
 
@@ -153,6 +154,45 @@ useAgentChat({
 });
 ```
 
+### `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
 
 ```ts

package/dist/index.d.mts

@@ -73,6 +73,25 @@ interface UseAgentChatOptions<AgentT = unknown, ChatMessage extends UIMessage =
      * 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.
      *

package/dist/index.d.ts

@@ -73,6 +73,25 @@ interface UseAgentChatOptions<AgentT = unknown, ChatMessage extends UIMessage =
      * 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.
      *

package/dist/index.mjs

@@ -128,6 +128,17 @@ function mergeById(onScreen, stored) {
   const storedIds = new Set(stored.map((message) => message.id));
   return [...stored, ...onScreen.filter((message) => !storedIds.has(message.id))];
 }
+function idsOf(messages) {
+  return messages.map((message) => message.id);
+}
+function startMessageIdOf(body) {
+  try {
+    const chunk = JSON.parse(body);
+    return isRecord(chunk) && chunk.type === "start" && typeof chunk.messageId === "string" ? chunk.messageId : null;
+  } catch {
+    return null;
+  }
+}
 function createMessageId() {
   if (globalThis.crypto?.randomUUID) {
     return globalThis.crypto.randomUUID();
@@ -146,6 +157,8 @@ function useAgentChat(options) {
   let continuationLaunchTimer = null;
   let observedToolContinuationRequestId = null;
   const dispatchedToolCallIds = /* @__PURE__ */ new Set();
+  let heldMessageIds = idsOf(options.initialMessages ?? []);
+  const streamMessageIds = /* @__PURE__ */ new Map();
   let resumeInFlight = false;
   let resumeGeneration = 0;
   const isRecovering = ref(false);
@@ -198,9 +211,50 @@ function useAgentChat(options) {
   }
   const chat = new Chat({
     messages: options.initialMessages,
-    transport,
+    transport: options.sendOnlyNewMessages ? {
+      sendMessages: (request) => transport.sendMessages(onlyNewMessages(request)),
+      reconnectToStream: (request) => transport.reconnectToStream(request)
+    } : transport,
     onError: options.onError
   });
+  function onlyNewMessages(request) {
+    if (request.trigger === "regenerate-message") {
+      return request;
+    }
+    const { messages } = request;
+    let held = 0;
+    while (held < messages.length && messages[held]?.id === heldMessageIds[held]) {
+      held++;
+    }
+    const rewrittenIndex = messages.findIndex((message) => message.id === request.messageId);
+    const start = rewrittenIndex >= 0 ? Math.min(held, rewrittenIndex) : held;
+    if (rewrittenIndex >= 0) {
+      heldMessageIds = heldMessageIds.slice(0, start);
+    }
+    const afterMessageId = messages[start - 1]?.id;
+    if (afterMessageId === void 0 || start === messages.length) {
+      return request;
+    }
+    return { ...request, messages: messages.slice(start), body: { ...request.body, afterMessageId } };
+  }
+  function holdThrough(messageId) {
+    const index = chat.messages.findIndex((message) => message.id === messageId);
+    if (index >= 0) {
+      heldMessageIds = idsOf(chat.messages.slice(0, index + 1));
+    }
+  }
+  function trackStreamMessage(requestId, frame) {
+    if (frame.done || frame.error) {
+      const messageId = streamMessageIds.get(requestId);
+      streamMessageIds.delete(requestId);
+      const reply = chat.messages.find((message) => message.id === messageId);
+      if (reply && reply.parts.length > 0 && !frame.error) {
+        holdThrough(reply.id);
+      }
+    } else if (!streamMessageIds.has(requestId) && frame.body?.trim()) {
+      streamMessageIds.set(requestId, startMessageIdOf(frame.body));
+    }
+  }
   function dispatchRenderedToolCalls() {
     if (chat.status === "streaming" || chat.status === "submitted" || isServerStreaming.value || isRecovering.value) {
       return;
@@ -273,6 +327,7 @@ function useAgentChat(options) {
     isServerStreaming.value = false;
     streamState = broadcastTransition(streamState, { type: "clear" }).state;
     chat.messages = [];
+    heldMessageIds = [];
     socket.send(JSON.stringify({ type: "cf_agent_chat_clear" }));
   }
   async function addToolOutputForTool(toolName, toolOutput) {
@@ -348,17 +403,20 @@ function useAgentChat(options) {
         // Full message list sync (sent on connect, and after every appendMessage / turn).
         case "cf_agent_chat_messages":
           chat.messages = chat.status === "streaming" || chat.status === "submitted" || streamState.status !== "idle" ? preserveActiveStreamMessages(chat.messages, data.messages ?? []) : data.messages ?? [];
+          heldMessageIds = idsOf(data.messages ?? []);
           break;
         // Single message update (e.g. tool result applied)
         case "cf_agent_message_updated":
           if (data.message) {
             chat.messages = replaceUpdatedMessage(chat.messages, data.message);
+            holdThrough(data.message.id);
           }
           break;
         // Clear all messages
         case "cf_agent_chat_clear":
           streamState = broadcastTransition(streamState, { type: "clear" }).state;
           chat.messages = [];
+          heldMessageIds = [];
           isRecovering.value = false;
           isServerStreaming.value = false;
           break;
@@ -405,6 +463,9 @@ function useAgentChat(options) {
           isRecovering.value = Boolean(data.recovering);
           break;
         case "cf_agent_use_chat_response":
+          if (data.id) {
+            trackStreamMessage(data.id, data);
+          }
           if (!data.id || activeRequestIds.has(data.id)) {
             return;
           }
@@ -470,6 +531,7 @@ function useAgentChat(options) {
   });
   socket.addEventListener("close", (event) => {
     fallbackAckedResumeRequestIds.clear();
+    streamMessageIds.clear();
     isRecovering.value = false;
     connectionState.value = "reconnecting";
     resyncPending = true;
@@ -521,6 +583,7 @@ function useAgentChat(options) {
       const stored = await fetchStoredMessages();
       if (stored && chat.messages.length === 0) {
         chat.messages = stored;
+        heldMessageIds = idsOf(stored);
       }
     } finally {
       initialMessagesLoaded.value = true;
@@ -530,6 +593,7 @@ function useAgentChat(options) {
     const stored = await fetchStoredMessages();
     if (stored) {
       chat.messages = (options.mergeMessages ?? mergeById)(chat.messages, stored);
+      heldMessageIds = idsOf(stored);
     }
   }
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-vue",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Vue 3 composable for Cloudflare Agents — a port of @cloudflare/ai-chat/react's useAgentChat.",
   "keywords": [
     "vue",