agents-vue 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+
+## v0.1.0
+
+
+### 🚀 Enhancements
+
+- Initial scaffold ([c717193](https://github.com/ymansurozer/agents-vue/commit/c717193))
+
+### 📖 Documentation
+
+- Write README with usage, API, coverage table ([16461f2](https://github.com/ymansurozer/agents-vue/commit/16461f2))
+
+### ❤️ Contributors
+
+- Ymansurozer <ymansurozer@gmail.com>
+

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Mansur Özer
+Portions copyright (c) 2025 Cloudflare, Inc. — original React
+implementation in @cloudflare/ai-chat (https://github.com/cloudflare/agents)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# agents-vue
+
+Vue 3 composable for [Cloudflare Agents](https://github.com/cloudflare/agents) — a port of `@cloudflare/ai-chat/react`'s `useAgentChat` to the Vue Composition API and `@ai-sdk/vue`.
+
+> `agents-vue` is a Vue 3 port of [`@cloudflare/ai-chat`](https://github.com/cloudflare/agents/tree/main/packages/ai-chat)'s `useAgentChat` React hook. The protocol, semantics, and most of the algorithmic structure come directly from the upstream React implementation. This package adapts it to the Vue Composition API and `@ai-sdk/vue`.
+
+## Status
+
+v0.1 — covers the surface needed for a working chat UI: streaming responses, client-side tools, tool approvals, stream resumption, broadcast handling. Deeper upstream features (the `useAgent` connection hook, initial-message HTTP cache, `isServerStreaming` flag) are on the roadmap.
+
+## Install
+
+```bash
+pnpm add agents-vue
+```
+
+Peer dependencies (must also be installed):
+
+| Peer | Version |
+|---|---|
+| `vue` | `^3.3.4` |
+| `@ai-sdk/vue` | `^3.0.0` |
+| `ai` | `^6.0.0` |
+| `agents` | `>=0.11.0 <1.0.0` |
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import { useAgentChat } from "agents-vue";
+
+const { chat, addToolOutput, addToolApprovalResponse, clearHistory, stop } = useAgentChat({
+  client: {
+    agent: "MyAgent",          // Agent class name
+    host: "agent.example.com", // your worker host
+    name: "session-id",        // identifies the Durable Object instance
+  },
+});
+</script>
+
+<template>
+  <div v-for="message in chat.messages" :key="message.id">
+    <strong>{{ message.role }}:</strong>
+    <template v-for="(part, i) in message.parts" :key="i">
+      <span v-if="part.type === 'text'">{{ part.text }}</span>
+    </template>
+  </div>
+
+  <button @click="chat.sendMessage({ text: 'hi' })">Send</button>
+  <button @click="stop()">Stop</button>
+  <button @click="clearHistory()">Clear</button>
+</template>
+```
+
+`chat` is the underlying [`@ai-sdk/vue` `Chat` instance](https://ai-sdk.dev/) — `chat.messages`, `chat.status`, `chat.sendMessage()` are all reactive and standard. The composable layers WebSocket-aware overrides for `addToolOutput`, `addToolApprovalResponse`, `clearHistory`, and `stop`, plus full-history sync, broadcast merging, and stream resumption.
+
+## SSR
+
+`agents-vue` is **client-only**. The composable opens a WebSocket on construction and will throw in Node / SSR contexts. Wrap call sites in `<ClientOnly>` (Nuxt) or defer with `onMounted`.
+
+```vue
+<!-- Nuxt -->
+<ClientOnly>
+  <ChatComponent />
+</ClientOnly>
+```
+
+## API
+
+### `useAgentChat<AgentT, ChatMessage, State>(options)`
+
+Returns:
+
+| Field | Type | Description |
+|---|---|---|
+| `chat` | `Chat<ChatMessage>` | `@ai-sdk/vue` chat instance — reactive `messages`, `status`, `error`, plus `sendMessage`, `regenerate`. |
+| `socket` | `AgentClient<AgentT, State>` | Underlying PartySocket. Typed RPC stub when `AgentT` is provided. |
+| `addToolOutput` | `function` | Submit a tool result. Sends `cf_agent_tool_result` and triggers continuation if enabled. |
+| `addToolApprovalResponse` | `function` | Resolve a human-in-the-loop tool approval. Sends `cf_agent_tool_approval` and triggers continuation. |
+| `clearHistory` | `function` | Clear local state and broadcast `cf_agent_chat_clear` to the server. |
+| `stop` | `function` | Abort the active stream and any pending tool continuation. |
+
+### Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `client` | `AgentClientOptions<State>` | — | **Required.** Connection config — `agent`, `host`, `name`, `basePath`. |
+| `initialMessages` | `ChatMessage[]` | `[]` | Seed messages on mount. |
+| `body` | `object \| () => object \| Promise<object>` | — | Extra request body — static or per-request function. |
+| `tools` | `Record<string, AgentClientTool>` | — | Client-side tool definitions. Schemas auto-extracted and sent with each request. |
+| `onToolCall` | `({ toolCall, addToolOutput }) => void \| Promise<void>` | — | Custom tool-call handler. Overrides per-tool `execute`. |
+| `autoContinueAfterToolResult` | `boolean` | `true` | Server resumes the stream after a tool result. |
+| `resume` | `boolean` | `true` | Resume in-flight streams on socket reconnect. |
+| `onOpen` | `(event: Event) => void` | — | WebSocket open. |
+| `onClose` | `(event: CloseEvent) => void` | — | WebSocket close. |
+| `onSocketError` | `(event: Event) => void` | — | Connection-level error. |
+| `onError` | `(error: Error) => void` | — | Chat-turn error from the AI SDK. |
+
+### Client-side tools
+
+```ts
+useAgentChat({
+  client: { /* ... */ },
+  tools: {
+    weather: {
+      description: "Get the weather for a city",
+      parameters: {
+        type: "object",
+        properties: { city: { type: "string" } },
+        required: ["city"],
+      },
+      execute: async ({ city }) => ({ temp: 70, conditions: "clear" }),
+    },
+  },
+});
+```
+
+Tool schemas are auto-extracted from any tool with an `execute` function and sent to the server with each request. The server invokes the tool by name; `execute` runs client-side; the output flows back via `addToolOutput`.
+
+### Tool approvals (human-in-the-loop)
+
+```ts
+const { addToolApprovalResponse } = useAgentChat({ /* ... */ });
+
+// When the model requests approval for a destructive tool:
+await addToolApprovalResponse({ id: approvalId, approved: true });
+```
+
+The composable matches the approval id against a `tool-approve` part in `chat.messages` and forwards `cf_agent_tool_approval` to the server. If no match exists it warns to the console and bails — no SDK crash.
+
+### `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.
+
+```ts
+import { WebSocketChatTransport, type WebSocketLike } from "agents-vue";
+
+const transport = new WebSocketChatTransport({
+  socket,        // any WebSocketLike
+  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.
+
+| Feature | Status |
+|---|---|
+| `useAgentChat` composable | ✅ |
+| `WebSocketChatTransport` | ✅ |
+| Streaming responses | ✅ |
+| Client-side tools with `execute` | ✅ |
+| Tool approvals (HITL) | ✅ |
+| `body` option (static / sync / async) | ✅ |
+| Stream resumption (resumable streaming) | ✅ |
+| Partial-hydration replay rebuild | ✅ |
+| Broadcast handling (multi-tab) | ✅ |
+| Tool approval continuation merge across broadcasts | ✅ |
+| `useAgent` connection hook | 🚧 roadmap |
+| Initial-message HTTP cache | 🚧 roadmap |
+| `isServerStreaming` / `isStreaming` flags | 🚧 roadmap |
+
+## Contributing
+
+```bash
+pnpm install
+pnpm exec playwright install chromium
+pnpm test       # 59 tests in chromium (vitest-browser-vue)
+pnpm typecheck
+pnpm lint
+pnpm build
+```
+
+Releases are driven by [`changelogen`](https://github.com/unjs/changelogen) with conventional commits.
+
+## License
+
+MIT — see [LICENSE](./LICENSE). Includes attribution to the original Cloudflare React implementation in [`@cloudflare/ai-chat`](https://github.com/cloudflare/agents/tree/main/packages/ai-chat).

package/dist/index.d.mts

@@ -0,0 +1,140 @@
+import * as ai from 'ai';
+import { UIMessage, Tool, JSONSchema7, ChatTransport, ChatRequestOptions, UIMessageChunk } from 'ai';
+import { Chat } from '@ai-sdk/vue';
+import { AgentClientOptions, AgentClient } from 'agents/client';
+
+interface AgentClientTool<Input = unknown, Output = unknown> {
+    description?: Tool["description"];
+    parameters?: JSONSchema7;
+    inputSchema?: JSONSchema7;
+    execute?: (input: Input) => Output | Promise<Output>;
+}
+interface AgentToolOutput {
+    toolCallId: string;
+    output?: unknown;
+    state?: "output-available" | "output-error";
+    errorText?: string;
+}
+interface AgentToolCall {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+}
+type StateOf<AgentT> = AgentT extends {
+    readonly state: infer S;
+} ? S : AgentT;
+interface UseAgentChatOptions<AgentT = unknown, ChatMessage extends UIMessage = UIMessage, State = StateOf<AgentT>> {
+    /** AgentClient connection config — agent name, host, basePath, etc. */
+    client: AgentClientOptions<State>;
+    initialMessages?: ChatMessage[];
+    /** Extra body to include with every request — static object or (sync/async) function. */
+    body?: Record<string, unknown> | (() => Record<string, unknown> | Promise<Record<string, unknown>>);
+    tools?: Record<string, AgentClientTool>;
+    onToolCall?: (options: {
+        toolCall: AgentToolCall;
+        addToolOutput: (toolOutput: AgentToolOutput) => Promise<void>;
+    }) => void | Promise<void>;
+    autoContinueAfterToolResult?: boolean;
+    /** When true (default), the chat resumes any in-flight stream on socket open. */
+    resume?: boolean;
+    /** Called when the underlying WebSocket opens (initial connect or reconnect). */
+    onOpen?: (event: Event) => void;
+    /** Called when the underlying WebSocket closes. */
+    onClose?: (event: CloseEvent) => void;
+    /** Called for connection-level errors. Distinct from `onError`, which fires for chat turn errors. */
+    onSocketError?: (event: Event) => void;
+    /** Called for chat-turn errors (AI SDK). */
+    onError?: (error: Error) => void;
+}
+declare function useAgentChat<AgentT = unknown, ChatMessage extends UIMessage = UIMessage, State = StateOf<AgentT>>(options: UseAgentChatOptions<AgentT, ChatMessage, State>): {
+    addToolApprovalResponse: (args_0: {
+        id: string;
+        approved: boolean;
+        reason?: string;
+        options?: ai.ChatRequestOptions;
+    }) => Promise<void>;
+    addToolOutput: (args_0: {
+        tool: keyof (ChatMessage extends UIMessage<unknown, ai.UIDataTypes, infer TOOLS extends ai.UITools> ? TOOLS : ai.UITools);
+        toolCallId: string;
+        options?: ai.ChatRequestOptions;
+    } & ({
+        state: "output-error";
+        output?: never;
+        errorText: string;
+    } | {
+        state?: "output-available";
+        output: (ChatMessage extends UIMessage<unknown, ai.UIDataTypes, infer TOOLS extends ai.UITools> ? TOOLS : ai.UITools)[keyof (ChatMessage extends UIMessage<unknown, ai.UIDataTypes, infer TOOLS extends ai.UITools> ? TOOLS : ai.UITools)]["output"];
+        errorText?: never;
+    })) => Promise<void>;
+    clearHistory: () => void;
+    chat: Chat<ChatMessage>;
+    socket: AgentClient<AgentT, State>;
+    stop: () => Promise<void>;
+};
+
+/** 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>>;
+}
+/**
+ * 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;
+    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;
+    /** 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 };

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+import * as ai from 'ai';
+import { UIMessage, Tool, JSONSchema7, ChatTransport, ChatRequestOptions, UIMessageChunk } from 'ai';
+import { Chat } from '@ai-sdk/vue';
+import { AgentClientOptions, AgentClient } from 'agents/client';
+
+interface AgentClientTool<Input = unknown, Output = unknown> {
+    description?: Tool["description"];
+    parameters?: JSONSchema7;
+    inputSchema?: JSONSchema7;
+    execute?: (input: Input) => Output | Promise<Output>;
+}
+interface AgentToolOutput {
+    toolCallId: string;
+    output?: unknown;
+    state?: "output-available" | "output-error";
+    errorText?: string;
+}
+interface AgentToolCall {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+}
+type StateOf<AgentT> = AgentT extends {
+    readonly state: infer S;
+} ? S : AgentT;
+interface UseAgentChatOptions<AgentT = unknown, ChatMessage extends UIMessage = UIMessage, State = StateOf<AgentT>> {
+    /** AgentClient connection config — agent name, host, basePath, etc. */
+    client: AgentClientOptions<State>;
+    initialMessages?: ChatMessage[];
+    /** Extra body to include with every request — static object or (sync/async) function. */
+    body?: Record<string, unknown> | (() => Record<string, unknown> | Promise<Record<string, unknown>>);
+    tools?: Record<string, AgentClientTool>;
+    onToolCall?: (options: {
+        toolCall: AgentToolCall;
+        addToolOutput: (toolOutput: AgentToolOutput) => Promise<void>;
+    }) => void | Promise<void>;
+    autoContinueAfterToolResult?: boolean;
+    /** When true (default), the chat resumes any in-flight stream on socket open. */
+    resume?: boolean;
+    /** Called when the underlying WebSocket opens (initial connect or reconnect). */
+    onOpen?: (event: Event) => void;
+    /** Called when the underlying WebSocket closes. */
+    onClose?: (event: CloseEvent) => void;
+    /** Called for connection-level errors. Distinct from `onError`, which fires for chat turn errors. */
+    onSocketError?: (event: Event) => void;
+    /** Called for chat-turn errors (AI SDK). */
+    onError?: (error: Error) => void;
+}
+declare function useAgentChat<AgentT = unknown, ChatMessage extends UIMessage = UIMessage, State = StateOf<AgentT>>(options: UseAgentChatOptions<AgentT, ChatMessage, State>): {
+    addToolApprovalResponse: (args_0: {
+        id: string;
+        approved: boolean;
+        reason?: string;
+        options?: ai.ChatRequestOptions;
+    }) => Promise<void>;
+    addToolOutput: (args_0: {
+        tool: keyof (ChatMessage extends UIMessage<unknown, ai.UIDataTypes, infer TOOLS extends ai.UITools> ? TOOLS : ai.UITools);
+        toolCallId: string;
+        options?: ai.ChatRequestOptions;
+    } & ({
+        state: "output-error";
+        output?: never;
+        errorText: string;
+    } | {
+        state?: "output-available";
+        output: (ChatMessage extends UIMessage<unknown, ai.UIDataTypes, infer TOOLS extends ai.UITools> ? TOOLS : ai.UITools)[keyof (ChatMessage extends UIMessage<unknown, ai.UIDataTypes, infer TOOLS extends ai.UITools> ? TOOLS : ai.UITools)]["output"];
+        errorText?: never;
+    })) => Promise<void>;
+    clearHistory: () => void;
+    chat: Chat<ChatMessage>;
+    socket: AgentClient<AgentT, State>;
+    stop: () => Promise<void>;
+};
+
+/** 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>>;
+}
+/**
+ * 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;
+    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;
+    /** 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 };

package/dist/index.mjs

@@ -0,0 +1,692 @@
+import { Chat } from '@ai-sdk/vue';
+import { broadcastTransition } from 'agents/chat';
+import { AgentClient } from 'agents/client';
+import { onScopeDispose } from 'vue';
+
+function randomRequestId() {
+  return Math.random().toString(36).slice(2, 10);
+}
+class WebSocketChatTransport {
+  socket;
+  prepareBody;
+  activeRequestIds;
+  // Resume handshake state (public so the composable message handler can resolve them)
+  _resumeResolver = null;
+  _resumeNoneResolver = null;
+  // Tool continuation state
+  _expectToolContinuation = false;
+  _abortToolContinuation = null;
+  constructor(options) {
+    this.socket = options.socket;
+    this.prepareBody = options.prepareBody;
+    this.activeRequestIds = options.activeRequestIds ?? /* @__PURE__ */ new Set();
+  }
+  /** Mark that the next reconnectToStream() should attach to a server-initiated tool continuation. */
+  expectToolContinuation() {
+    this._expectToolContinuation = true;
+  }
+  /** Abort the active client-side tool continuation stream. */
+  abortActiveToolContinuation() {
+    return this._abortToolContinuation?.() ?? false;
+  }
+  /** True when the transport is waiting for a resume handshake. */
+  isAwaitingResume() {
+    return this._resumeResolver !== null || this._resumeNoneResolver !== null;
+  }
+  /** Called by the composable when it receives cf_agent_stream_resuming. */
+  handleStreamResuming(data) {
+    if (!this._resumeResolver) {
+      return false;
+    }
+    this._resumeResolver(data);
+    return true;
+  }
+  /** Called by the composable when it receives cf_agent_stream_resume_none. */
+  handleStreamResumeNone() {
+    if (!this._resumeNoneResolver) {
+      return false;
+    }
+    this._resumeNoneResolver();
+    return true;
+  }
+  async sendMessages(options) {
+    const requestId = randomRequestId();
+    const abortController = new AbortController();
+    let completed = false;
+    let extraBody = {};
+    if (this.prepareBody) {
+      extraBody = await this.prepareBody({
+        messages: options.messages,
+        trigger: options.trigger,
+        messageId: options.messageId
+      });
+    }
+    if (options.body) {
+      extraBody = { ...extraBody, ...options.body };
+    }
+    const tail = options.messages.at(-1);
+    const bodyPayload = JSON.stringify({
+      messages: tail ? [tail] : [],
+      trigger: options.trigger,
+      ...extraBody
+    });
+    this.activeRequestIds.add(requestId);
+    const socket = this.socket;
+    const activeIds = this.activeRequestIds;
+    const finish = (action, keepId = false) => {
+      if (completed) {
+        return;
+      }
+      completed = true;
+      try {
+        action();
+      } catch {
+      }
+      if (!keepId) {
+        activeIds.delete(requestId);
+      }
+      abortController.abort();
+    };
+    const abortError = new Error("Aborted");
+    abortError.name = "AbortError";
+    let streamController;
+    const onAbort = () => {
+      if (completed) {
+        return;
+      }
+      try {
+        socket.send(JSON.stringify({ id: requestId, type: "cf_agent_chat_request_cancel" }));
+      } catch {
+      }
+      finish(() => streamController.error(abortError), true);
+    };
+    const stream = new ReadableStream({
+      start(controller) {
+        streamController = controller;
+        const onMessage = (event) => {
+          try {
+            const data = JSON.parse(String(event.data));
+            if (data.type !== "cf_agent_use_chat_response") {
+              return;
+            }
+            if (data.id !== requestId) {
+              return;
+            }
+            if (data.error) {
+              finish(() => controller.error(new Error(data.body || "Stream error")));
+              return;
+            }
+            if (data.body?.trim()) {
+              try {
+                const chunk = JSON.parse(data.body);
+                controller.enqueue(chunk);
+              } catch {
+              }
+            }
+            if (data.done) {
+              finish(() => controller.close());
+            }
+          } catch {
+          }
+        };
+        socket.addEventListener("message", onMessage, { signal: abortController.signal });
+      },
+      cancel() {
+        onAbort();
+      }
+    });
+    if (options.abortSignal) {
+      options.abortSignal.addEventListener("abort", onAbort, { once: true });
+      if (options.abortSignal.aborted) {
+        onAbort();
+      }
+    }
+    socket.send(
+      JSON.stringify({
+        id: requestId,
+        init: { method: "POST", body: bodyPayload },
+        type: "cf_agent_use_chat_request"
+      })
+    );
+    return stream;
+  }
+  async reconnectToStream(_options) {
+    if (this._expectToolContinuation) {
+      this._expectToolContinuation = false;
+      return this._createToolContinuationStream();
+    }
+    const activeIds = this.activeRequestIds;
+    return new Promise((resolve) => {
+      let resolved = false;
+      const done = (value) => {
+        if (resolved) {
+          return;
+        }
+        resolved = true;
+        this._resumeResolver = null;
+        this._resumeNoneResolver = null;
+        clearTimeout(timeout);
+        resolve(value);
+      };
+      this._resumeNoneResolver = () => done(null);
+      this._resumeResolver = (data) => {
+        const id = data.id;
+        activeIds.add(id);
+        this.socket.send(JSON.stringify({ type: "cf_agent_stream_resume_ack", id }));
+        done(this._createResumeStream(id));
+      };
+      try {
+        this.socket.send(JSON.stringify({ type: "cf_agent_stream_resume_request" }));
+      } catch {
+      }
+      const timeout = setTimeout(() => done(null), 5e3);
+    });
+  }
+  /**
+   * 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.
+   */
+  _createToolContinuationStream() {
+    const socket = this.socket;
+    const activeIds = this.activeRequestIds;
+    const streamAbort = new AbortController();
+    const abortError = new Error("Aborted");
+    abortError.name = "AbortError";
+    let completed = false;
+    let requestId = null;
+    let readerController;
+    let onResumeRef = null;
+    let onResumeNoneRef = null;
+    const clearHandshakeResolvers = (resumeResolver, resumeNoneResolver) => {
+      if (resumeResolver === void 0 && resumeNoneResolver === void 0) {
+        this._resumeResolver = null;
+        this._resumeNoneResolver = null;
+        return;
+      }
+      if (resumeResolver && this._resumeResolver === resumeResolver) {
+        this._resumeResolver = null;
+      }
+      if (resumeNoneResolver && this._resumeNoneResolver === resumeNoneResolver) {
+        this._resumeNoneResolver = null;
+      }
+    };
+    const finish = (action, resumeResolver, resumeNoneResolver, keepRequestId = false) => {
+      if (completed) {
+        return;
+      }
+      completed = true;
+      this._abortToolContinuation = null;
+      clearHandshakeResolvers(resumeResolver, resumeNoneResolver);
+      try {
+        action();
+      } catch {
+      }
+      if (requestId && !keepRequestId) {
+        activeIds.delete(requestId);
+      }
+      streamAbort.abort();
+    };
+    this._abortToolContinuation = () => {
+      if (completed) {
+        return false;
+      }
+      if (requestId === null) {
+        finish(() => readerController.error(abortError), onResumeRef, onResumeNoneRef);
+        return true;
+      }
+      try {
+        socket.send(JSON.stringify({ type: "cf_agent_chat_request_cancel", id: requestId }));
+      } catch {
+      }
+      finish(() => readerController.error(abortError), onResumeRef, onResumeNoneRef, true);
+      return true;
+    };
+    return new ReadableStream({
+      start: (controller) => {
+        readerController = controller;
+        const onResumeNone = () => {
+          clearTimeout(timeout);
+          finish(() => controller.close(), onResume, onResumeNone);
+        };
+        const onResume = (data) => {
+          if (requestId) {
+            return;
+          }
+          requestId = data.id;
+          activeIds.add(requestId);
+          clearHandshakeResolvers(onResume, onResumeNone);
+          clearTimeout(timeout);
+          socket.send(JSON.stringify({ type: "cf_agent_stream_resume_ack", id: requestId }));
+        };
+        onResumeRef = onResume;
+        onResumeNoneRef = onResumeNone;
+        const timeout = setTimeout(() => finish(() => controller.close(), onResume, onResumeNone), 5e3);
+        this._resumeResolver = onResume;
+        this._resumeNoneResolver = onResumeNone;
+        const onMessage = (event) => {
+          try {
+            const data = JSON.parse(String(event.data));
+            if (data.type !== "cf_agent_use_chat_response" || requestId == null || data.id !== requestId) {
+              return;
+            }
+            if (data.error) {
+              finish(() => controller.error(new Error(data.body || "Stream error")), onResume, onResumeNone);
+              return;
+            }
+            if (data.body?.trim()) {
+              try {
+                const chunk = JSON.parse(data.body);
+                controller.enqueue(chunk);
+              } catch {
+              }
+            }
+            if (data.done) {
+              finish(() => controller.close(), onResume, onResumeNone);
+            }
+          } catch {
+          }
+        };
+        socket.addEventListener("message", onMessage, { signal: streamAbort.signal });
+        try {
+          socket.send(JSON.stringify({ type: "cf_agent_stream_resume_request" }));
+        } catch {
+          finish(() => controller.close());
+        }
+      },
+      cancel() {
+        finish(() => {
+        });
+      }
+    });
+  }
+  /** Creates a ReadableStream that receives resumed stream chunks. */
+  _createResumeStream(requestId) {
+    const socket = this.socket;
+    const activeIds = this.activeRequestIds;
+    const chunkAbort = new AbortController();
+    let completed = false;
+    const finish = (action) => {
+      if (completed) {
+        return;
+      }
+      completed = true;
+      try {
+        action();
+      } catch {
+      }
+      activeIds.delete(requestId);
+      chunkAbort.abort();
+    };
+    return new ReadableStream({
+      start(controller) {
+        const onMessage = (event) => {
+          try {
+            const data = JSON.parse(String(event.data));
+            if (data.type !== "cf_agent_use_chat_response") {
+              return;
+            }
+            if (data.id !== requestId) {
+              return;
+            }
+            if (data.error) {
+              finish(() => controller.error(new Error(data.body || "Stream error")));
+              return;
+            }
+            if (data.body?.trim()) {
+              try {
+                const chunk = JSON.parse(data.body);
+                controller.enqueue(chunk);
+              } catch {
+              }
+            }
+            if (data.done) {
+              finish(() => controller.close());
+            }
+          } catch {
+          }
+        };
+        socket.addEventListener("message", onMessage, { signal: chunkAbort.signal });
+      },
+      cancel() {
+        finish(() => {
+        });
+      }
+    });
+  }
+}
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function parseProtocolMessage(data) {
+  const parsed = JSON.parse(data);
+  if (!isRecord(parsed) || typeof parsed.type !== "string") {
+    return null;
+  }
+  const message = isUiMessage(parsed.message) ? parsed.message : void 0;
+  const messages = Array.isArray(parsed.messages) && parsed.messages.every(isUiMessage) ? parsed.messages : void 0;
+  return {
+    type: parsed.type,
+    id: typeof parsed.id === "string" ? parsed.id : void 0,
+    body: typeof parsed.body === "string" ? parsed.body : void 0,
+    done: typeof parsed.done === "boolean" ? parsed.done : void 0,
+    error: typeof parsed.error === "boolean" ? parsed.error : void 0,
+    replay: typeof parsed.replay === "boolean" ? parsed.replay : void 0,
+    replayComplete: typeof parsed.replayComplete === "boolean" ? parsed.replayComplete : void 0,
+    continuation: typeof parsed.continuation === "boolean" ? parsed.continuation : void 0,
+    message,
+    messages
+  };
+}
+function isUiMessage(value) {
+  return isRecord(value) && typeof value.id === "string" && typeof value.role === "string" && Array.isArray(value.parts);
+}
+function getToolCallIds(message) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const part of message.parts) {
+    if ("toolCallId" in part && typeof part.toolCallId === "string") {
+      ids.add(part.toolCallId);
+    }
+  }
+  return ids;
+}
+function replaceUpdatedMessage(messages, updatedMessage) {
+  const idIndex = messages.findIndex((message) => message.id === updatedMessage.id);
+  if (idIndex >= 0) {
+    return messages.map((message) => message.id === updatedMessage.id ? updatedMessage : message);
+  }
+  const updatedToolCallIds = getToolCallIds(updatedMessage);
+  if (updatedToolCallIds.size === 0) {
+    return messages;
+  }
+  const toolIndex = messages.findIndex(
+    (message) => message.parts.some(
+      (part) => "toolCallId" in part && typeof part.toolCallId === "string" && updatedToolCallIds.has(part.toolCallId)
+    )
+  );
+  if (toolIndex < 0) {
+    return messages;
+  }
+  const nextMessages = [...messages];
+  const existingMessage = nextMessages[toolIndex];
+  if (!existingMessage) {
+    return messages;
+  }
+  nextMessages[toolIndex] = {
+    ...updatedMessage,
+    id: existingMessage.id
+  };
+  return nextMessages;
+}
+function getApprovalToolCallId(messages, approvalId) {
+  for (const message of messages) {
+    for (const part of message.parts) {
+      if (!("toolCallId" in part) || typeof part.toolCallId !== "string" || !("approval" in part) || !isRecord(part.approval)) {
+        continue;
+      }
+      if (part.approval.id === approvalId) {
+        return part.toolCallId;
+      }
+    }
+  }
+  return null;
+}
+function getClientToolSchemas(tools) {
+  if (!tools) {
+    return void 0;
+  }
+  const schemas = Object.entries(tools).filter(([, tool]) => tool.execute).map(([name, tool]) => ({
+    name,
+    description: tool.description,
+    parameters: tool.parameters ?? tool.inputSchema
+  }));
+  return schemas.length > 0 ? schemas : void 0;
+}
+function getErrorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function preserveActiveStreamMessages(currentMessages, incomingMessages) {
+  const tailMessage = currentMessages.at(-1);
+  if (!tailMessage || tailMessage.role !== "assistant") {
+    return incomingMessages;
+  }
+  const existingIndex = incomingMessages.findIndex((message) => message.id === tailMessage.id);
+  if (existingIndex >= 0) {
+    const nextMessages = [...incomingMessages];
+    nextMessages[existingIndex] = tailMessage;
+    return nextMessages;
+  }
+  const tailToolCallIds = getToolCallIds(tailMessage);
+  if (tailToolCallIds.size > 0) {
+    const remappedIndex = incomingMessages.findIndex(
+      (message) => message.parts.some(
+        (part) => "toolCallId" in part && typeof part.toolCallId === "string" && tailToolCallIds.has(part.toolCallId)
+      )
+    );
+    if (remappedIndex >= 0) {
+      const remapped = incomingMessages[remappedIndex];
+      const nextMessages = [...incomingMessages];
+      nextMessages[remappedIndex] = { ...tailMessage, id: remapped.id };
+      return nextMessages;
+    }
+  }
+  return [...incomingMessages, tailMessage];
+}
+function createMessageId() {
+  return globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2);
+}
+function useAgentChat(options) {
+  const autoContinueAfterToolResult = options.autoContinueAfterToolResult ?? true;
+  const activeRequestIds = /* @__PURE__ */ new Set();
+  let streamState = { status: "idle" };
+  let isResumingToolContinuation = false;
+  const socket = new AgentClient(options.client);
+  const transport = new WebSocketChatTransport({
+    socket,
+    activeRequestIds,
+    prepareBody: async () => {
+      const rawBody = options.body;
+      const extraBody = typeof rawBody === "function" ? await rawBody() : rawBody ?? {};
+      const clientTools = getClientToolSchemas(options.tools);
+      return clientTools ? { ...extraBody, clientTools } : extraBody;
+    }
+  });
+  const handleToolCall = async ({ toolCall }) => {
+    const clientTool = options.tools?.[toolCall.toolName];
+    const addClientToolOutput = (toolOutput) => addToolOutputForTool(toolCall.toolName, toolOutput);
+    if (options.onToolCall) {
+      await options.onToolCall({ toolCall, addToolOutput: addClientToolOutput });
+      return;
+    }
+    if (!clientTool?.execute) {
+      return;
+    }
+    try {
+      const output = await clientTool.execute(toolCall.input);
+      await addClientToolOutput({ toolCallId: toolCall.toolCallId, output });
+    } catch (error) {
+      await addClientToolOutput({
+        toolCallId: toolCall.toolCallId,
+        state: "output-error",
+        errorText: getErrorText(error)
+      });
+    }
+  };
+  const chat = new Chat({
+    messages: options.initialMessages,
+    transport,
+    onToolCall: handleToolCall,
+    onError: options.onError
+  });
+  function startToolContinuation() {
+    if (!autoContinueAfterToolResult || isResumingToolContinuation) {
+      return;
+    }
+    isResumingToolContinuation = true;
+    transport.expectToolContinuation();
+    void chat.resumeStream().finally(() => {
+      isResumingToolContinuation = false;
+    });
+  }
+  async function stop() {
+    try {
+      await chat.stop();
+    } finally {
+      transport.abortActiveToolContinuation();
+    }
+  }
+  function clearHistory() {
+    void stop();
+    isResumingToolContinuation = false;
+    streamState = broadcastTransition(streamState, { type: "clear" }).state;
+    chat.messages = [];
+    socket.send(JSON.stringify({ type: "cf_agent_chat_clear" }));
+  }
+  async function addToolOutputForTool(toolName, toolOutput) {
+    const shouldAutoContinue = toolOutput.state === "output-error" ? false : autoContinueAfterToolResult;
+    const clientTools = getClientToolSchemas(options.tools);
+    socket.send(
+      JSON.stringify({
+        type: "cf_agent_tool_result",
+        toolCallId: toolOutput.toolCallId,
+        toolName,
+        output: "output" in toolOutput ? toolOutput.output : void 0,
+        ...toolOutput.state ? { state: toolOutput.state } : {},
+        ...toolOutput.errorText !== void 0 ? { errorText: toolOutput.errorText } : {},
+        autoContinue: shouldAutoContinue,
+        ...clientTools ? { clientTools } : {}
+      })
+    );
+    if (toolOutput.state === "output-error") {
+      await chat.addToolOutput({
+        tool: toolName,
+        toolCallId: toolOutput.toolCallId,
+        state: "output-error",
+        errorText: toolOutput.errorText ?? "Tool execution failed."
+      });
+    } else {
+      await chat.addToolOutput({
+        tool: toolName,
+        toolCallId: toolOutput.toolCallId,
+        output: toolOutput.output
+      });
+    }
+    if (shouldAutoContinue) {
+      startToolContinuation();
+    }
+  }
+  async function addToolOutput(...args) {
+    const [toolOutput] = args;
+    await addToolOutputForTool(String(toolOutput.tool), toolOutput);
+  }
+  async function addToolApprovalResponse(...args) {
+    const [approvalResponse] = args;
+    const toolCallId = getApprovalToolCallId(chat.messages, approvalResponse.id);
+    if (!toolCallId) {
+      console.warn(`[agents-vue] Could not find tool call for approval "${approvalResponse.id}".`);
+      return;
+    }
+    socket.send(
+      JSON.stringify({
+        type: "cf_agent_tool_approval",
+        toolCallId,
+        approved: approvalResponse.approved,
+        autoContinue: autoContinueAfterToolResult
+      })
+    );
+    await chat.addToolApprovalResponse(...args);
+    startToolContinuation();
+  }
+  socket.addEventListener("message", (event) => {
+    try {
+      const data = parseProtocolMessage(String(event.data));
+      if (!data) {
+        return;
+      }
+      switch (data.type) {
+        // 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 ?? [];
+          break;
+        // Single message update (e.g. tool result applied)
+        case "cf_agent_message_updated":
+          if (data.message) {
+            chat.messages = replaceUpdatedMessage(chat.messages, data.message);
+          }
+          break;
+        // Clear all messages
+        case "cf_agent_chat_clear":
+          streamState = broadcastTransition(streamState, { type: "clear" }).state;
+          chat.messages = [];
+          break;
+        // Forward resume handshake to transport
+        case "cf_agent_stream_resuming":
+          if (data.id && !transport.handleStreamResuming({ type: data.type, id: data.id }) && !activeRequestIds.has(data.id)) {
+            streamState = broadcastTransition(streamState, {
+              type: "resume-fallback",
+              streamId: data.id,
+              messageId: createMessageId()
+            }).state;
+            socket.send(JSON.stringify({ type: "cf_agent_stream_resume_ack", id: data.id }));
+          }
+          break;
+        case "cf_agent_stream_resume_none":
+          transport.handleStreamResumeNone();
+          break;
+        case "cf_agent_use_chat_response":
+          if (!data.id || activeRequestIds.has(data.id)) {
+            return;
+          }
+          {
+            const chunkData = data.body?.trim() ? JSON.parse(data.body) : void 0;
+            const result = broadcastTransition(streamState, {
+              type: "response",
+              streamId: data.id,
+              messageId: createMessageId(),
+              chunkData,
+              done: data.done,
+              error: data.error,
+              replay: data.replay,
+              replayComplete: data.replayComplete,
+              continuation: data.continuation,
+              currentMessages: data.continuation ? chat.messages : void 0
+            });
+            streamState = result.state;
+            if (result.messagesUpdate) {
+              chat.messages = result.messagesUpdate(chat.messages);
+            }
+          }
+          break;
+      }
+    } catch {
+    }
+  });
+  socket.addEventListener("open", (event) => {
+    options.onOpen?.(event);
+    if (options.resume !== false) {
+      void chat.resumeStream();
+    }
+  });
+  socket.addEventListener("close", (event) => {
+    if (options.onClose && event instanceof CloseEvent) {
+      options.onClose(event);
+    }
+  });
+  socket.addEventListener("error", (event) => {
+    options.onSocketError?.(event);
+  });
+  onScopeDispose(() => {
+    socket.close();
+  });
+  return {
+    addToolApprovalResponse,
+    addToolOutput,
+    clearHistory,
+    chat,
+    socket,
+    stop
+  };
+}
+
+export { WebSocketChatTransport, useAgentChat };

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "agents-vue",
+  "version": "0.1.0",
+  "description": "Vue 3 composable for Cloudflare Agents — a port of @cloudflare/ai-chat/react's useAgentChat.",
+  "keywords": [
+    "vue",
+    "vue3",
+    "cloudflare",
+    "agents",
+    "ai",
+    "chat",
+    "websocket",
+    "ai-sdk",
+    "composable"
+  ],
+  "homepage": "https://github.com/ymansurozer/agents-vue",
+  "bugs": "https://github.com/ymansurozer/agents-vue/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ymansurozer/agents-vue.git"
+  },
+  "license": "MIT",
+  "author": "Yusuf Mansur Özer",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "@ai-sdk/vue": "^3.0.0",
+    "agents": ">=0.11.0 <1.0.0",
+    "ai": "^6.0.0",
+    "vue": "^3.3.4"
+  },
+  "devDependencies": {
+    "@ai-sdk/vue": "^3.0.0",
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.0.0",
+    "@vitest/browser": "^4.1.5",
+    "@vitest/browser-playwright": "^4.1.5",
+    "agents": "^0.11.4",
+    "ai": "^6.0.0",
+    "changelogen": "^0.6.2",
+    "eslint": "^9.0.0",
+    "playwright": "^1.49.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.0.0",
+    "unbuild": "^3.0.0",
+    "vitest": "^4.1.5",
+    "vitest-browser-vue": "^2.1.0",
+    "vue": "^3.5.0",
+    "vue-tsc": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "unbuild --watch",
+    "build": "unbuild",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "vue-tsc --noEmit",
+    "release": "pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run build && changelogen --release && git push --follow-tags"
+  }
+}