feat(client): add version-gated subagent backward-compat shim (0.0.57)

BackwardCompatibility_0_0_57 strips all subagent additions when talking to a pre-subagent (<=0.0.57) remote agent: removes subagentId from input messages on the way in, and drops SUBAGENT_STARTED/FINISHED/ERROR events + strips subagentId from surviving events and MESSAGES_SNAPSHOT messages on the way out. Registered behind compareVersions(maxVersion, '0.0.57') <= 0, and client bumped to 0.0.58 so a default modern client keeps its own subagent data. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ag-ui-protocol · mme · Jul 7, 2026 · Jul 7, 2026 · Jul 7, 2026 · Jul 7, 2026
commit c2a3c27c75d2022c8814b18ef8ab8c2630a99e93
@@ -1,7 +1,7 @@
 {
   "name": "@ag-ui/client",
   "author": "Markus Ecker <markus.ecker@gmail.com>",
-  "version": "0.0.57",
+  "version": "0.0.58",
   "license": "MIT",
   "repository": {
     "type": "git",

@@ -40,6 +40,7 @@ import {
   BackwardCompatibility_0_0_39,
   BackwardCompatibility_0_0_45,
   BackwardCompatibility_0_0_47,
+  BackwardCompatibility_0_0_57,
 } from "@/middleware";
 import packageJson from "../../package.json";
 
@@ -126,6 +127,11 @@ export abstract class AbstractAgent {
       this.middlewares.unshift(new BackwardCompatibility_0_0_47());
     }
 
+    // Auto-insert BackwardCompatibility_0_0_57 for backward compatibility with
+    // pre-subagent agents: strips subagentId and drops SUBAGENT_* lifecycle events.
+    if (compareVersions(this.maxVersion, "0.0.57") <= 0) {
+      this.middlewares.unshift(new BackwardCompatibility_0_0_57());
+    }
   }
 
   public subscribe(subscriber: AgentSubscriber) {

@@ -0,0 +1,134 @@
+import { describe, it, expect } from "vitest";
+import { AbstractAgent } from "@/agent";
+import { BaseEvent, EventType, RunAgentInput } from "@ag-ui/core";
+import { Observable, from, lastValueFrom, toArray } from "rxjs";
+import { BackwardCompatibility_0_0_57 } from "../backward-compatibility-0-0-57";
+
+// Mock agent that records the input it received and replays a scripted stream.
+class MockAgent extends AbstractAgent {
+  public lastInput?: RunAgentInput;
+  private events: BaseEvent[];
+
+  constructor(events: BaseEvent[] = []) {
+    super({});
+    this.events = events;
+  }
+
+  override get maxVersion(): string {
+    return "0.0.57";
+  }
+
+  override run(input: RunAgentInput): Observable<BaseEvent> {
+    this.lastInput = input;
+    return from(this.events);
+  }
+}
+
+const createInput = (overrides: Partial<RunAgentInput> = {}): RunAgentInput => ({
+  threadId: "thread-1",
+  runId: "run-1",
+  state: {},
+  messages: [],
+  tools: [],
+  context: [],
+  forwardedProps: {},
+  ...overrides,
+});
+
+describe("BackwardCompatibility_0_0_57", () => {
+  it("strips subagentId from input messages before the agent sees them", async () => {
+    const middleware = new BackwardCompatibility_0_0_57();
+    const agent = new MockAgent([]);
+    const input = createInput({
+      messages: [
+        { id: "m1", role: "assistant", content: "hi", subagentId: "sub-1" } as any,
+        { id: "m2", role: "user", content: "yo" } as any,
+      ],
+    });
+
+    await lastValueFrom(middleware.run(input, agent).pipe(toArray()));
+
+    expect((agent.lastInput!.messages[0] as any).subagentId).toBeUndefined();
+    expect(agent.lastInput!.messages[0].content).toBe("hi");
+    expect((agent.lastInput!.messages[1] as any).subagentId).toBeUndefined();
+  });
+
+  it("drops SUBAGENT_STARTED/FINISHED/ERROR events from the output stream", async () => {
+    const middleware = new BackwardCompatibility_0_0_57();
+    const events: BaseEvent[] = [
+      { type: EventType.RUN_STARTED, threadId: "thread-1", runId: "run-1" } as any,
+      { type: EventType.SUBAGENT_STARTED, subagentId: "s1", name: "R" } as any,
+      { type: EventType.TEXT_MESSAGE_START, messageId: "m1", subagentId: "s1" } as any,
+      { type: EventType.SUBAGENT_ERROR, subagentId: "s1", message: "x" } as any,
+      { type: EventType.SUBAGENT_FINISHED, subagentId: "s1" } as any,
+      { type: EventType.RUN_FINISHED, threadId: "thread-1", runId: "run-1" } as any,
+    ];
+
+    const result = await lastValueFrom(
+      middleware.run(createInput(), new MockAgent(events)).pipe(toArray()),
+    );
+
+    const types = result.map((e) => e.type);
+    expect(types).toEqual([
+      EventType.RUN_STARTED,
+      EventType.TEXT_MESSAGE_START,
+      EventType.RUN_FINISHED,
+    ]);
+  });
+
+  it("strips subagentId from surviving events", async () => {
+    const middleware = new BackwardCompatibility_0_0_57();
+    const events: BaseEvent[] = [
+      { type: EventType.TEXT_MESSAGE_START, messageId: "m1", subagentId: "s1" } as any,
+    ];
+
+    const result = await lastValueFrom(
+      middleware.run(createInput(), new MockAgent(events)).pipe(toArray()),
+    );
+
+    expect((result[0] as any).subagentId).toBeUndefined();
+    expect((result[0] as any).messageId).toBe("m1");
+  });
+
+  it("strips subagentId from messages inside MESSAGES_SNAPSHOT", async () => {
+    const middleware = new BackwardCompatibility_0_0_57();
+    const events: BaseEvent[] = [
+      {
+        type: EventType.MESSAGES_SNAPSHOT,
+        messages: [
+          { id: "m1", role: "assistant", content: "hi", subagentId: "s1" },
+          { id: "m2", role: "user", content: "yo" },
+        ],
+      } as any,
+    ];
+
+    const result = await lastValueFrom(
+      middleware.run(createInput(), new MockAgent(events)).pipe(toArray()),
+    );
+
+    const snapshot = result[0] as any;
+    expect(snapshot.messages[0].subagentId).toBeUndefined();
+    expect(snapshot.messages[0].content).toBe("hi");
+    expect(snapshot.messages[1].subagentId).toBeUndefined();
+  });
+
+  it("leaves a subagent-free stream and input untouched", async () => {
+    const middleware = new BackwardCompatibility_0_0_57();
+    const events: BaseEvent[] = [
+      { type: EventType.RUN_STARTED, threadId: "thread-1", runId: "run-1" } as any,
+      { type: EventType.TEXT_MESSAGE_START, messageId: "m1", role: "assistant" } as any,
+      { type: EventType.RUN_FINISHED, threadId: "thread-1", runId: "run-1" } as any,
+    ];
+    const agent = new MockAgent(events);
+    const input = createInput({ messages: [{ id: "m0", role: "user", content: "hi" } as any] });
+
+    const result = await lastValueFrom(middleware.run(input, agent).pipe(toArray()));
+
+    expect(result.map((e) => e.type)).toEqual([
+      EventType.RUN_STARTED,
+      EventType.TEXT_MESSAGE_START,
+      EventType.RUN_FINISHED,
+    ]);
+    expect(agent.lastInput!.messages[0].content).toBe("hi");
+  });
+});
@@ -0,0 +1,61 @@
+import { Middleware } from "./middleware";
+import { AbstractAgent } from "@/agent";
+import type { RunAgentInput, BaseEvent } from "@ag-ui/core";
+import { EventType } from "@ag-ui/core";
+import type { Observable } from "rxjs";
+import { filter, map } from "rxjs/operators";
+
+// Subagent lifecycle event types (introduced after 0.0.57). Referenced as string
+// literals so this shim keeps compiling even if the enum members are ever removed.
+const SUBAGENT_STARTED = "SUBAGENT_STARTED";
+const SUBAGENT_FINISHED = "SUBAGENT_FINISHED";
+const SUBAGENT_ERROR = "SUBAGENT_ERROR";
+
+/** Returns a shallow copy of `obj` with any `subagentId` key removed. */
+function stripSubagentId<T extends object>(obj: T): T {
+  if (obj && typeof obj === "object" && "subagentId" in obj) {
+    const { subagentId: _subagentId, ...rest } = obj as T & { subagentId?: unknown };
+    return rest as T;
+  }
+  return obj;
+}
+
+/**
+ * Middleware that removes all subagent-support additions when talking to a
+ * pre-subagent (<= 0.0.57) agent:
+ *  - input:  strips `subagentId` from every message before the agent sees it.
+ *  - output: drops SUBAGENT_STARTED/FINISHED/ERROR events entirely, and strips
+ *            `subagentId` from every remaining event and from each message inside
+ *            a MESSAGES_SNAPSHOT.
+ *
+ * The subagent feature is purely additive, so this shim is a pure removal in both
+ * directions; there is no field/event to translate (unlike 0.0.45's THINKING->REASONING).
+ */
+export class BackwardCompatibility_0_0_57 extends Middleware {
+  override run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent> {
+    const sanitizedInput: RunAgentInput = {
+      ...input,
+      messages: (input.messages ?? []).map((message) => stripSubagentId(message)),
+    } as RunAgentInput;
+
+    return this.runNext(sanitizedInput, next).pipe(
+      filter((event) => {
+        const type = event.type as string;
+        return type !== SUBAGENT_STARTED && type !== SUBAGENT_FINISHED && type !== SUBAGENT_ERROR;
+      }),
+      map((event) => {
+        const stripped = stripSubagentId(event);
+        if (stripped.type === EventType.MESSAGES_SNAPSHOT) {
+          const snapshot = stripped as BaseEvent & { messages?: Array<Record<string, unknown>> };
+          if (Array.isArray(snapshot.messages)) {
+            return {
+              ...snapshot,
+              messages: snapshot.messages.map((message) => stripSubagentId(message)),
+            } as BaseEvent;
+          }
+        }
+        return stripped;
+      }),
+    );
+  }
+}
@@ -4,3 +4,4 @@ export { FilterToolCallsMiddleware } from "./filter-tool-calls";
 export { BackwardCompatibility_0_0_39 } from "./backward-compatibility-0-0-39";
 export { BackwardCompatibility_0_0_45 } from "./backward-compatibility-0-0-45";
 export { BackwardCompatibility_0_0_47 } from "./backward-compatibility-0-0-47";
+export { BackwardCompatibility_0_0_57 } from "./backward-compatibility-0-0-57";