agents 0.12.0 → 0.12.2

package/README.md

@@ -222,6 +222,16 @@ const chat = useAgent({
 
 The routed URL becomes `/agents/inbox/{userId}/sub/chat/{chatId}`.
 
+Child WebSocket clients can use the same URL shape. The parent remains the
+public address, while child agents still receive `onConnect`, `onMessage`,
+`onClose`, `broadcast()`, and `getConnections()` calls scoped to their own
+clients. Parent broadcasts do not leak to child-targeted sockets, and child
+connection tags, readonly state, and protocol-message settings are preserved
+when a connection is resumed from hibernation.
+
+Nested sub-agent URLs are supported using repeated `/sub/{agent}/{name}`
+segments, subject to the platform's current facet nesting limits.
+
 ### Agent Tools
 
 Run chat-capable sub-agents as tools from a parent chat agent. Think agents and

package/dist/{agent-tool-types-tBGRsPm0.d.ts → agent-tool-types-DSteYkkS.d.ts}

@@ -25,7 +25,8 @@ import {
   ConnectionContext as ConnectionContext$1,
   PartyServerOptions,
   Server,
-  WSMessage
+  WSMessage,
+  WSMessage as WSMessage$1
 } from "partyserver";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import {
@@ -845,7 +846,7 @@ declare class MCPClientConnection {
    */
   getTransport(
     transportType: BaseTransportType
-  ): RPCClientTransport | SSEClientTransport | StreamableHTTPClientTransport;
+  ): StreamableHTTPClientTransport | SSEClientTransport | RPCClientTransport;
   private tryConnect;
   private _capabilityErrorHandler;
 }
@@ -1647,6 +1648,54 @@ declare class SqlError extends Error {
   readonly query: string;
   constructor(query: string, cause: unknown);
 }
+type SubAgentConnectionMeta = {
+  id: string;
+  uri: string | null;
+  tags: string[];
+  state: unknown;
+  requestHeaders?: [string, string][];
+};
+type SubAgentConnectionBridgeLike = {
+  send(message: string | ArrayBuffer | ArrayBufferView): void;
+  close(code?: number, reason?: string): void;
+  setState(state: unknown): unknown;
+  broadcast(
+    ownerPath: ReadonlyArray<{
+      className: string;
+      name: string;
+    }>,
+    message: string | ArrayBuffer | ArrayBufferView,
+    without?: string[]
+  ): void;
+};
+declare class SubAgentConnectionBridge
+  extends RpcTarget
+  implements SubAgentConnectionBridgeLike
+{
+  #private;
+  constructor(
+    connection: Connection,
+    broadcast?: (
+      ownerPath: ReadonlyArray<{
+        className: string;
+        name: string;
+      }>,
+      message: string | ArrayBuffer | ArrayBufferView,
+      without?: string[]
+    ) => void
+  );
+  send(message: string | ArrayBuffer | ArrayBufferView): void;
+  close(code?: number, reason?: string): void;
+  setState(state: unknown): unknown;
+  broadcast(
+    ownerPath: ReadonlyArray<{
+      className: string;
+      name: string;
+    }>,
+    message: string | ArrayBuffer | ArrayBufferView,
+    without?: string[]
+  ): void;
+}
 /**
  * Constructor type for a sub-agent class.
  * Used by {@link Agent.subAgent} to reference the child class
@@ -1947,6 +1996,8 @@ declare class Agent<
    * parent-owned WebSocket handles during this window.
    */
   private _suppressProtocolBroadcasts;
+  private _cf_currentSubAgentBridge?;
+  private _cf_virtualSubAgentConnections;
   /**
    * Ancestor chain, root-first. Empty for top-level DOs; populated at
    * facet init time from the parent's own `selfPath`. Exposed publicly
@@ -2782,6 +2833,76 @@ declare class Agent<
    * @experimental The API surface may change before stabilizing.
    */
   fetch(request: Request): Promise<Response>;
+  broadcast(
+    msg: string | ArrayBuffer | ArrayBufferView,
+    without?: string[]
+  ): void;
+  getConnection<TState = unknown>(id: string): Connection<TState> | undefined;
+  getConnections<TState = unknown>(tag?: string): Iterable<Connection<TState>>;
+  private _cf_broadcastToParentSubAgent;
+  _cf_broadcastToSubAgent(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    message: string | ArrayBuffer | ArrayBufferView,
+    without?: string[]
+  ): Promise<void>;
+  _cf_subAgentConnectionMetas(
+    ownerPath: ReadonlyArray<AgentPathStep>
+  ): Promise<SubAgentConnectionMeta[]>;
+  _cf_sendToSubAgentConnection(
+    connectionId: string,
+    message: string | ArrayBuffer | ArrayBufferView
+  ): Promise<void>;
+  _cf_closeSubAgentConnection(
+    connectionId: string,
+    code?: number,
+    reason?: string
+  ): Promise<void>;
+  _cf_setSubAgentConnectionState(
+    connectionId: string,
+    state: unknown
+  ): Promise<unknown>;
+  private _cf_subAgentConnectionMetaForPath;
+  private _cf_subAgentTargetPath;
+  private _cf_subAgentPathFromOuterUri;
+  private _isSameAgentPath;
+  private _cf_connectionHasSubAgentTarget;
+  protected _cf_connectionTargetsSubAgent(connection: Connection): boolean;
+  /**
+   * Returns true when the current request is addressed to a child facet of
+   * this agent rather than to this agent itself.
+   *
+   * Chat-style subclasses wrap `onConnect` before the base Agent forwarding
+   * wrapper runs, so they need a request-level check to avoid sending their
+   * own protocol frames on sockets that are about to be forwarded to a child.
+   */
+  protected _cf_requestTargetsSubAgent(request: Request): boolean;
+  private _cf_forwardSubAgentWebSocketConnect;
+  private _cf_createSubAgentConnectionBridge;
+  private _cf_forwardSubAgentWebSocketMessage;
+  private _cf_forwardSubAgentWebSocketClose;
+  private _cf_resolveSubAgentConnection;
+  _cf_handleSubAgentWebSocketConnect(
+    bridge: SubAgentConnectionBridge,
+    meta: SubAgentConnectionMeta
+  ): Promise<void>;
+  _cf_handleSubAgentWebSocketMessage(
+    message: WSMessage,
+    bridge: SubAgentConnectionBridge,
+    meta: SubAgentConnectionMeta
+  ): Promise<void>;
+  _cf_handleSubAgentWebSocketClose(
+    code: number,
+    reason: string,
+    wasClean: boolean,
+    bridge: SubAgentConnectionBridge,
+    meta: SubAgentConnectionMeta
+  ): Promise<void>;
+  private _cf_runWithSubAgentBridge;
+  private _cf_createSubAgentBridgeConnection;
+  private _cf_storeVirtualSubAgentConnection;
+  protected _cf_hydrateSubAgentConnectionsFromRoot(): Promise<void>;
+  private _cf_getRawConnectionState;
+  private _cf_getForwardedSubAgentState;
   /**
    * Parent-side middleware hook. Fires before a request is
    * forwarded into a facet sub-agent. Mirrors `onBeforeConnect` /
@@ -3872,7 +3993,7 @@ export {
   DEFAULT_AGENT_STATIC_OPTIONS as E,
   SSEEdgeClientTransport as Et,
   RPCRequest as F,
-  WSMessage as G,
+  WSMessage$1 as G,
   StreamingResponse as H,
   RPCResponse as I,
   getCurrentAgent as J,
@@ -3950,4 +4071,4 @@ export {
   createMcpHandler as yt,
   SendEmailOptions as z
 };
-//# sourceMappingURL=agent-tool-types-tBGRsPm0.d.ts.map
+//# sourceMappingURL=agent-tool-types-DSteYkkS.d.ts.map

package/dist/agent-tool-types.d.ts

@@ -14,7 +14,7 @@ import {
   s as AgentToolRunInfo,
   t as AgentToolChildAdapter,
   u as AgentToolRunStatus
-} from "./agent-tool-types-tBGRsPm0.js";
+} from "./agent-tool-types-DSteYkkS.js";
 export {
   AgentToolChildAdapter,
   AgentToolDisplayMetadata,

package/dist/{agent-tools-CIO14miM.d.ts → agent-tools-eGTCdVZX.d.ts}

@@ -1,7 +1,7 @@
 import {
   a as AgentToolEventState,
   i as AgentToolEventMessage
-} from "./agent-tool-types-tBGRsPm0.js";
+} from "./agent-tool-types-DSteYkkS.js";
 
 //#region src/chat/agent-tools.d.ts
 declare function createAgentToolEventState(): AgentToolEventState;
@@ -11,4 +11,4 @@ declare function applyAgentToolEvent(
 ): AgentToolEventState;
 //#endregion
 export { createAgentToolEventState as n, applyAgentToolEvent as t };
-//# sourceMappingURL=agent-tools-CIO14miM.d.ts.map
+//# sourceMappingURL=agent-tools-eGTCdVZX.d.ts.map

package/dist/agent-tools.d.ts

@@ -14,7 +14,7 @@ import {
   s as AgentToolRunInfo,
   t as AgentToolChildAdapter,
   u as AgentToolRunStatus
-} from "./agent-tool-types-tBGRsPm0.js";
+} from "./agent-tool-types-DSteYkkS.js";
 import { Tool } from "ai";
 
 //#region src/agent-tools.d.ts

package/dist/chat/index.d.ts

@@ -1,5 +1,5 @@
-import { a as AgentToolEventState, i as AgentToolEventMessage, l as AgentToolRunState, r as AgentToolEvent } from "../agent-tool-types-tBGRsPm0.js";
-import { n as createAgentToolEventState, t as applyAgentToolEvent } from "../agent-tools-CIO14miM.js";
+import { a as AgentToolEventState, i as AgentToolEventMessage, l as AgentToolRunState, r as AgentToolEvent } from "../agent-tool-types-DSteYkkS.js";
+import { n as createAgentToolEventState, t as applyAgentToolEvent } from "../agent-tools-eGTCdVZX.js";
 import { JSONSchema7, Tool, ToolSet, UIMessage } from "ai";
 import { Connection } from "agents";
 
@@ -503,6 +503,7 @@ declare class ResumableStream {
    *          When non-null the caller should reconstruct the message from chunks.
    */
   replayChunks(connection: Connection, requestId: string): string | null;
+  replayCompletedChunksByRequestId(connection: Connection, requestId: string): boolean;
   /**
    * Restore active stream state if the agent was restarted during streaming.
    * All streams are restored regardless of age — stale cleanup happens

package/dist/chat/index.js

@@ -746,6 +746,37 @@ var ResumableStream = class ResumableStream {
 		}));
 		return null;
 	}
+	replayCompletedChunksByRequestId(connection, requestId) {
+		this.flushBuffer();
+		const stream = this.sql`
+      select * from cf_ai_chat_stream_metadata
+      where request_id = ${requestId}
+      and status = 'completed'
+      order by created_at desc
+      limit 1
+    `[0];
+		if (!stream) return false;
+		const chunks = this.sql`
+      select * from cf_ai_chat_stream_chunks
+      where stream_id = ${stream.id}
+      order by chunk_index asc
+    `;
+		for (const chunk of chunks || []) connection.send(JSON.stringify({
+			body: chunk.body,
+			done: false,
+			id: requestId,
+			type: CHAT_MESSAGE_TYPES.USE_CHAT_RESPONSE,
+			replay: true
+		}));
+		connection.send(JSON.stringify({
+			body: "",
+			done: true,
+			id: requestId,
+			type: CHAT_MESSAGE_TYPES.USE_CHAT_RESPONSE,
+			replay: true
+		}));
+		return true;
+	}
 	/**
 	* Restore active stream state if the agent was restarted during streaming.
 	* All streams are restored regardless of age — stale cleanup happens