assistant-stream 0.3.26 → 0.3.27

package/src/core/gorp/GorpStreamDeltaTracker.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, it } from "vitest";
+import { GorpStreamDeltaTracker } from "./GorpStreamDeltaTracker";
+import { createGorpStream } from "./createGorpStream";
+import type { ReadonlyJSONObject } from "../../utils";
+
+describe("GorpStreamDeltaTracker frames", () => {
+  it("reports ops of the current frame in getChangedKeys", () => {
+    const tracker = new GorpStreamDeltaTracker({ items: {} });
+    tracker.append([
+      { type: "set", path: ["items", "a"], value: { name: "alpha" } },
+    ]);
+    expect(tracker.getChangedKeys(["items"])).toEqual(["a"]);
+    expect((tracker.state as ReadonlyJSONObject).items).toEqual({
+      a: { name: "alpha" },
+    });
+  });
+
+  it("opens a separate frame per append", () => {
+    const tracker = new GorpStreamDeltaTracker({ items: {} });
+    tracker.append([
+      { type: "set", path: ["items", "a"], value: { name: "alpha" } },
+    ]);
+    tracker.append([
+      { type: "set", path: ["items", "b"], value: { name: "beta" } },
+    ]);
+    expect(tracker.getChangedKeys(["items"])).toEqual(["b"]);
+    expect(tracker.isChangedAt(["items", "a"])).toBe(false);
+  });
+
+  it("reports an empty change set before the first append and after an empty append", () => {
+    const tracker = new GorpStreamDeltaTracker({ count: 0 });
+    expect(tracker.isChangedAt([])).toBe(false);
+    expect(tracker.isChangedAt(["count"])).toBe(false);
+    expect(tracker.getChangedKeys([])).toEqual([]);
+    tracker.append([{ type: "set", path: ["count"], value: 1 }]);
+    expect(tracker.isChangedAt([])).toBe(true);
+    tracker.append([]);
+    expect(tracker.isChangedAt([])).toBe(false);
+    expect(tracker.isChangedAt(["count"])).toBe(false);
+    expect(tracker.getChangedKeys([])).toEqual([]);
+  });
+});
+
+describe("GorpStreamDeltaTracker isChangedAt", () => {
+  it("returns truthy for any path inside a marked subtree", () => {
+    const tracker = new GorpStreamDeltaTracker();
+    tracker.append([{ type: "set", path: [], value: { items: {} } }]);
+    expect(tracker.isChangedAt([])).toBe(true);
+    expect(tracker.isChangedAt(["items"])).toBe(true);
+    expect(tracker.isChangedAt(["items", "anything", "deep"])).toBe(true);
+  });
+
+  it("returns true for ancestors of a changed path and false for siblings", () => {
+    const tracker = new GorpStreamDeltaTracker({ a: { b: "x" }, c: "y" });
+    tracker.append([{ type: "set", path: ["a", "b"], value: "z" }]);
+    expect(tracker.isChangedAt([])).toBe(true);
+    expect(tracker.isChangedAt(["a"])).toBe(true);
+    expect(tracker.isChangedAt(["a", "b"])).toBe(true);
+    expect(tracker.isChangedAt(["c"])).toBe(false);
+  });
+
+  it("marks append-text targets as changed", () => {
+    const tracker = new GorpStreamDeltaTracker({ message: "Hello" });
+    tracker.append([{ type: "append-text", path: ["message"], value: "!" }]);
+    expect(tracker.isChangedAt(["message"])).toBe(true);
+    expect(tracker.getChangedKeys([])).toEqual(["message"]);
+    expect((tracker.state as ReadonlyJSONObject).message).toBe("Hello!");
+  });
+});
+
+describe("GorpStreamDeltaTracker getChangedKeys", () => {
+  it("diffs keys against the previous frame when a subtree is fully replaced", () => {
+    const tracker = new GorpStreamDeltaTracker({ count: 0, items: {} });
+    tracker.append([
+      { type: "set", path: ["items", "a"], value: { name: "alpha" } },
+    ]);
+    tracker.append([
+      { type: "set", path: ["items", "b"], value: { name: "beta" } },
+    ]);
+    tracker.append([
+      {
+        type: "set",
+        path: [],
+        value: {
+          count: 99,
+          items: { b: { name: "beta-new" }, c: { name: "gamma" } },
+        },
+      },
+    ]);
+    expect(tracker.getChangedKeys(["items"])).toEqual(["b", "c", "a"]);
+  });
+
+  it("returns interior node keys for a partially changed subtree", () => {
+    const tracker = new GorpStreamDeltaTracker({ items: { a: 1, b: 2 } });
+    tracker.append([
+      { type: "set", path: ["items", "a"], value: 10 },
+      { type: "set", path: ["items", "c"], value: 3 },
+    ]);
+    expect(tracker.getChangedKeys(["items"])).toEqual(["a", "c"]);
+    expect(tracker.getChangedKeys([])).toEqual(["items"]);
+    expect(tracker.getChangedKeys(["other"])).toEqual([]);
+  });
+
+  it("diffs keys when the previous value at a replaced path was not an object", () => {
+    const tracker = new GorpStreamDeltaTracker({ value: "initial" });
+    tracker.append([{ type: "set", path: ["value"], value: { nested: true } }]);
+    expect(tracker.getChangedKeys(["value"])).toEqual(["nested"]);
+  });
+});
+
+describe("GorpStreamDeltaTracker inherited object members", () => {
+  it("does not treat inherited members as changes on a fresh tracker", () => {
+    const tracker = new GorpStreamDeltaTracker({ items: {} });
+    expect(tracker.isChangedAt(["toString"])).toBe(false);
+    expect(tracker.isChangedAt(["hasOwnProperty"])).toBe(false);
+    expect(tracker.getChangedKeys(["toString"])).toEqual([]);
+  });
+
+  it("does not treat inherited members as changes on a populated tree", () => {
+    const tracker = new GorpStreamDeltaTracker({ items: {} });
+    tracker.append([{ type: "set", path: ["items", "a"], value: 1 }]);
+    expect(tracker.isChangedAt(["toString"])).toBe(false);
+    expect(tracker.isChangedAt(["items", "toString"])).toBe(false);
+    expect(tracker.isChangedAt(["items", "valueOf", "deep"])).toBe(false);
+    expect(tracker.getChangedKeys([])).toEqual(["items"]);
+    expect(tracker.getChangedKeys(["items"])).toEqual(["a"]);
+  });
+});
+
+describe("GorpStreamDeltaTracker failed append", () => {
+  it("leaves state and the change frame untouched when an operation throws", () => {
+    const tracker = new GorpStreamDeltaTracker({ count: 5, message: "hi" });
+    tracker.append([{ type: "set", path: ["message"], value: "hello" }]);
+    const stateBefore = tracker.state;
+
+    expect(() =>
+      tracker.append([
+        { type: "set", path: ["other"], value: 1 },
+        { type: "append-text", path: ["count"], value: "!" },
+      ]),
+    ).toThrow(/Expected string/);
+
+    expect(tracker.state).toBe(stateBefore);
+    expect(tracker.isChangedAt(["message"])).toBe(true);
+    expect(tracker.isChangedAt(["other"])).toBe(false);
+    expect(tracker.isChangedAt(["count"])).toBe(false);
+    expect(tracker.getChangedKeys([])).toEqual(["message"]);
+  });
+});
+
+describe("GorpStreamDeltaTracker streamed accumulation", () => {
+  it("tracks one frame per streamed chunk", async () => {
+    const stream = createGorpStream({
+      execute: (controller) => {
+        controller.enqueue([
+          { type: "set", path: ["user"], value: { name: "Initial" } },
+        ]);
+        controller.enqueue([
+          { type: "set", path: ["user", "name"], value: "Updated" },
+          { type: "set", path: ["user", "email"], value: "user@example.com" },
+        ]);
+        controller.enqueue([
+          { type: "set", path: ["status"], value: "complete" },
+        ]);
+      },
+    });
+
+    const tracker = new GorpStreamDeltaTracker();
+    const frames: string[][] = [];
+    for await (const chunk of stream) {
+      tracker.append(chunk.operations);
+      frames.push(tracker.getChangedKeys(["user"]));
+      expect(tracker.state).toEqual(chunk.snapshot);
+    }
+
+    expect(frames).toEqual([["name"], ["name", "email"], []]);
+    expect(tracker.state).toEqual({
+      user: { name: "Updated", email: "user@example.com" },
+      status: "complete",
+    });
+  });
+});

