assistant-stream 0.3.25 → 0.3.27

package/src/core/utils/stream/LineDecoderStream.test.ts

@@ -40,6 +40,22 @@ describe("LineDecoderStream", () => {
     expect(lines).toEqual(["line1", "line2", "line3"]);
   });
 
+  it("should split lines on CR (\\r)", async () => {
+    const stream = createTextStream(["line1\rline2\rline3\r"]);
+    const lines = await collectLines(
+      stream.pipeThrough(new LineDecoderStream()),
+    );
+    expect(lines).toEqual(["line1", "line2", "line3"]);
+  });
+
+  it("should handle CR line endings split across chunks", async () => {
+    const stream = createTextStream(["line1\r", "line2\r", "line3\r"]);
+    const lines = await collectLines(
+      stream.pipeThrough(new LineDecoderStream()),
+    );
+    expect(lines).toEqual(["line1", "line2", "line3"]);
+  });
+
   it("should handle CRLF split across chunks", async () => {
     // The \r is at the end of one chunk and \n at the start of the next
     const stream = createTextStream(["line1\r", "\nline2\r\n"]);
@@ -65,8 +81,16 @@ describe("LineDecoderStream", () => {
     expect(lines).toEqual(["line1", "", "line2"]);
   });
 
-  it("should handle mixed LF and CRLF", async () => {
-    const stream = createTextStream(["line1\nline2\r\nline3\n"]);
+  it("should handle empty lines with CR", async () => {
+    const stream = createTextStream(["line1\r\rline2\r"]);
+    const lines = await collectLines(
+      stream.pipeThrough(new LineDecoderStream()),
+    );
+    expect(lines).toEqual(["line1", "", "line2"]);
+  });
+
+  it("should handle mixed standard line endings", async () => {
+    const stream = createTextStream(["line1\nline2\r\nline3\r"]);
     const lines = await collectLines(
       stream.pipeThrough(new LineDecoderStream()),
     );

package/src/core/utils/stream/LineDecoderStream.ts

@@ -1,25 +1,35 @@
 export class LineDecoderStream extends TransformStream<string, string> {
   private buffer = "";
+  private skipNextLineFeed = false;
 
   constructor() {
     super({
       transform: (chunk, controller) => {
-        this.buffer += chunk;
-        const lines = this.buffer.split("\n");
+        let lineStart = 0;
 
-        // Process all complete lines
-        for (let i = 0; i < lines.length - 1; i++) {
-          // Strip trailing \r to handle \r\n (CRLF) line endings per the SSE spec.
-          const line = lines[i]!;
-          controller.enqueue(line.endsWith("\r") ? line.slice(0, -1) : line);
+        for (let i = 0; i < chunk.length; i++) {
+          const character = chunk[i]!;
+
+          if (this.skipNextLineFeed) {
+            this.skipNextLineFeed = false;
+            if (character === "\n") {
+              lineStart = i + 1;
+              continue;
+            }
+          }
+
+          if (character === "\n" || character === "\r") {
+            this.buffer += chunk.slice(lineStart, i);
+            controller.enqueue(this.buffer);
+            this.buffer = "";
+            this.skipNextLineFeed = character === "\r";
+            lineStart = i + 1;
+          }
         }
 
-        // Keep the last incomplete line in the buffer
-        this.buffer = lines[lines.length - 1] || "";
+        this.buffer += chunk.slice(lineStart);
       },
       flush: () => {
-        // If there's content in the buffer when the stream ends, it means
-        // the stream ended with an incomplete line (no trailing newline)
         if (this.buffer) {
           throw new Error(
             `Stream ended with an incomplete line: "${this.buffer}"`,

package/src/core/utils/stream/SSE.ts

@@ -1,5 +1,8 @@
 import { PipeableTransformStream } from "./PipeableTransformStream";
-import { LineDecoderStream } from "./LineDecoderStream";
+import {
+  SSEEventDecoderStream,
+  type PipelineSSEEvent,
+} from "./SSEEventDecoderStream";
 
 export class SSEEncoder<T> extends PipeableTransformStream<
   T,
@@ -28,72 +31,6 @@ export class SSEEncoder<T> extends PipeableTransformStream<
   }
 }
 
-type SSEEvent = {
-  event: string;
-  data: string;
-  id?: string | undefined;
-  retry?: number | undefined;
-};
-
-class SSEEventStream extends TransformStream<string, SSEEvent> {
-  constructor() {
-    let eventBuffer: Partial<SSEEvent> = {};
-    let dataLines: string[] = [];
-
-    super({
-      start() {
-        eventBuffer = {};
-        dataLines = [];
-      },
-      transform(line, controller) {
-        if (line.startsWith(":")) return; // Ignore comments
-
-        if (line === "") {
-          if (dataLines.length > 0) {
-            controller.enqueue({
-              event: eventBuffer.event || "message",
-              data: dataLines.join("\n"),
-              id: eventBuffer.id,
-              retry: eventBuffer.retry,
-            });
-          }
-          eventBuffer = {};
-          dataLines = [];
-          return;
-        }
-
-        const [field, ...rest] = line.split(":");
-        const value = rest.join(":").trimStart();
-
-        switch (field) {
-          case "event":
-            eventBuffer.event = value;
-            break;
-          case "data":
-            dataLines.push(value);
-            break;
-          case "id":
-            eventBuffer.id = value;
-            break;
-          case "retry":
-            eventBuffer.retry = Number(value);
-            break;
-        }
-      },
-      flush(controller) {
-        if (dataLines.length > 0) {
-          controller.enqueue({
-            event: eventBuffer.event || "message",
-            data: dataLines.join("\n"),
-            id: eventBuffer.id,
-            retry: eventBuffer.retry,
-          });
-        }
-      },
-    });
-  }
-}
-
 export class SSEDecoder<T> extends PipeableTransformStream<
   Uint8Array<ArrayBuffer>,
   T
@@ -102,10 +39,9 @@ export class SSEDecoder<T> extends PipeableTransformStream<
     super((readable) =>
       readable
         .pipeThrough(new TextDecoderStream())
-        .pipeThrough(new LineDecoderStream())
-        .pipeThrough(new SSEEventStream())
+        .pipeThrough(new SSEEventDecoderStream())
         .pipeThrough(
-          new TransformStream<SSEEvent, T>({
+          new TransformStream<PipelineSSEEvent, T>({
             transform(event, controller) {
               switch (event.event) {
                 case "message":

package/src/core/utils/stream/SSEEventDecoder.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from "vitest";
+import { SSEEventDecoder } from "./SSEEventDecoder";
+
+describe("SSEEventDecoder", () => {
+  it("decodes LF terminated events", () => {
+    const decoder = new SSEEventDecoder();
+    expect(decoder.push("data: x\n\n")).toEqual([{ data: "x" }]);
+  });
+
+  it("decodes CRLF terminated events", () => {
+    const decoder = new SSEEventDecoder();
+    expect(decoder.push("data: x\r\n\r\n")).toEqual([{ data: "x" }]);
+  });
+
+  it("decodes CR terminated events", () => {
+    const decoder = new SSEEventDecoder();
+    expect(decoder.push("data: x\r\r")).toEqual([{ data: "x" }]);
+  });
+
+  it("handles CRLF split across pushes", () => {
+    const decoder = new SSEEventDecoder();
+    expect(decoder.push("data: x\r")).toEqual([]);
+    expect(decoder.push("\n\r\n")).toEqual([{ data: "x" }]);
+  });
+
+  it("handles CR terminated lines split across pushes", () => {
+    const decoder = new SSEEventDecoder();
+    expect(decoder.push("data: x\r")).toEqual([]);
+    expect(decoder.push("\r")).toEqual([{ data: "x" }]);
+  });
+
+  it("decodes multiple events in one push", () => {
+    const decoder = new SSEEventDecoder();
+    expect(decoder.push("data: first\n\ndata: second\n\n")).toEqual([
+      { data: "first" },
+      { data: "second" },
+    ]);
+  });
+
+  it("joins multiple data lines with a newline", () => {
+    const decoder = new SSEEventDecoder();
+    expect(decoder.push("data: first\ndata: second\n\n")).toEqual([
+      { data: "first\nsecond" },
+    ]);
+  });
+
+  it("preserves data values without a space after the colon", () => {
+    const decoder = new SSEEventDecoder();
+    expect(decoder.push("data:x\n\n")).toEqual([{ data: "x" }]);
+  });
+
+  it("skips comment lines", () => {
+    const decoder = new SSEEventDecoder();
+    expect(decoder.push(": heartbeat\ndata: x\n\n")).toEqual([{ data: "x" }]);
+  });
+
+  it("captures event fields and clears them after dispatch", () => {
+    const decoder = new SSEEventDecoder();
+    expect(
+      decoder.push("event: update\ndata: first\n\ndata: second\n\n"),
+    ).toEqual([{ event: "update", data: "first" }, { data: "second" }]);
+  });
+
+  it("persists IDs across frames", () => {
+    const decoder = new SSEEventDecoder();
+    expect(decoder.push("id: 1\ndata: first\n\ndata: second\n\n")).toEqual([
+      { data: "first", id: "1" },
+      { data: "second", id: "1" },
+    ]);
+  });
+
+  it("parses numeric retries and ignores non-numeric retries", () => {
+    const decoder = new SSEEventDecoder();
+    expect(
+      decoder.push(
+        "retry: 1000\ndata: first\n\nretry: invalid\ndata: second\n\n",
+      ),
+    ).toEqual([
+      { data: "first", retry: 1000 },
+      { data: "second", retry: 1000 },
+    ]);
+  });
+
+  it("ignores ids containing NUL and keeps ids containing spaces", () => {
+    const decoder = new SSEEventDecoder();
+    expect(
+      decoder.push(
+        "id: ok\ndata: a\n\nid: bad\u0000id\ndata: b\n\nid: spaced id\ndata: c\n\n",
+      ),
+    ).toEqual([
+      { data: "a", id: "ok" },
+      { data: "b", id: "ok" },
+      { data: "c", id: "spaced id" },
+    ]);
+  });
+
+  it("ignores non-digit and unsafe-integer retry values", () => {
+    const decoder = new SSEEventDecoder();
+    expect(
+      decoder.push(
+        "retry: 1000\ndata: a\n\nretry: -1\ndata: b\n\nretry: 1.5\ndata: c\n\nretry: 1e3\ndata: d\n\nretry:\ndata: e\n\n" +
+          `retry: ${"9".repeat(400)}\ndata: f\n\n`,
+      ),
+    ).toEqual([
+      { data: "a", retry: 1000 },
+      { data: "b", retry: 1000 },
+      { data: "c", retry: 1000 },
+      { data: "d", retry: 1000 },
+      { data: "e", retry: 1000 },
+      { data: "f", retry: 1000 },
+    ]);
+  });
+
+  it("does not dispatch blank frames", () => {
+    const decoder = new SSEEventDecoder();
+    expect(decoder.push("event: update\n\ndata: x\n\n")).toEqual([
+      { data: "x" },
+    ]);
+  });
+
+  it("preserves a pending LF across empty pushes", () => {
+    const decoder = new SSEEventDecoder();
+    expect(decoder.push("data: x\r")).toEqual([]);
+    expect(decoder.push("")).toEqual([]);
+    expect(decoder.push("\n\r\n")).toEqual([{ data: "x" }]);
+  });
+
+  it("drops unterminated trailing data by default", () => {
+    const decoder = new SSEEventDecoder();
+    expect(decoder.push("data: x")).toEqual([]);
+    expect(decoder.flush()).toBeNull();
+  });
+
+  it("dispatches an unterminated final data line when configured", () => {
+    const decoder = new SSEEventDecoder({ trailing: "dispatch" });
+    expect(decoder.push("data: x")).toEqual([]);
+    expect(decoder.flush()).toEqual({ data: "x" });
+  });
+
+  it("makes flush idempotent", () => {
+    const decoder = new SSEEventDecoder({ trailing: "dispatch" });
+    decoder.push("data: x");
+    expect(decoder.flush()).toEqual({ data: "x" });
+    expect(decoder.flush()).toBeNull();
+  });
+});

package/src/core/utils/stream/SSEEventDecoder.ts

@@ -0,0 +1,109 @@
+export type SSEEvent = {
+  event?: string;
+  data: string;
+  id?: string;
+  retry?: number;
+};
+
+export class SSEEventDecoder {
+  private lineBuffer = "";
+  private dataLines: string[] = [];
+  private eventName: string | undefined;
+  private lastEventId: string | undefined;
+  private retry: number | undefined;
+  private pendingLF = false;
+  private readonly trailing: "drop" | "dispatch";
+
+  constructor(options?: { trailing?: "drop" | "dispatch" }) {
+    this.trailing = options?.trailing ?? "drop";
+  }
+
+  push(text: string): SSEEvent[] {
+    const events: SSEEvent[] = [];
+    if (text === "") return events;
+
+    // Lines end with LF, CRLF, or CR. A chunk-trailing "\r" terminates its
+    // line immediately; pendingLF then swallows the leading "\n" of the next
+    // chunk so a CRLF split across chunks is not counted twice.
+    if (this.pendingLF && text.startsWith("\n")) text = text.slice(1);
+    this.pendingLF = text.endsWith("\r");
+
+    this.lineBuffer += text;
+    const lines = this.lineBuffer.split(/\r\n|\r|\n/);
+    this.lineBuffer = lines.pop()!;
+
+    for (const line of lines) {
+      const event = this.processLine(line);
+      if (event) events.push(event);
+    }
+
+    return events;
+  }
+
+  flush(): SSEEvent | null {
+    if (this.trailing === "drop") {
+      this.resetFrame();
+      this.lineBuffer = "";
+      this.pendingLF = false;
+      return null;
+    }
+
+    if (this.lineBuffer.length > 0) {
+      this.processLine(this.lineBuffer);
+    }
+
+    this.lineBuffer = "";
+    this.pendingLF = false;
+    return this.dispatchEvent();
+  }
+
+  private processLine(line: string): SSEEvent | null {
+    if (line === "") return this.dispatchEvent();
+    if (line.startsWith(":")) return null;
+
+    const separator = line.indexOf(":");
+    const field = separator === -1 ? line : line.slice(0, separator);
+    let value = separator === -1 ? "" : line.slice(separator + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+
+    switch (field) {
+      case "data":
+        this.dataLines.push(value);
+        break;
+      case "event":
+        this.eventName = value;
+        break;
+      case "id":
+        if (!value.includes("\u0000")) this.lastEventId = value;
+        break;
+      case "retry": {
+        const retry = Number(value);
+        if (/^\d+$/.test(value) && Number.isSafeInteger(retry)) {
+          this.retry = retry;
+        }
+        break;
+      }
+    }
+
+    return null;
+  }
+
+  private dispatchEvent(): SSEEvent | null {
+    if (this.dataLines.length === 0) {
+      this.resetFrame();
+      return null;
+    }
+
+    const event: SSEEvent = { data: this.dataLines.join("\n") };
+    if (this.eventName !== undefined) event.event = this.eventName;
+    if (this.lastEventId !== undefined) event.id = this.lastEventId;
+    if (this.retry !== undefined) event.retry = this.retry;
+    this.resetFrame();
+    return event;
+  }
+
+  private resetFrame() {
+    this.dataLines = [];
+    this.eventName = undefined;
+  }
+}

package/src/core/utils/stream/SSEEventDecoderStream.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import {
+  SSEEventDecoderStream,
+  type PipelineSSEEvent,
+} from "./SSEEventDecoderStream";
+
+const collectEvents = async (chunks: string[]): Promise<PipelineSSEEvent[]> => {
+  const stream = new ReadableStream<string>({
+    start(controller) {
+      for (const chunk of chunks) controller.enqueue(chunk);
+      controller.close();
+    },
+  }).pipeThrough(new SSEEventDecoderStream());
+
+  const events: PipelineSSEEvent[] = [];
+  for await (const event of stream as unknown as AsyncIterable<PipelineSSEEvent>) {
+    events.push(event);
+  }
+  return events;
+};
+
+describe("SSEEventDecoderStream", () => {
+  it("defaults unnamed events to message", async () => {
+    const events = await collectEvents(["data: hello\n\n"]);
+    expect(events).toEqual([{ event: "message", data: "hello" }]);
+  });
+
+  it("normalizes an explicit empty event field to message", async () => {
+    const events = await collectEvents(["event:\ndata: hello\n\n"]);
+    expect(events).toEqual([{ event: "message", data: "hello" }]);
+  });
+
+  it("passes named events through", async () => {
+    const events = await collectEvents(["event: custom\ndata: hello\n\n"]);
+    expect(events).toEqual([{ event: "custom", data: "hello" }]);
+  });
+
+  it("drops an unterminated trailing frame", async () => {
+    const events = await collectEvents(["data: partial\n"]);
+    expect(events).toEqual([]);
+  });
+});

package/src/core/utils/stream/SSEEventDecoderStream.ts

@@ -0,0 +1,34 @@
+import { SSEEventDecoder } from "./SSEEventDecoder";
+import type { SSEEvent } from "./SSEEventDecoder";
+
+export type PipelineSSEEvent = {
+  event: string;
+  data: string;
+  id?: string;
+  retry?: number;
+};
+
+export class SSEEventDecoderStream extends TransformStream<
+  string,
+  PipelineSSEEvent
+> {
+  constructor() {
+    const decoder = new SSEEventDecoder({ trailing: "drop" });
+    const normalize = (event: SSEEvent): PipelineSSEEvent => ({
+      ...event,
+      event: event.event || "message",
+    });
+
+    super({
+      transform(chunk, controller) {
+        for (const event of decoder.push(chunk)) {
+          controller.enqueue(normalize(event));
+        }
+      },
+      flush(controller) {
+        const event = decoder.flush();
+        if (event) controller.enqueue(normalize(event));
+      },
+    });
+  }
+}

package/src/core/utils/stream/merge.ts

@@ -9,9 +9,18 @@ type MergeStreamItem = {
 export const createMergeStream = () => {
   const list: MergeStreamItem[] = [];
   let sealed = false;
+  let cancelled = false;
+  let errored = false;
   let controller: ReadableStreamDefaultController<AssistantStreamChunk>;
   let currentPull: ReturnType<typeof promiseWithResolvers<void>> | undefined;
 
+  const cancelAllReaders = () => {
+    list.forEach((item) => {
+      void item.reader.cancel().catch(() => undefined);
+    });
+    list.length = 0;
+  };
+
   const handlePull = (item: MergeStreamItem) => {
     if (!item.promise) {
       // TODO for most streams, we can directly pipeTo to avoid the microTask queue
@@ -23,6 +32,8 @@ export const createMergeStream = () => {
         .read()
         .then(({ done, value }) => {
           item.promise = undefined;
+          if (cancelled || errored) return;
+
           if (done) {
             list.splice(list.indexOf(item), 1);
             if (sealed && list.length === 0) {
@@ -36,12 +47,11 @@ export const createMergeStream = () => {
           currentPull = undefined;
         })
         .catch((e) => {
-          console.error(e);
+          if (cancelled || errored) return;
 
-          list.forEach((item) => {
-            item.reader.cancel();
-          });
-          list.length = 0;
+          errored = true;
+          console.error(e);
+          cancelAllReaders();
 
           controller.error(e);
 
@@ -64,10 +74,10 @@ export const createMergeStream = () => {
       return currentPull.promise;
     },
     cancel() {
-      list.forEach((item) => {
-        item.reader.cancel();
-      });
-      list.length = 0;
+      cancelled = true;
+      cancelAllReaders();
+      currentPull?.resolve();
+      currentPull = undefined;
     },
   });
 
@@ -76,11 +86,23 @@ export const createMergeStream = () => {
     isSealed() {
       return sealed;
     },
+    isCancelled() {
+      return cancelled;
+    },
+    isErrored() {
+      return errored;
+    },
     seal() {
+      if (cancelled || errored) return;
       sealed = true;
       if (list.length === 0) controller.close();
     },
     addStream(stream: ReadableStream<AssistantStreamChunk>) {
+      if (cancelled || errored) {
+        void stream.cancel().catch(() => undefined);
+        return;
+      }
+
       if (sealed)
         throw new Error(
           "Cannot add streams after the run callback has settled.",

package/src/gorp.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import * as entry from "./index";
+
+describe("assistant-transport state exports", () => {
+  it("exposes the assistant-transport surface and no gorp-shaped names", () => {
+    expect(typeof entry.AssistantTransportDeltaTracker).toBe("function");
+    expect(typeof entry.createObjectStream).toBe("function");
+    expect(typeof entry.ObjectStreamResponse).toBe("function");
+    expect(typeof entry.fromObjectStreamResponse).toBe("function");
+    for (const name of Object.keys(entry)) {
+      expect(name.toLowerCase()).not.toContain("gorp");
+    }
+  });
+
+  it("streams operations end to end through the SSE wire", async () => {
+    const stream = entry.createObjectStream({
+      execute: (controller) => {
+        controller.enqueue([
+          { type: "set", path: ["message"], value: "Hello" },
+        ]);
+        controller.enqueue([
+          { type: "append-text", path: ["message"], value: " World" },
+        ]);
+      },
+    });
+
+    const response = new entry.ObjectStreamResponse(stream);
+    const decoded = entry.fromObjectStreamResponse(response);
+
+    const tracker = new entry.AssistantTransportDeltaTracker();
+    const reader = decoded.getReader();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      tracker.append(value.operations);
+      expect(tracker.state).toEqual(value.snapshot);
+    }
+
+    expect(tracker.state).toEqual({ message: "Hello World" });
+    expect(tracker.isChangedAt(["message"])).toBe(true);
+  });
+});

package/src/index.ts

@@ -62,12 +62,27 @@ export {
 export type { TextStreamController } from "./core/modules/text";
 export type { ToolCallStreamController } from "./core/modules/tool-call";
 
-export { createObjectStream } from "./core/object/createObjectStream";
-export {
-  ObjectStreamResponse,
-  fromObjectStreamResponse,
-} from "./core/object/ObjectStreamResponse";
-export type { ObjectStreamChunk } from "./core/object/types";
+import { createGorpStream } from "./core/gorp/createGorpStream";
+import {
+  GorpStreamResponse,
+  fromGorpStreamResponse,
+} from "./core/gorp/GorpStreamResponse";
+import type { GorpStreamChunk } from "./core/gorp/types";
+import { GorpStreamDeltaTracker } from "./core/gorp/GorpStreamDeltaTracker";
+
+export { GorpStreamDeltaTracker as AssistantTransportDeltaTracker };
+export type { AssistantTransportStateOperation } from "./core/gorp/types";
+
+/** @deprecated Use the assistant-transport surface instead. */
+export const createObjectStream = createGorpStream;
+/** @deprecated Use the assistant-transport surface instead. */
+export const ObjectStreamResponse = GorpStreamResponse;
+/** @deprecated Use the assistant-transport surface instead. */
+export type ObjectStreamResponse = GorpStreamResponse;
+/** @deprecated Use the assistant-transport surface instead. */
+export const fromObjectStreamResponse = fromGorpStreamResponse;
+/** @deprecated Use the assistant-transport surface instead. */
+export type ObjectStreamChunk = GorpStreamChunk;
 
 export {
   toGenericMessages,