assistant-stream 0.2.6 → 0.2.7

package/dist/core/utils/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/utils/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/utils/types.ts"],"names":[],"mappings":"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"}

package/dist/utils/index.d.ts

@@ -1,3 +1,3 @@
-export { asAsyncIterableStream, type AsyncIterableStream } from "./AsyncIterableStream";
+export { asAsyncIterableStream, type AsyncIterableStream, } from "./AsyncIterableStream";
 export { type ReadonlyJSONObject, type ReadonlyJSONValue } from "./json";
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACxF,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,KAAK,mBAAmB,GACzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,QAAQ,CAAC"}

package/dist/utils/index.js

@@ -1,5 +1,7 @@
 // src/utils/index.ts
-import { asAsyncIterableStream } from "./AsyncIterableStream.js";
+import {
+  asAsyncIterableStream
+} from "./AsyncIterableStream.js";
 export {
   asAsyncIterableStream
 };

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/index.ts"],"sourcesContent":["export { asAsyncIterableStream, type AsyncIterableStream } from \"./AsyncIterableStream\";\nexport { type ReadonlyJSONObject, type ReadonlyJSONValue } from \"./json\";\n"],"mappings":";AAAA,SAAS,6BAAuD;","names":[]}
+{"version":3,"sources":["../../src/utils/index.ts"],"sourcesContent":["export {\n  asAsyncIterableStream,\n  type AsyncIterableStream,\n} from \"./AsyncIterableStream\";\nexport { type ReadonlyJSONObject, type ReadonlyJSONValue } from \"./json\";\n"],"mappings":";AAAA;AAAA,EACE;AAAA,OAEK;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assistant-stream",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/core/AssistantStreamChunk.ts

@@ -1,4 +1,5 @@
 import { ReadonlyJSONValue } from "../utils/json/json-value";
+import { ObjectStreamOperation } from "./object/types";
 
 export type PartInit =
   | {
@@ -82,7 +83,7 @@ export type AssistantStreamChunk = { readonly path: readonly number[] } & (
     }
   | {
       readonly type: "result";
-      readonly artifact?: ReadonlyJSONValue | undefined;
+      readonly artifact?: ReadonlyJSONValue;
       readonly result: ReadonlyJSONValue;
       readonly isError: boolean;
     }
@@ -90,4 +91,8 @@ export type AssistantStreamChunk = { readonly path: readonly number[] } & (
       readonly type: "error";
       readonly error: string;
     }
+  | {
+      readonly type: "update-state";
+      readonly operations: ObjectStreamOperation[];
+    }
 );

package/src/core/accumulators/AssistantMessageStream.ts

@@ -26,6 +26,7 @@ export class AssistantMessageStream {
         parts: [],
         content: [],
         metadata: {
+          unstable_state: null,
           unstable_data: [],
           unstable_annotations: [],
           steps: [],

package/src/core/accumulators/assistant-message-accumulator.ts

@@ -11,6 +11,7 @@ import {
   ReasoningPart,
   FilePart,
 } from "../utils/types";
+import { ObjectStreamAccumulator } from "../object/ObjectStreamAccumulator";
 
 const createInitialMessage = (): AssistantMessage => ({
   role: "assistant",
@@ -20,6 +21,7 @@ const createInitialMessage = (): AssistantMessage => ({
     return this.parts;
   },
   metadata: {
+    unstable_state: null,
     unstable_data: [],
     unstable_annotations: [],
     steps: [],
@@ -132,6 +134,9 @@ const handleToolCallArgsTextFinish = (
     if (part.type !== "tool-call") {
       throw new Error("Last is not a tool call");
     }
+    if (part.state !== "partial-call")
+      throw new Error("Last is not a partial call");
+
     return {
       ...part,
       state: "call",
@@ -180,7 +185,7 @@ const handleResult = (
       return {
         ...part,
         state: "result",
-        artifact: chunk.artifact,
+        ...(chunk.artifact !== undefined ? { artifact: chunk.artifact } : {}),
         result: chunk.result,
         isError: chunk.isError ?? false,
         status: { type: "complete", reason: "stop" },
@@ -316,6 +321,22 @@ const handleErrorChunk = (
   };
 };
 
+const handleUpdateState = (
+  message: AssistantMessage,
+  chunk: AssistantStreamChunk & { type: "update-state" },
+): AssistantMessage => {
+  const acc = new ObjectStreamAccumulator(message.metadata.unstable_state);
+  acc.append(chunk.operations);
+
+  return {
+    ...message,
+    metadata: {
+      ...message.metadata,
+      unstable_state: acc.state,
+    },
+  };
+};
+
 export class AssistantMessageAccumulator extends TransformStream<
   AssistantStreamChunk,
   AssistantMessage
@@ -366,6 +387,9 @@ export class AssistantMessageAccumulator extends TransformStream<
           case "error":
             message = handleErrorChunk(message, chunk);
             break;
+          case "update-state":
+            message = handleUpdateState(message, chunk);
+            break;
           default: {
             const unhandledType: never = type;
             throw new Error(`Unsupported chunk type: ${unhandledType}`);

package/src/core/index.ts

@@ -15,3 +15,10 @@ export { AssistantMessageStream } from "./accumulators/AssistantMessageStream";
 export type { AssistantMessage } from "./utils/types";
 
 export * from "./tool";
+
+export { createObjectStream } from "./object/createObjectStream";
+export {
+  ObjectStreamResponse,
+  fromObjectStreamResponse,
+} from "./object/ObjectStreamResponse";
+export type { ObjectStreamChunk } from "./object/types";

package/src/core/modules/tool-call.ts

@@ -57,7 +57,9 @@ class ToolCallStreamControllerImpl implements ToolCallStreamController {
     this._controller.enqueue({
       type: "result",
       path: [],
-      artifact: response.artifact,
+      ...(response.artifact !== undefined
+        ? { artifact: response.artifact }
+        : {}),
       result: response.result,
       isError: response.isError ?? false,
     });

package/src/core/object/ObjectStream.test.ts

@@ -0,0 +1,376 @@
+import { describe, expect, it } from "vitest";
+import { createObjectStream } from "./createObjectStream";
+import {
+  ObjectStreamEncoder,
+  ObjectStreamDecoder,
+} from "./ObjectStreamResponse";
+import { ReadonlyJSONValue } from "../../utils";
+import { ObjectStreamChunk } from "./types";
+
+// Helper function to collect all chunks from a stream
+async function collectChunks<T>(stream: ReadableStream<T>): Promise<T[]> {
+  const reader = stream.getReader();
+  const chunks: T[] = [];
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  return chunks;
+}
+
+// Helper function to encode and decode a stream
+async function encodeAndDecode(
+  stream: ReadableStream<ObjectStreamChunk>,
+): Promise<ReadableStream<ObjectStreamChunk>> {
+  // Encode the stream to Uint8Array (simulating network transmission)
+  const encodedStream = stream.pipeThrough(new ObjectStreamEncoder());
+
+  // Collect all encoded chunks
+  const encodedChunks = await collectChunks(encodedStream);
+
+  // Create a new stream from the encoded chunks
+  const reconstructedStream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const chunk of encodedChunks) {
+        controller.enqueue(chunk);
+      }
+      controller.close();
+    },
+  });
+
+  // Decode the stream back to ObjectStreamChunk
+  return reconstructedStream.pipeThrough(new ObjectStreamDecoder());
+}
+
+describe("ObjectStream serialization and deserialization", () => {
+  it("should correctly serialize and deserialize simple objects", async () => {
+    // Create an object stream with simple operations
+    const stream = createObjectStream({
+      execute: (controller) => {
+        controller.enqueue([
+          { type: "set", path: ["name"], value: "John" },
+          { type: "set", path: ["age"], value: 30 },
+        ]);
+      },
+    });
+
+    // Encode and decode the stream
+    const decodedStream = await encodeAndDecode(stream);
+
+    // Collect all chunks from the decoded stream
+    const chunks = await collectChunks(decodedStream);
+
+    // Verify the final state
+    const finalChunk = chunks[chunks.length - 1]!;
+    expect(finalChunk.snapshot).toEqual({
+      name: "John",
+      age: 30,
+    });
+  });
+
+  it("should correctly handle nested objects", async () => {
+    const stream = createObjectStream({
+      execute: (controller) => {
+        controller.enqueue([
+          { type: "set", path: ["user", "profile", "name"], value: "Jane" },
+          {
+            type: "set",
+            path: ["user", "profile", "email"],
+            value: "jane@example.com",
+          },
+          { type: "set", path: ["user", "settings", "theme"], value: "dark" },
+        ]);
+      },
+    });
+
+    const decodedStream = await encodeAndDecode(stream);
+    const chunks = await collectChunks(decodedStream);
+    const finalChunk = chunks[chunks.length - 1]!;
+
+    expect(finalChunk.snapshot).toEqual({
+      user: {
+        profile: {
+          name: "Jane",
+          email: "jane@example.com",
+        },
+        settings: {
+          theme: "dark",
+        },
+      },
+    });
+  });
+
+  it("should correctly handle arrays", async () => {
+    const stream = createObjectStream({
+      execute: (controller) => {
+        controller.enqueue([
+          { type: "set", path: ["items"], value: [] },
+          { type: "set", path: ["items", "0"], value: "apple" },
+          { type: "set", path: ["items", "1"], value: "banana" },
+          { type: "set", path: ["items", "2"], value: "cherry" },
+        ]);
+      },
+    });
+
+    const decodedStream = await encodeAndDecode(stream);
+    const chunks = await collectChunks(decodedStream);
+    const finalChunk = chunks[chunks.length - 1]!;
+
+    expect(finalChunk.snapshot).toEqual({
+      items: ["apple", "banana", "cherry"],
+    });
+  });
+
+  it("should correctly handle mixed arrays and objects", async () => {
+    const stream = createObjectStream({
+      execute: (controller) => {
+        controller.enqueue([
+          { type: "set", path: ["users"], value: [] },
+          { type: "set", path: ["users", "0"], value: {} },
+          { type: "set", path: ["users", "0", "id"], value: 1 },
+          { type: "set", path: ["users", "0", "name"], value: "Alice" },
+          { type: "set", path: ["users", "1"], value: {} },
+          { type: "set", path: ["users", "1", "id"], value: 2 },
+          { type: "set", path: ["users", "1", "name"], value: "Bob" },
+        ]);
+      },
+    });
+
+    const decodedStream = await encodeAndDecode(stream);
+    const chunks = await collectChunks(decodedStream);
+    const finalChunk = chunks[chunks.length - 1]!;
+
+    expect(finalChunk.snapshot).toEqual({
+      users: [
+        { id: 1, name: "Alice" },
+        { id: 2, name: "Bob" },
+      ],
+    });
+  });
+
+  it("should correctly handle append-text operations", async () => {
+    const stream = createObjectStream({
+      execute: (controller) => {
+        controller.enqueue([
+          { type: "set", path: ["message"], value: "Hello" },
+          { type: "append-text", path: ["message"], value: " " },
+          { type: "append-text", path: ["message"], value: "World" },
+          { type: "append-text", path: ["message"], value: "!" },
+        ]);
+      },
+    });
+
+    const decodedStream = await encodeAndDecode(stream);
+    const chunks = await collectChunks(decodedStream);
+    const finalChunk = chunks[chunks.length - 1]!;
+
+    expect(finalChunk.snapshot).toEqual({
+      message: "Hello World!",
+    });
+  });
+
+  it("should correctly handle special characters and Unicode", async () => {
+    const stream = createObjectStream({
+      execute: (controller) => {
+        controller.enqueue([
+          {
+            type: "set",
+            path: ["special"],
+            value: "Special chars: !@#$%^&*()",
+          },
+          { type: "set", path: ["unicode"], value: "Unicode: 😀🌍🚀" },
+          { type: "set", path: ["quotes"], value: "Quotes: \"'`" },
+          {
+            type: "set",
+            path: ["newlines"],
+            value: "Line 1\nLine 2\r\nLine 3",
+          },
+        ]);
+      },
+    });
+
+    const decodedStream = await encodeAndDecode(stream);
+    const chunks = await collectChunks(decodedStream);
+    const finalChunk = chunks[chunks.length - 1]!;
+
+    expect(finalChunk.snapshot).toEqual({
+      special: "Special chars: !@#$%^&*()",
+      unicode: "Unicode: 😀🌍🚀",
+      quotes: "Quotes: \"'`",
+      newlines: "Line 1\nLine 2\r\nLine 3",
+    });
+  });
+
+  it("should correctly handle null and undefined values", async () => {
+    const stream = createObjectStream({
+      execute: (controller) => {
+        controller.enqueue([
+          { type: "set", path: ["nullValue"], value: null },
+          { type: "set", path: ["emptyObject"], value: {} },
+          { type: "set", path: ["emptyArray"], value: [] },
+        ]);
+      },
+    });
+
+    const decodedStream = await encodeAndDecode(stream);
+    const chunks = await collectChunks(decodedStream);
+    const finalChunk = chunks[chunks.length - 1]!;
+
+    expect(finalChunk.snapshot).toEqual({
+      nullValue: null,
+      emptyObject: {},
+      emptyArray: [],
+    });
+  });
+
+  it("should correctly handle large nested structures", async () => {
+    // Create a deep nested structure
+    const stream = createObjectStream({
+      execute: (controller) => {
+        controller.enqueue([
+          { type: "set", path: ["level1"], value: {} },
+          { type: "set", path: ["level1", "level2"], value: {} },
+          { type: "set", path: ["level1", "level2", "level3"], value: {} },
+          {
+            type: "set",
+            path: ["level1", "level2", "level3", "level4"],
+            value: {},
+          },
+          {
+            type: "set",
+            path: ["level1", "level2", "level3", "level4", "level5"],
+            value: "deep value",
+          },
+        ]);
+      },
+    });
+
+    const decodedStream = await encodeAndDecode(stream);
+    const chunks = await collectChunks(decodedStream);
+    const finalChunk = chunks[chunks.length - 1]!;
+
+    expect(finalChunk.snapshot).toEqual({
+      level1: {
+        level2: {
+          level3: {
+            level4: {
+              level5: "deep value",
+            },
+          },
+        },
+      },
+    });
+  });
+
+  it("should correctly handle operations in multiple enqueue calls", async () => {
+    const stream = createObjectStream({
+      execute: (controller) => {
+        // First batch of operations
+        controller.enqueue([
+          { type: "set", path: ["user"], value: { name: "Initial" } },
+        ]);
+
+        // Second batch of operations
+        controller.enqueue([
+          { type: "set", path: ["user", "name"], value: "Updated" },
+          { type: "set", path: ["user", "email"], value: "user@example.com" },
+        ]);
+
+        // Third batch of operations
+        controller.enqueue([
+          { type: "set", path: ["status"], value: "complete" },
+        ]);
+      },
+    });
+
+    const decodedStream = await encodeAndDecode(stream);
+    const chunks = await collectChunks(decodedStream);
+    const finalChunk = chunks[chunks.length - 1]!;
+
+    expect(finalChunk.snapshot).toEqual({
+      user: {
+        name: "Updated",
+        email: "user@example.com",
+      },
+      status: "complete",
+    });
+
+    // Verify that we got the correct number of chunks
+    expect(chunks.length).toBe(3);
+
+    // Verify intermediate states
+    expect(chunks[0]!.snapshot).toEqual({
+      user: { name: "Initial" },
+    });
+
+    expect(chunks[1]!.snapshot).toEqual({
+      user: {
+        name: "Updated",
+        email: "user@example.com",
+      },
+    });
+  });
+
+  it("should correctly handle overwriting existing values", async () => {
+    const stream = createObjectStream({
+      execute: (controller) => {
+        controller.enqueue([
+          { type: "set", path: ["value"], value: "initial" },
+          { type: "set", path: ["nested"], value: { prop: "initial" } },
+        ]);
+
+        controller.enqueue([
+          { type: "set", path: ["value"], value: "updated" },
+          { type: "set", path: ["nested"], value: "completely replaced" },
+        ]);
+      },
+    });
+
+    const decodedStream = await encodeAndDecode(stream);
+    const chunks = await collectChunks(decodedStream);
+    const finalChunk = chunks[chunks.length - 1]!;
+
+    expect(finalChunk.snapshot).toEqual({
+      value: "updated",
+      nested: "completely replaced",
+    });
+  });
+
+  it("should correctly handle custom initial values", async () => {
+    const initialValue: ReadonlyJSONValue = {
+      existing: "value",
+      nested: {
+        prop: 123,
+      },
+    };
+
+    const stream = createObjectStream({
+      defaultValue: initialValue,
+      execute: (controller) => {
+        controller.enqueue([
+          { type: "set", path: ["new"], value: "added" },
+          { type: "set", path: ["nested", "prop"], value: 456 },
+        ]);
+      },
+    });
+
+    const decodedStream = await encodeAndDecode(stream);
+    const chunks = await collectChunks(decodedStream);
+    const finalChunk = chunks[chunks.length - 1]!;
+
+    expect(finalChunk.snapshot).toEqual({
+      existing: "value",
+      nested: {
+        prop: 456,
+      },
+      new: "added",
+    });
+  });
+});

package/src/core/object/ObjectStreamAccumulator.ts

@@ -0,0 +1,80 @@
+import { ReadonlyJSONValue, ReadonlyJSONObject } from "../../utils";
+import { ObjectStreamOperation } from "./types";
+
+export class ObjectStreamAccumulator {
+  private _state: ReadonlyJSONValue;
+
+  constructor(initialValue: ReadonlyJSONValue = null) {
+    this._state = initialValue;
+  }
+
+  get state() {
+    return this._state;
+  }
+
+  append(ops: readonly ObjectStreamOperation[]) {
+    this._state = ops.reduce(
+      (state, op) => ObjectStreamAccumulator.apply(state, op),
+      this._state,
+    );
+  }
+
+  private static apply(state: ReadonlyJSONValue, op: ObjectStreamOperation) {
+    const type = op.type;
+    switch (type) {
+      case "set":
+        return ObjectStreamAccumulator.updatePath(
+          state,
+          op.path,
+          () => op.value,
+        );
+      case "append-text":
+        return ObjectStreamAccumulator.updatePath(state, op.path, (current) => {
+          if (typeof current !== "string")
+            throw new Error(`Expected string at path [${op.path.join(", ")}]`);
+          return current + op.value;
+        });
+
+      default: {
+        const _exhaustiveCheck: never = type;
+        throw new Error(`Invalid operation type: ${_exhaustiveCheck}`);
+      }
+    }
+  }
+
+  private static updatePath(
+    state: ReadonlyJSONValue | undefined,
+    path: readonly string[],
+    updater: (current: ReadonlyJSONValue | undefined) => ReadonlyJSONValue,
+  ): ReadonlyJSONValue {
+    if (path.length === 0) return updater(state);
+
+    // Initialize state as empty object if it's null and we're trying to set a property
+    if (state === null) {
+      state = {};
+    }
+
+    if (typeof state !== "object") {
+      throw new Error(`Invalid path: [${path.join(", ")}]`);
+    }
+
+    const [key, ...rest] = path as [string, ...(readonly string[])];
+    if (Array.isArray(state)) {
+      const idx = Number(key);
+      if (isNaN(idx))
+        throw new Error(`Expected array index at [${path.join(", ")}]`);
+      if (idx > state.length || idx < 0)
+        throw new Error(`Insert array index out of bounds`);
+
+      const nextState = [...state];
+      nextState[idx] = this.updatePath(nextState[idx], rest, updater);
+
+      return nextState;
+    }
+
+    const nextState = { ...(state as ReadonlyJSONObject) };
+    nextState[key] = this.updatePath(nextState[key], rest, updater);
+
+    return nextState;
+  }
+}