package/src/core/gorp/GorpStreamDeltaTracker.ts

@@ -0,0 +1,55 @@
+import type { ReadonlyJSONValue } from "../../utils";
+import { GorpStreamAccumulator } from "./GorpStreamAccumulator";
+import type { GorpStreamOperation } from "./types";
+import {
+  type ChangeNode,
+  createChangeNode,
+  diffKeys,
+  lookupChange,
+  lookupValue,
+  markChanged,
+} from "./changeTree";
+
+export class GorpStreamDeltaTracker {
+  private readonly accumulator: GorpStreamAccumulator;
+  private previousState: ReadonlyJSONValue;
+  private changes: ChangeNode = createChangeNode();
+
+  constructor(initialValue: ReadonlyJSONValue = null) {
+    this.accumulator = new GorpStreamAccumulator(initialValue);
+    this.previousState = this.accumulator.state;
+  }
+
+  get state(): ReadonlyJSONValue {
+    return this.accumulator.state;
+  }
+
+  append(operations: readonly GorpStreamOperation[]): void {
+    const previousState = this.accumulator.state;
+    let changes: ChangeNode = createChangeNode();
+    for (const op of operations) {
+      changes = markChanged(changes, op.path);
+    }
+    this.accumulator.append(operations);
+    this.previousState = previousState;
+    this.changes = changes;
+  }
+
+  isChangedAt(path: readonly string[]): boolean {
+    const node = lookupChange(this.changes, path);
+    if (node === true) return true;
+    return node !== false && Object.keys(node).length > 0;
+  }
+
+  getChangedKeys(path: readonly string[]): string[] {
+    const node = lookupChange(this.changes, path);
+    if (node === false) return [];
+    if (node === true) {
+      return diffKeys(
+        lookupValue(this.accumulator.state, path),
+        lookupValue(this.previousState, path),
+      );
+    }
+    return Object.keys(node);
+  }
+}

