@assistant-ui/react-a2a 0.2.29 → 0.2.31

package/src/A2AClient.ts

@@ -272,10 +272,157 @@ const parseSendMessageResponse = (value: unknown): A2ATask | A2AMessage => {
   );
 };
 
+const parseTaskResponse = (
+  value: unknown,
+  operation: "tasks:get" | "tasks:cancel",
+): A2ATask => {
+  if (isTask(value)) return value;
+
+  throw new Error(
+    `Invalid A2A ${operation} response: expected a valid task payload.`,
+  );
+};
+
+const isNonNegativeInteger = (value: unknown): value is number =>
+  typeof value === "number" && Number.isInteger(value) && value >= 0;
+
+const invalidListTasksResponse = (): never => {
+  throw new Error(
+    "Invalid A2A tasks:list response: expected a valid task list payload.",
+  );
+};
+
+const parseListTasksResponse = (value: unknown): A2AListTasksResponse => {
+  if (!isRecord(value)) return invalidListTasksResponse();
+
+  const tasks = value.tasks ?? [];
+  if (!Array.isArray(tasks) || !tasks.every(isTask)) {
+    return invalidListTasksResponse();
+  }
+
+  const { nextPageToken, pageSize, totalSize } = value;
+  if (
+    (nextPageToken != null && typeof nextPageToken !== "string") ||
+    (pageSize != null && !isNonNegativeInteger(pageSize)) ||
+    (totalSize != null && !isNonNegativeInteger(totalSize))
+  ) {
+    return invalidListTasksResponse();
+  }
+
+  return {
+    ...value,
+    tasks,
+    nextPageToken: nextPageToken ?? "",
+    pageSize: pageSize ?? 0,
+    totalSize: totalSize ?? 0,
+  };
+};
+
+const invalidPushNotificationConfigResponse =
+  (
+    operation: "pushNotificationConfigs:create" | "pushNotificationConfigs:get",
+  ) =>
+  (): never => {
+    throw new Error(
+      `Invalid A2A ${operation} response: expected a valid push notification config payload.`,
+    );
+  };
+
+const invalidListPushNotificationConfigsResponse = (): never => {
+  throw new Error(
+    "Invalid A2A pushNotificationConfigs:list response: expected a valid push notification config list payload.",
+  );
+};
+
+const parseOptionalString = (
+  value: unknown,
+  invalid: () => never,
+): string | undefined =>
+  value == null ? undefined : typeof value === "string" ? value : invalid();
+
+const parseTaskPushNotificationConfigResponse = (
+  value: unknown,
+  invalid: () => never,
+): A2ATaskPushNotificationConfig => {
+  if (
+    !isRecord(value) ||
+    typeof value.url !== "string" ||
+    value.url.length === 0
+  ) {
+    return invalid();
+  }
+
+  const { tenant, id, taskId, url, token, authentication, ...extra } = value;
+  let normalizedAuthentication: A2ATaskPushNotificationConfig["authentication"];
+  if (authentication != null) {
+    if (!isRecord(authentication)) return invalid();
+    const { scheme, credentials, ...authenticationExtra } = authentication;
+    normalizedAuthentication = {
+      ...authenticationExtra,
+      scheme: parseOptionalString(scheme, invalid) ?? "",
+      ...(credentials == null
+        ? {}
+        : { credentials: parseOptionalString(credentials, invalid) }),
+    };
+  }
+
+  return {
+    ...extra,
+    ...(tenant == null ? {} : { tenant: parseOptionalString(tenant, invalid) }),
+    ...(id == null ? {} : { id: parseOptionalString(id, invalid) }),
+    ...(taskId == null ? {} : { taskId: parseOptionalString(taskId, invalid) }),
+    url,
+    ...(token == null ? {} : { token: parseOptionalString(token, invalid) }),
+    ...(normalizedAuthentication === undefined
+      ? {}
+      : { authentication: normalizedAuthentication }),
+  };
+};
+
+const parseListTaskPushNotificationConfigsResponse = (
+  value: unknown,
+): A2AListTaskPushNotificationConfigsResponse => {
+  if (!isRecord(value)) return invalidListPushNotificationConfigsResponse();
+
+  const { configs: rawConfigs, nextPageToken, ...extra } = value;
+  if (rawConfigs != null && !Array.isArray(rawConfigs)) {
+    return invalidListPushNotificationConfigsResponse();
+  }
+
+  return {
+    ...extra,
+    configs: (rawConfigs ?? []).map((config) =>
+      parseTaskPushNotificationConfigResponse(
+        config,
+        invalidListPushNotificationConfigsResponse,
+      ),
+    ),
+    ...(nextPageToken == null
+      ? {}
+      : {
+          nextPageToken: parseOptionalString(
+            nextPageToken,
+            invalidListPushNotificationConfigsResponse,
+          ),
+        }),
+  };
+};
+
 function signalInit(signal?: AbortSignal): RequestInit {
   return signal ? { signal } : {};
 }
 
+const SKIPPED_FRAME_SNIPPET_LENGTH = 120;
+
+function describeSkippedFrame(data: string, reason: string): string {
+  const collapsed = data.replace(/\s+/g, " ");
+  const snippet =
+    collapsed.length > SKIPPED_FRAME_SNIPPET_LENGTH
+      ? `${collapsed.slice(0, SKIPPED_FRAME_SNIPPET_LENGTH)}…`
+      : collapsed;
+  return `${reason} (frame: ${snippet})`;
+}
+
 export class A2AClient {
   private baseUrl: string;
   private basePath: string;
@@ -458,7 +605,7 @@ export class A2AClient {
       await this.throwResponseError(response);
     }
 
-    yield* this.parseSSE(response);
+    return yield* this.parseSSE(response);
   }
 
   // --- Tasks ---
@@ -474,10 +621,11 @@ export class A2AClient {
       params.set("history_length", String(historyLength));
     }
     const qs = params.toString();
-    return this.fetchJSON<A2ATask>(
+    const result = await this.fetchJSON<unknown>(
       `${this.getBasePath()}/tasks/${encodeURIComponent(taskId)}${qs ? `?${qs}` : ""}`,
       signalInit(signal),
     );
+    return parseTaskResponse(result, "tasks:get");
   }
 
   async listTasks(
@@ -497,10 +645,11 @@ export class A2AClient {
     if (request?.includeArtifacts !== undefined)
       params.set("include_artifacts", String(request.includeArtifacts));
     const qs = params.toString();
-    return this.fetchJSON<A2AListTasksResponse>(
+    const result = await this.fetchJSON<unknown>(
       `${this.getBasePath()}/tasks${qs ? `?${qs}` : ""}`,
       signalInit(signal),
     );
+    return parseListTasksResponse(result);
   }
 
   async cancelTask(
@@ -509,7 +658,7 @@ export class A2AClient {
     signal?: AbortSignal,
   ): Promise<A2ATask> {
     const body = metadata ? { metadata } : {};
-    return this.fetchJSON<A2ATask>(
+    const result = await this.fetchJSON<unknown>(
       `${this.getBasePath()}/tasks/${encodeURIComponent(taskId)}:cancel`,
       {
         method: "POST",
@@ -517,6 +666,7 @@ export class A2AClient {
         ...signalInit(signal),
       },
     );
+    return parseTaskResponse(result, "tasks:cancel");
   }
 
   async *subscribeToTask(
@@ -549,7 +699,7 @@ export class A2AClient {
   ): Promise<A2ATaskPushNotificationConfig> {
     const taskId = config.taskId;
     if (!taskId) throw new Error("taskId is required");
-    return this.fetchJSON<A2ATaskPushNotificationConfig>(
+    const result = await this.fetchJSON<unknown>(
       `${this.getBasePath()}/tasks/${encodeURIComponent(taskId)}/pushNotificationConfigs`,
       {
         method: "POST",
@@ -557,6 +707,10 @@ export class A2AClient {
         ...signalInit(signal),
       },
     );
+    return parseTaskPushNotificationConfigResponse(
+      result,
+      invalidPushNotificationConfigResponse("pushNotificationConfigs:create"),
+    );
   }
 
   async getTaskPushNotificationConfig(
@@ -564,10 +718,14 @@ export class A2AClient {
     configId: string,
     signal?: AbortSignal,
   ): Promise<A2ATaskPushNotificationConfig> {
-    return this.fetchJSON<A2ATaskPushNotificationConfig>(
+    const result = await this.fetchJSON<unknown>(
       `${this.getBasePath()}/tasks/${encodeURIComponent(taskId)}/pushNotificationConfigs/${encodeURIComponent(configId)}`,
       signalInit(signal),
     );
+    return parseTaskPushNotificationConfigResponse(
+      result,
+      invalidPushNotificationConfigResponse("pushNotificationConfigs:get"),
+    );
   }
 
   async listTaskPushNotificationConfigs(
@@ -580,10 +738,11 @@ export class A2AClient {
       params.set("page_size", String(options.pageSize));
     if (options?.pageToken) params.set("page_token", options.pageToken);
     const qs = params.toString();
-    return this.fetchJSON<A2AListTaskPushNotificationConfigsResponse>(
+    const result = await this.fetchJSON<unknown>(
       `${this.getBasePath()}/tasks/${encodeURIComponent(taskId)}/pushNotificationConfigs${qs ? `?${qs}` : ""}`,
       signalInit(signal),
     );
+    return parseListTaskPushNotificationConfigsResponse(result);
   }
 
   async deleteTaskPushNotificationConfig(
@@ -609,13 +768,16 @@ export class A2AClient {
 
   // --- SSE Parsing ---
 
-  private async *parseSSE(response: Response): AsyncGenerator<A2AStreamEvent> {
+  private async *parseSSE(
+    response: Response,
+  ): AsyncGenerator<A2AStreamEvent, string | undefined> {
     const contentType = response.headers.get("Content-Type");
     const mediaType = contentType?.split(";", 1)[0]?.trim().toLowerCase();
     if (mediaType !== "text/event-stream") {
       const received = contentType
         ? `"${contentType}"`
         : "no Content-Type header";
+      void response.body?.cancel().catch(() => undefined);
       throw new Error(
         `Expected A2A stream response Content-Type "text/event-stream", received ${received}`,
       );
@@ -627,6 +789,11 @@ export class A2AClient {
     const decoder = new TextDecoder();
     const sseDecoder = new SSEEventDecoder();
 
+    let firstSkipReason: string | undefined;
+    const noteSkip = (data: string, reason: string) => {
+      firstSkipReason ??= describeSkippedFrame(data, reason);
+    };
+
     const readEvent = (event: SSEEvent): A2AStreamEvent | null => {
       try {
         let parsed = JSON.parse(event.data);
@@ -641,8 +808,14 @@ export class A2AClient {
         }
 
         const normalized = normalizeKeys(parsed) as Record<string, unknown>;
-        return discriminateStreamResponse(normalized);
-      } catch {
+        const streamEvent = discriminateStreamResponse(normalized);
+        if (!streamEvent) noteSkip(event.data, "unrecognized event shape");
+        return streamEvent;
+      } catch (error) {
+        noteSkip(
+          event.data,
+          error instanceof Error ? error.message : String(error),
+        );
         return null;
       }
     };
@@ -682,5 +855,7 @@ export class A2AClient {
         reader.releaseLock();
       }
     }
+
+    return firstSkipReason;
   }
 }

package/src/A2AThreadRuntimeCore.test.ts

@@ -518,6 +518,25 @@ describe("A2AThreadRuntimeCore", () => {
       });
     });
 
+    it("handles malformed status message parts", async () => {
+      const core = createCore({
+        streamMessage: vi.fn().mockImplementation(async function* () {
+          yield {
+            type: "statusUpdate",
+            event: {
+              taskId: "t1",
+              contextId: "ctx-1",
+              status: { state: "completed", message: {} },
+            },
+          } as unknown as A2AStreamEvent;
+        }),
+      });
+
+      await core.append(createUserAppendMessage("Go"));
+
+      expect(core.getMessages()[1]!.content).toEqual([]);
+    });
+
     it("tracks task state from status updates", async () => {
       const core = createCore({
         streamMessage: vi.fn().mockImplementation(async function* () {
@@ -628,6 +647,31 @@ describe("A2AThreadRuntimeCore", () => {
   // --- Artifact handling ---
 
   describe("artifacts", () => {
+    it("treats malformed artifact parts as empty", async () => {
+      const core = createCore({
+        streamMessage: vi.fn().mockImplementation(async function* () {
+          yield {
+            type: "artifactUpdate",
+            event: {
+              taskId: "t1",
+              contextId: "ctx-1",
+              artifact: { artifactId: "a1", parts: {} },
+            },
+          } as unknown as A2AStreamEvent;
+          yield artifactUpdateEvent("a1", [{ text: "part" }], {
+            append: true,
+          });
+          yield statusUpdateEvent("completed", "Done");
+        }),
+      });
+
+      await core.append(createUserAppendMessage("Go"));
+
+      expect(core.getArtifacts()).toEqual([
+        { artifactId: "a1", parts: [{ text: "part" }] },
+      ]);
+    });
+
     it("accumulates artifacts from artifact update events", async () => {
       const core = createCore({
         streamMessage: vi.fn().mockImplementation(async function* () {
@@ -825,6 +869,71 @@ describe("A2AThreadRuntimeCore", () => {
   // --- Task snapshot ---
 
   describe("task snapshot", () => {
+    it("treats malformed artifact parts as empty", async () => {
+      const taskSnapshot = {
+        id: "t1",
+        status: { state: "completed" },
+        artifacts: [{ artifactId: "a1", parts: {} }],
+      } as unknown as A2ATask;
+
+      const core = createCore({
+        streamMessage: vi.fn().mockImplementation(async function* () {
+          yield { type: "task", task: taskSnapshot } as A2AStreamEvent;
+        }),
+      });
+
+      await core.append(createUserAppendMessage("Go"));
+
+      expect(core.getArtifacts()).toEqual([{ artifactId: "a1", parts: [] }]);
+      expect(core.getTask()?.artifacts).toEqual([
+        { artifactId: "a1", parts: [] },
+      ]);
+    });
+
+    it.each([undefined, null, {}, "not-an-array"])(
+      "does not consume malformed task artifacts: %j",
+      async (artifacts) => {
+        const taskSnapshot = {
+          id: "t1",
+          status: { state: "completed" },
+          artifacts,
+          history: artifacts,
+        } as unknown as A2ATask;
+        const core = createCore({
+          streamMessage: vi.fn().mockImplementation(async function* () {
+            yield { type: "task", task: taskSnapshot } as A2AStreamEvent;
+          }),
+        });
+
+        await core.append(createUserAppendMessage("Go"));
+
+        expect(core.getArtifacts()).toEqual([]);
+        if (artifacts === undefined) {
+          expect(core.getTask()?.artifacts).toBeUndefined();
+          expect(core.getTask()?.history).toBeUndefined();
+        } else {
+          expect(core.getTask()?.artifacts).toEqual([]);
+          expect(core.getTask()?.history).toEqual([]);
+        }
+      },
+    );
+
+    it("handles malformed status message parts", async () => {
+      const taskSnapshot = {
+        id: "t1",
+        status: { state: "completed", message: {} },
+      } as unknown as A2ATask;
+      const core = createCore({
+        streamMessage: vi.fn().mockImplementation(async function* () {
+          yield { type: "task", task: taskSnapshot } as A2AStreamEvent;
+        }),
+      });
+
+      await core.append(createUserAppendMessage("Go"));
+
+      expect(core.getMessages()[1]!.content).toEqual([]);
+    });
+
     it("handles full task snapshot from stream", async () => {
       const taskSnapshot: A2ATask = {
         id: "t1",
@@ -1077,17 +1186,73 @@ describe("A2AThreadRuntimeCore", () => {
       },
     );
 
-    it("marks complete when stream ends without terminal status", async () => {
-      const core = createCore({
-        streamMessage: vi.fn().mockImplementation(async function* () {
-          // Stream ends without any events
+    it("rejects a stream that ends without any events", async () => {
+      const onError = vi.fn();
+      const core = createCore(
+        {
+          streamMessage: vi.fn().mockImplementation(async function* () {
+            return;
+          }),
+        },
+        {
+          onError,
+        },
+      );
+
+      await expect(core.append(createUserAppendMessage("Go"))).rejects.toThrow(
+        "A2A message stream ended without any events.",
+      );
+
+      expect(onError).toHaveBeenCalledWith(
+        expect.objectContaining({
+          message: "A2A message stream ended without any events.",
         }),
+      );
+      const assistant = core.getMessages()[1]!;
+      expect(assistant.status).toEqual({
+        type: "incomplete",
+        reason: "error",
       });
+    });
+
+    it("appends the first skipped frame reason to the empty-stream error", async () => {
+      const onError = vi.fn();
+      const core = createCore(
+        {
+          streamMessage: vi.fn().mockImplementation(async function* () {
+            return "unrecognized event shape (frame: {})";
+          }),
+        },
+        { onError },
+      );
+
+      await expect(core.append(createUserAppendMessage("Go"))).rejects.toThrow(
+        "A2A message stream ended without any events. First skipped frame: unrecognized event shape (frame: {})",
+      );
+      expect(onError).toHaveBeenCalledWith(
+        expect.objectContaining({
+          message:
+            "A2A message stream ended without any events. First skipped frame: unrecognized event shape (frame: {})",
+        }),
+      );
+    });
+
+    it("ignores the skipped frame reason when the stream produced events", async () => {
+      const onError = vi.fn();
+      const core = createCore(
+        {
+          streamMessage: vi.fn().mockImplementation(async function* () {
+            yield statusUpdateEvent("completed", "Done");
+            return "unrecognized event shape (frame: {})";
+          }),
+        },
+        { onError },
+      );
 
       await core.append(createUserAppendMessage("Go"));
 
-      const assistant = core.getMessages()[1]!;
-      expect(assistant.status).toEqual({
+      expect(onError).not.toHaveBeenCalled();
+      expect(core.getMessages()[1]!.status).toEqual({
         type: "complete",
         reason: "stop",
       });
@@ -1152,6 +1317,7 @@ describe("A2AThreadRuntimeCore", () => {
           streamMessage.mock.calls.length === 1 ? firstPending : secondPending;
         return (async function* () {
           await pending;
+          yield statusUpdateEvent("completed", "Done");
         })();
       });
       const core = createCore({ streamMessage });
@@ -1200,7 +1366,9 @@ describe("A2AThreadRuntimeCore", () => {
 
 describe("outbound message conversion", () => {
   function createCoreWithStream() {
-    const streamMessage = vi.fn().mockImplementation(async function* () {});
+    const streamMessage = vi.fn().mockImplementation(async function* () {
+      yield statusUpdateEvent("completed", "Done");
+    });
     const core = new A2AThreadRuntimeCore({
       client: createMockClient({ streamMessage }),
       notifyUpdate: vi.fn() as unknown as () => void,

package/src/A2AThreadRuntimeCore.ts

@@ -76,6 +76,13 @@ const invokeRuntimeCallback = <TArgs extends unknown[]>(
   }
 };
 
+function normalizeArtifact(artifact: A2AArtifact): A2AArtifact {
+  return {
+    ...artifact,
+    parts: Array.isArray(artifact.parts) ? artifact.parts : [],
+  };
+}
+
 export class A2AThreadRuntimeCore {
   private client: A2AClient;
   private contextId: string | undefined;
@@ -526,12 +533,28 @@ export class A2AThreadRuntimeCore {
       abortController.signal,
     );
 
-    for await (const event of stream) {
+    let receivedEvent = false;
+    let skipReason: string | undefined;
+    const diagnosedStream = (async function* () {
+      const reason = yield* stream;
+      if (typeof reason === "string") skipReason = reason;
+    })();
+
+    for await (const event of diagnosedStream) {
       if (abortController.signal.aborted) break;
+      receivedEvent = true;
       this.handleStreamEvent(assistantId, event);
     }
 
     if (!abortController.signal.aborted) {
+      if (!receivedEvent) {
+        throw new Error(
+          skipReason
+            ? `A2A message stream ended without any events. First skipped frame: ${skipReason}`
+            : "A2A message stream ended without any events.",
+        );
+      }
+
       const lastStatus = this.getAssistantStatus(assistantId);
       if (lastStatus?.type === "running") {
         this.updateAssistantStatus(assistantId, {
@@ -617,7 +640,8 @@ export class A2AThreadRuntimeCore {
   }
 
   private handleArtifactUpdate(event: A2ATaskArtifactUpdateEvent) {
-    const { artifact, append, lastChunk } = event;
+    const { append, lastChunk } = event;
+    const artifact = normalizeArtifact(event.artifact);
     const existingIdx = this.currentArtifacts.findIndex(
       (a) => a.artifactId === artifact.artifactId,
     );
@@ -666,13 +690,29 @@ export class A2AThreadRuntimeCore {
   }
 
   private handleTaskSnapshot(assistantId: string, task: A2ATask) {
-    this.currentTask = task;
+    const artifacts =
+      task.artifacts === undefined
+        ? undefined
+        : Array.isArray(task.artifacts)
+          ? task.artifacts.map(normalizeArtifact)
+          : [];
+    const history =
+      task.history === undefined
+        ? undefined
+        : Array.isArray(task.history)
+          ? task.history
+          : [];
+    this.currentTask = {
+      ...task,
+      ...(artifacts === undefined ? {} : { artifacts }),
+      ...(history === undefined ? {} : { history }),
+    };
 
     if (task.contextId) {
       this.contextId = task.contextId;
     }
-    if (task.artifacts) {
-      this.currentArtifacts = task.artifacts;
+    if (artifacts) {
+      this.currentArtifacts = artifacts;
     }
 
     if (task.status.message) {

package/src/conversions.test.ts

@@ -228,6 +228,13 @@ describe("a2aPartsToContent", () => {
   it("handles empty parts array", () => {
     expect(a2aPartsToContent([])).toEqual([]);
   });
+
+  it.each([undefined, null, {}, "not-an-array"])(
+    "treats %j parts as empty content",
+    (parts) => {
+      expect(a2aPartsToContent(parts as unknown as A2APart[])).toEqual([]);
+    },
+  );
 });
 
 describe("a2aMessageToContent", () => {
@@ -242,6 +249,15 @@ describe("a2aMessageToContent", () => {
     expect(result[0]).toEqual({ type: "text", text: "Hello" });
     expect(result[1]).toEqual({ type: "text", text: " world" });
   });
+
+  it.each([undefined, null, {}, "not-an-array"])(
+    "treats a message with %j parts as empty content",
+    (parts) => {
+      expect(a2aMessageToContent({ parts } as unknown as A2AMessage)).toEqual(
+        [],
+      );
+    },
+  );
 });
 
 describe("taskStateToMessageStatus", () => {

package/src/conversions.ts

@@ -54,7 +54,7 @@ export function a2aPartToContent(
 export function a2aPartsToContent(
   parts: A2APart[],
 ): ThreadAssistantMessage["content"] {
-  return parts.map(a2aPartToContent);
+  return (Array.isArray(parts) ? parts : []).map(a2aPartToContent);
 }
 
 const TERMINAL_STATES = new Set<A2ATaskState>([
@@ -183,5 +183,5 @@ export function contentPartsToA2AParts(
 export function a2aMessageToContent(
   message: A2AMessage,
 ): ThreadAssistantMessage["content"] {
-  return a2aPartsToContent(message.parts);
+  return a2aPartsToContent(message?.parts ?? []);
 }