package/src/core/{object/ObjectStreamResponse.test.ts → gorp/GorpStreamResponse.test.ts}

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { fromObjectStreamResponse } from "./ObjectStreamResponse";
+import { fromGorpStreamResponse } from "./GorpStreamResponse";
 
 const createResponse = (contentType?: string) => {
   const headers = new Headers({
@@ -10,23 +10,23 @@ const createResponse = (contentType?: string) => {
   return new Response(new Uint8Array(), { headers });
 };
 
-describe("fromObjectStreamResponse", () => {
+describe("fromGorpStreamResponse", () => {
   it.each([
     "text/event-stream",
     "text/event-stream; charset=utf-8",
     "Text/Event-Stream; Charset=UTF-8",
   ])("accepts the event-stream content type %s", (contentType) => {
     expect(() =>
-      fromObjectStreamResponse(createResponse(contentType)),
+      fromGorpStreamResponse(createResponse(contentType)),
     ).not.toThrow();
   });
 
   it.each([undefined, "application/json", "text/event-streaming"])(
     "rejects the content type %s",
     (contentType) => {
-      expect(() =>
-        fromObjectStreamResponse(createResponse(contentType)),
-      ).toThrow("Response is not an event stream");
+      expect(() => fromGorpStreamResponse(createResponse(contentType))).toThrow(
+        "Response is not an event stream",
+      );
     },
   );
 });

package/src/core/gorp/GorpStreamResponse.ts

@@ -0,0 +1,88 @@
+import { PipeableTransformStream } from "../utils/stream/PipeableTransformStream";
+import { GorpStreamAccumulator } from "./GorpStreamAccumulator";
+import { SSEDecoder, SSEEncoder } from "../utils/stream/SSE";
+import type { GorpStreamChunk, GorpStreamOperation } from "./types";
+
+export class GorpStreamEncoder extends PipeableTransformStream<
+  GorpStreamChunk,
+  Uint8Array
+> {
+  constructor() {
+    let isFirstChunk = true;
+    super((readable) =>
+      readable
+        .pipeThrough(
+          new TransformStream<GorpStreamChunk, readonly GorpStreamOperation[]>({
+            transform(chunk, controller) {
+              if (isFirstChunk) {
+                controller.enqueue([
+                  { type: "set", path: [], value: chunk.snapshot },
+                ]);
+              } else {
+                controller.enqueue(chunk.operations);
+              }
+              isFirstChunk = false;
+            },
+          }),
+        )
+        .pipeThrough(new SSEEncoder()),
+    );
+  }
+}
+
+export class GorpStreamDecoder extends PipeableTransformStream<
+  Uint8Array<ArrayBuffer>,
+  GorpStreamChunk
+> {
+  constructor() {
+    const accumulator = new GorpStreamAccumulator();
+    super((readable) =>
+      readable
+        .pipeThrough(new SSEDecoder<readonly GorpStreamOperation[]>())
+        .pipeThrough(
+          new TransformStream<readonly GorpStreamOperation[], GorpStreamChunk>({
+            transform(operations, controller) {
+              accumulator.append(operations);
+              controller.enqueue({
+                snapshot: accumulator.state,
+                operations,
+              });
+            },
+          }),
+        ),
+    );
+  }
+}
+
+export class GorpStreamResponse extends Response {
+  constructor(body: ReadableStream<GorpStreamChunk>) {
+    super(body.pipeThrough(new GorpStreamEncoder()), {
+      headers: new Headers({
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+        "Assistant-Stream-Format": "object-stream/v0",
+      }),
+    });
+  }
+}
+
+export const fromGorpStreamResponse = (
+  response: Response,
+): ReadableStream<GorpStreamChunk> => {
+  if (!response.ok)
+    throw new Error(`Response failed, status ${response.status}`);
+  if (!response.body) throw new Error("Response body is null");
+  const mediaType = response.headers
+    .get("Content-Type")
+    ?.split(";", 1)[0]
+    ?.trim()
+    .toLowerCase();
+  if (mediaType !== "text/event-stream") {
+    throw new Error("Response is not an event stream");
+  }
+  if (response.headers.get("Assistant-Stream-Format") !== "object-stream/v0") {
+    throw new Error("Unsupported Assistant-Stream-Format header");
+  }
+  return response.body.pipeThrough(new GorpStreamDecoder());
+};

package/src/core/gorp/changeTree.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from "vitest";
+import {
+  diffKeys,
+  lookupChange,
+  markChanged,
+  mergeChanged,
+  type ChangeNode,
+} from "./changeTree";
+
+describe("markChanged", () => {
+  it("collapses to true when path is empty", () => {
+    expect(markChanged({}, [])).toBe(true);
+  });
+
+  it("keeps `true` after attempting to descend into it", () => {
+    const node: ChangeNode = { a: true };
+    const result = markChanged(node, ["a", "b"]);
+    expect(result).toBe(node);
+    expect(node.a).toBe(true);
+  });
+
+  it("overwrites a nested subtree with `true` when the path collapses to the parent", () => {
+    const node: ChangeNode = { a: { b: true } };
+    markChanged(node, ["a"]);
+    expect(node.a).toBe(true);
+  });
+
+  it("creates intermediate nodes lazily without disturbing siblings", () => {
+    const node: ChangeNode = { a: { existing: true } };
+    markChanged(node, ["a", "b", "c"]);
+    expect(node).toEqual({
+      a: { existing: true, b: { c: true } },
+    });
+  });
+
+  it("is idempotent when the same leaf is marked twice", () => {
+    const node: ChangeNode = {};
+    markChanged(node, ["a", "b"]);
+    markChanged(node, ["a", "b"]);
+    expect(node).toEqual({ a: { b: true } });
+  });
+
+  it("rejects unsafe path segments", () => {
+    const node: ChangeNode = {};
+    expect(() => markChanged(node, ["__proto__", "polluted"])).toThrow(
+      /Unsafe gorp path segment/,
+    );
+    expect(({} as Record<string, unknown>).polluted).toBeUndefined();
+  });
+});
+
+describe("mergeChanged", () => {
+  it("returns true when either side is true", () => {
+    expect(mergeChanged(true, {})).toBe(true);
+    expect(mergeChanged({}, true)).toBe(true);
+  });
+
+  it("merges disjoint subtrees in place", () => {
+    const target: ChangeNode = { a: true };
+    const source: ChangeNode = { b: true };
+    const result = mergeChanged(target, source);
+    expect(result).toBe(target);
+    expect(target).toEqual({ a: true, b: true });
+  });
+
+  it("clones source subtrees before assigning them", () => {
+    const target: ChangeNode = {};
+    const source: ChangeNode = { a: { b: true } };
+    mergeChanged(target, source);
+    (source as { a: { c?: true } }).a.c = true;
+    expect(target).toEqual({ a: { b: true } });
+  });
+
+  it("deep-merges overlapping subtrees", () => {
+    const target: ChangeNode = { a: { x: true } };
+    const source: ChangeNode = { a: { y: true } };
+    mergeChanged(target, source);
+    expect(target).toEqual({ a: { x: true, y: true } });
+  });
+
+  it("propagates `true` upward when one side has it at a shared key", () => {
+    const target: ChangeNode = { a: { x: true } };
+    const source: ChangeNode = { a: true };
+    mergeChanged(target, source);
+    expect(target).toEqual({ a: true });
+  });
+
+  it("rejects unsafe source keys", () => {
+    const target: ChangeNode = {};
+    const source = JSON.parse('{"__proto__":true}') as ChangeNode;
+    expect(() => mergeChanged(target, source)).toThrow(
+      /Unsafe gorp path segment/,
+    );
+    expect(({} as Record<string, unknown>).polluted).toBeUndefined();
+  });
+
+  it("rejects nested unsafe source keys before assigning a subtree", () => {
+    const target: ChangeNode = {};
+    const source = JSON.parse('{"a":{"constructor":true}}') as ChangeNode;
+    expect(() => mergeChanged(target, source)).toThrow(
+      /Unsafe gorp path segment/,
+    );
+  });
+});
+
+describe("lookupChange", () => {
+  it("returns false for paths that don't exist", () => {
+    expect(lookupChange({ a: true }, ["b"])).toBe(false);
+  });
+
+  it("returns true when traversal hits a `true` sentinel", () => {
+    expect(lookupChange({ a: true }, ["a", "b", "c"])).toBe(true);
+  });
+
+  it("returns the subtree when the path lands on an interior node", () => {
+    const node: ChangeNode = { a: { b: true } };
+    const result = lookupChange(node, ["a"]);
+    expect(result).toEqual({ b: true });
+  });
+
+  it("returns the root node for the empty path", () => {
+    const node: ChangeNode = { a: true };
+    expect(lookupChange(node, [])).toBe(node);
+  });
+
+  it("returns false for inherited object members", () => {
+    expect(lookupChange({}, ["toString"])).toBe(false);
+    expect(lookupChange({ a: {} }, ["a", "hasOwnProperty"])).toBe(false);
+    expect(lookupChange({ a: true }, ["constructor"])).toBe(false);
+  });
+});
+
+describe("inherited object members", () => {
+  it("markChanged does not descend into inherited members", () => {
+    const node: ChangeNode = {};
+    markChanged(node, ["toString", "x"]);
+    expect(node).toEqual({ toString: { x: true } });
+    expect(lookupChange(node, ["toString", "x"])).toBe(true);
+    expect(lookupChange(node, ["valueOf"])).toBe(false);
+  });
+
+  it("mergeChanged ignores inherited target members", () => {
+    const target: ChangeNode = {};
+    const source: ChangeNode = { toString: { x: true } };
+    mergeChanged(target, source);
+    expect(target).toEqual({ toString: { x: true } });
+  });
+});
+
+describe("diffKeys", () => {
+  it("returns new keys in order, then deleted keys in reverse", () => {
+    expect(diffKeys({ b: 1, c: 2 }, { a: 1, b: 2, d: 3 })).toEqual([
+      "b",
+      "c",
+      "d",
+      "a",
+    ]);
+  });
+
+  it("returns new keys when the old value is not an object", () => {
+    expect(diffKeys({ a: 1 }, null)).toEqual(["a"]);
+    expect(diffKeys({ a: 1 }, "str")).toEqual(["a"]);
+  });
+
+  it("returns deleted keys when the new value is not an object", () => {
+    expect(diffKeys(null, { a: 1, b: 2 })).toEqual(["b", "a"]);
+  });
+});

package/src/core/gorp/changeTree.ts

@@ -0,0 +1,96 @@
+export type ChangeNode = true | { [key: string]: ChangeNode };
+
+export function createChangeNode(): { [key: string]: ChangeNode } {
+  return Object.create(null);
+}
+
+const UNSAFE_PATH_SEGMENTS = new Set(["__proto__", "constructor", "prototype"]);
+
+export function assertSafePathSegment(segment: string): void {
+  if (UNSAFE_PATH_SEGMENTS.has(segment)) {
+    throw new Error(`Unsafe gorp path segment: ${segment}`);
+  }
+}
+
+export function markChanged(
+  node: ChangeNode,
+  path: readonly string[],
+): ChangeNode {
+  if (node === true || path.length === 0) return true;
+  let cursor = node;
+  for (let i = 0; i < path.length - 1; i++) {
+    const key = path[i]!;
+    assertSafePathSegment(key);
+    const next = Object.hasOwn(cursor, key) ? cursor[key] : undefined;
+    if (next === true) return node;
+    if (next === undefined) cursor[key] = createChangeNode();
+    cursor = cursor[key] as { [k: string]: ChangeNode };
+  }
+  const leaf = path[path.length - 1]!;
+  assertSafePathSegment(leaf);
+  cursor[leaf] = true;
+  return node;
+}
+
+export function mergeChanged(
+  target: ChangeNode,
+  source: ChangeNode,
+): ChangeNode {
+  if (target === true || source === true) return true;
+  for (const key of Object.keys(source)) {
+    assertSafePathSegment(key);
+    const sChild = source[key]!;
+    const tChild = Object.hasOwn(target, key) ? target[key] : undefined;
+    target[key] =
+      tChild === undefined
+        ? cloneChangeNode(sChild)
+        : mergeChanged(tChild, sChild);
+  }
+  return target;
+}
+
+function cloneChangeNode(source: ChangeNode): ChangeNode {
+  if (source === true) return true;
+  const clone = createChangeNode();
+  for (const key of Object.keys(source)) {
+    assertSafePathSegment(key);
+    clone[key] = cloneChangeNode(source[key]!);
+  }
+  return clone;
+}
+
+export function lookupChange(
+  node: ChangeNode,
+  path: readonly string[],
+): ChangeNode | false {
+  for (const key of path) {
+    if (node === true) return true;
+    const next = Object.hasOwn(node, key) ? node[key] : undefined;
+    if (next === undefined) return false;
+    node = next;
+  }
+  return node;
+}
+
+export function lookupValue(state: unknown, path: readonly string[]): unknown {
+  let node = state;
+  for (const key of path) {
+    assertSafePathSegment(key);
+    if (typeof node !== "object" || node === null) return undefined;
+    node = Object.hasOwn(node, key)
+      ? (node as Record<string, unknown>)[key]
+      : undefined;
+  }
+  return node;
+}
+
+export function diffKeys(newNode: unknown, oldNode: unknown): string[] {
+  const newKeys =
+    typeof newNode === "object" && newNode !== null ? Object.keys(newNode) : [];
+  const oldKeys =
+    typeof oldNode === "object" && oldNode !== null ? Object.keys(oldNode) : [];
+  if (oldKeys.length === 0) return newKeys;
+  const newSet = new Set(newKeys);
+  const deletedKeys = oldKeys.filter((k) => !newSet.has(k)).reverse();
+  return [...newKeys, ...deletedKeys];
+}