streamfold 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Streamfold contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# streamfold
+
+Incremental structured state for streamed AI tool calls.
+
+Streamfold retains JSON parser and value state across deltas. Its Rust/WebAssembly
+engine emits compact patches that update a live partial JavaScript value without
+reparsing the complete accumulated input.
+
+```bash
+pnpm add streamfold
+```
+
+```ts
+import { createStructuredStream } from "streamfold";
+
+const stream = createStructuredStream();
+const update = stream.push('{"city":"San');
+
+console.log(update.partialValue); // { city: "San" }
+console.log(update.changes); // compact set/append/complete patches
+
+stream.push(' Francisco"}');
+console.log(stream.getFieldState(["city"])); // "complete"
+```
+
+Resource limits are configurable and enabled by default:
+
+```ts
+const stream = createStructuredStream({
+  maxBytes: 2 * 1024 * 1024,
+  maxDepth: 64,
+});
+```
+
+Use an isolated event integration when consuming an SDK stream:
+
+```ts
+import { createStructuredStream } from "streamfold/assistant-ui";
+
+const toolCalls = createStructuredStream();
+
+for await (const event of assistantStream) {
+  const update = toolCalls.push(event);
+  if (update) renderToolInput(update.id, update.partialValue);
+}
+```
+
+Available subpaths are `assistant-ui`, `vercel-ai`, `openai`, `anthropic`,
+`gemini`, `langchain`, and `ag-ui`. They consume structural event shapes and do
+not install or load provider SDKs.
+
+See the [repository README](https://github.com/assistant-ui/streamfold#readme)
+for benchmarks, methodology, and development instructions.

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "streamfold",
+  "version": "0.1.1",
+  "description": "Protocol-neutral incremental state for structured AI streams",
+  "type": "module",
+  "license": "MIT",
+  "types": "./src/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "!src/**/*.test.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./ag-ui": {
+      "types": "./src/ag-ui.d.ts",
+      "default": "./src/ag-ui.js"
+    },
+    "./anthropic": {
+      "types": "./src/anthropic.d.ts",
+      "default": "./src/anthropic.js"
+    },
+    "./assistant-ui": {
+      "types": "./src/assistant-ui.d.ts",
+      "default": "./src/assistant-ui.js"
+    },
+    "./gemini": {
+      "types": "./src/gemini.d.ts",
+      "default": "./src/gemini.js"
+    },
+    "./langchain": {
+      "types": "./src/langchain.d.ts",
+      "default": "./src/langchain.js"
+    },
+    "./openai": {
+      "types": "./src/openai.d.ts",
+      "default": "./src/openai.js"
+    },
+    "./vercel-ai": {
+      "types": "./src/vercel-ai.d.ts",
+      "default": "./src/vercel-ai.js"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/assistant-ui/streamfold.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/assistant-ui/streamfold#readme",
+  "bugs": {
+    "url": "https://github.com/assistant-ui/streamfold/issues"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "incremental",
+    "json",
+    "rust",
+    "streaming",
+    "tool-calling",
+    "webassembly"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {}
+}

package/src/ag-ui.d.ts

@@ -0,0 +1,31 @@
+import type {
+  EventStructuredStream,
+  StructuredStreamIntegration,
+  StructuredStreamPool,
+} from "./index.js";
+
+export type AgUiToolCallEvent =
+  | {
+      readonly type: "TOOL_CALL_START";
+      readonly toolCallId: string;
+    }
+  | {
+      readonly type: "TOOL_CALL_ARGS";
+      readonly toolCallId: string;
+      readonly delta: string;
+    }
+  | {
+      readonly type: "TOOL_CALL_END";
+      readonly toolCallId: string;
+    }
+  | {
+      readonly type: string;
+      readonly toolCallId?: string;
+      readonly [key: string]: unknown;
+    };
+
+export const agUI: StructuredStreamIntegration<AgUiToolCallEvent, string>;
+
+export function createStructuredStream(
+  pool?: StructuredStreamPool<string>,
+): EventStructuredStream<AgUiToolCallEvent, string>;

package/src/ag-ui.js

@@ -0,0 +1,14 @@
+import { createStructuredStreamPool } from "./index.js";
+import { createIntegration } from "./internal/integration.js";
+
+export const agUI = (pool = createStructuredStreamPool()) =>
+  createIntegration(pool, (event, complete) => {
+    if (event.type === "TOOL_CALL_START") return pool.start(event.toolCallId);
+    if (event.type === "TOOL_CALL_ARGS") {
+      return pool.push(event.toolCallId, event.delta);
+    }
+    if (event.type === "TOOL_CALL_END") return complete(event.toolCallId);
+    return undefined;
+  });
+
+export { agUI as createStructuredStream };

package/src/anthropic.d.ts

@@ -0,0 +1,43 @@
+import type {
+  EventStructuredStream,
+  StructuredStreamIntegration,
+  StructuredStreamPool,
+} from "./index.js";
+
+export type AnthropicToolInputEvent =
+  | {
+      readonly type: "content_block_start";
+      readonly index: number;
+      readonly content_block: {
+        readonly type: string;
+        readonly id: string;
+      };
+    }
+  | {
+      readonly type: "content_block_delta";
+      readonly index: number;
+      readonly delta:
+        | {
+            readonly type: "input_json_delta";
+            readonly partial_json: string;
+          }
+        | { readonly type: string };
+    }
+  | {
+      readonly type: "content_block_stop";
+      readonly index: number;
+    }
+  | {
+      readonly type: string;
+      readonly index?: number;
+      readonly [key: string]: unknown;
+    };
+
+export const anthropic: StructuredStreamIntegration<
+  AnthropicToolInputEvent,
+  string
+>;
+
+export function createStructuredStream(
+  pool?: StructuredStreamPool<string>,
+): EventStructuredStream<AnthropicToolInputEvent, string>;

package/src/anthropic.js

@@ -0,0 +1,34 @@
+import { createStructuredStreamPool } from "./index.js";
+import { createIntegration } from "./internal/integration.js";
+
+export const anthropic = (pool = createStructuredStreamPool()) => {
+  const idsByIndex = new Map();
+
+  return createIntegration(pool, (event, complete) => {
+    if (
+      event.type === "content_block_start" &&
+      (event.content_block.type === "tool_use" ||
+        event.content_block.type === "server_tool_use")
+    ) {
+      idsByIndex.set(event.index, event.content_block.id);
+      return pool.start(event.content_block.id);
+    }
+
+    const id = idsByIndex.get(event.index);
+    if (id === undefined) return undefined;
+
+    if (
+      event.type === "content_block_delta" &&
+      event.delta.type === "input_json_delta"
+    ) {
+      return pool.push(id, event.delta.partial_json);
+    }
+    if (event.type === "content_block_stop") {
+      idsByIndex.delete(event.index);
+      return complete(id);
+    }
+    return undefined;
+  });
+};
+
+export { anthropic as createStructuredStream };

package/src/assistant-ui.d.ts

@@ -0,0 +1,41 @@
+import type {
+  EventStructuredStream,
+  StructuredStreamIntegration,
+  StructuredStreamPool,
+} from "./index.js";
+
+export type AssistantUiStreamEvent =
+  | {
+      readonly type: "part-start";
+      readonly path: readonly number[];
+      readonly part:
+        | {
+            readonly type: "tool-call";
+            readonly toolCallId: string;
+            readonly toolName: string;
+          }
+        | { readonly type: string };
+    }
+  | {
+      readonly type: "text-delta";
+      readonly path: readonly number[];
+      readonly textDelta: string;
+    }
+  | {
+      readonly type: "tool-call-args-text-finish";
+      readonly path: readonly number[];
+    }
+  | {
+      readonly type: string;
+      readonly path: readonly number[];
+      readonly [key: string]: unknown;
+    };
+
+export const assistantUI: StructuredStreamIntegration<
+  AssistantUiStreamEvent,
+  string
+>;
+
+export function createStructuredStream(
+  pool?: StructuredStreamPool<string>,
+): EventStructuredStream<AssistantUiStreamEvent, string>;

package/src/assistant-ui.js

@@ -0,0 +1,31 @@
+import { createStructuredStreamPool } from "./index.js";
+import { createIntegration } from "./internal/integration.js";
+
+const pathKey = (path) => path.join("/");
+
+export const assistantUI = (pool = createStructuredStreamPool()) => {
+  const idsByPath = new Map();
+
+  return createIntegration(pool, (event, complete) => {
+    const key = pathKey(event.path);
+
+    if (event.type === "part-start" && event.part.type === "tool-call") {
+      idsByPath.set(key, event.part.toolCallId);
+      return pool.start(event.part.toolCallId);
+    }
+
+    const id = idsByPath.get(key);
+    if (id === undefined) return undefined;
+
+    if (event.type === "text-delta") {
+      return pool.push(id, event.textDelta);
+    }
+    if (event.type === "tool-call-args-text-finish") {
+      idsByPath.delete(key);
+      return complete(id);
+    }
+    return undefined;
+  });
+};
+
+export { assistantUI as createStructuredStream };

package/src/gemini.d.ts

@@ -0,0 +1,42 @@
+import type {
+  EventStructuredStream,
+  StructuredStreamIntegration,
+  StructuredStreamPool,
+} from "./index.js";
+
+export type GeminiToolCallEvent =
+  | {
+      readonly event_type: "step.start";
+      readonly index: number;
+      readonly step: {
+        readonly type: string;
+        readonly id: string;
+        readonly arguments?: string | object;
+      };
+    }
+  | {
+      readonly event_type: "step.delta";
+      readonly index: number;
+      readonly delta:
+        | {
+            readonly type: "arguments";
+            readonly partial_arguments: string;
+          }
+        | { readonly type: string };
+    }
+  | {
+      readonly event_type: "interaction.completed" | "interaction.complete";
+    }
+  | {
+      readonly event_type: string;
+      readonly [key: string]: unknown;
+    };
+
+export const gemini: StructuredStreamIntegration<
+  GeminiToolCallEvent,
+  string
+>;
+
+export function createStructuredStream(
+  pool?: StructuredStreamPool<string>,
+): EventStructuredStream<GeminiToolCallEvent, string>;

package/src/gemini.js

@@ -0,0 +1,50 @@
+import { createStructuredStreamPool } from "./index.js";
+import { createIntegration } from "./internal/integration.js";
+
+export const gemini = (pool = createStructuredStreamPool()) => {
+  const idsByIndex = new Map();
+
+  return createIntegration(
+    pool,
+    (event, complete) => {
+      if (
+        event.event_type === "step.start" &&
+        event.step.type === "function_call"
+      ) {
+        idsByIndex.set(event.index, event.step.id);
+        const initial =
+          typeof event.step.arguments === "string"
+            ? event.step.arguments
+            : event.step.arguments
+              ? JSON.stringify(event.step.arguments)
+              : "";
+        return pool.start(event.step.id, initial);
+      }
+
+      if (
+        event.event_type === "step.delta" &&
+        event.delta.type === "arguments"
+      ) {
+        const id = idsByIndex.get(event.index);
+        if (id !== undefined) {
+          return pool.push(id, event.delta.partial_arguments);
+        }
+      }
+
+      if (
+        event.event_type === "interaction.completed" ||
+        event.event_type === "interaction.complete"
+      ) {
+        for (const id of idsByIndex.values()) complete(id);
+        idsByIndex.clear();
+      }
+      return undefined;
+    },
+    (complete) => {
+      for (const id of idsByIndex.values()) complete(id);
+      idsByIndex.clear();
+    },
+  );
+};
+
+export { gemini as createStructuredStream };

package/src/index.d.ts

@@ -0,0 +1,118 @@
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+export type StructuredStreamPath = readonly (string | number)[];
+export type StructuredStreamFieldState = "partial" | "complete";
+
+export interface StructuredStreamOptions {
+  /** Maximum UTF-8 bytes accepted by one stream. Defaults to 16 MiB. */
+  readonly maxBytes?: number;
+  /** Maximum nested object/array depth. Defaults to 128. */
+  readonly maxDepth?: number;
+}
+
+export interface StructuredStreamPoolOptions extends StructuredStreamOptions {
+  /** Maximum number of concurrently active streams. Defaults to 256. */
+  readonly maxActiveStreams?: number;
+}
+
+export type StructuredStreamPatch =
+  | {
+      readonly op: "set";
+      readonly path: StructuredStreamPath;
+      readonly value: JsonValue;
+    }
+  | {
+      readonly op: "append";
+      readonly path: StructuredStreamPath;
+      readonly value: string;
+    }
+  | {
+      readonly op: "complete";
+      readonly path: StructuredStreamPath;
+    };
+
+export interface StreamState {
+  /** Number of UTF-8 bytes processed by the Rust parser. */
+  readonly bytesSeen: number;
+  readonly depth: number;
+  readonly complete: boolean;
+  readonly inString: boolean;
+  readonly changes: readonly StructuredStreamPatch[];
+  /** A live view updated in place; use `changes` for reactive state updates. */
+  readonly partialValue: JsonValue | undefined;
+}
+
+export interface CompletedStructuredStream<Id = string> extends StreamState {
+  readonly id: Id;
+  readonly text: string;
+  readonly value: JsonValue;
+}
+
+export interface ActiveStructuredStream<Id = string> extends StreamState {
+  readonly id: Id;
+}
+
+export type StructuredStreamUpdate<Id = string> =
+  | ActiveStructuredStream<Id>
+  | CompletedStructuredStream<Id>
+  | undefined;
+
+export interface EventStructuredStream<Event, Id = string> {
+  push(event: Event): StructuredStreamUpdate<Id>;
+  finish(): readonly CompletedStructuredStream<Id>[];
+}
+
+export interface StructuredStreamIntegration<Event, Id = string> {
+  (
+    pool?: StructuredStreamPool<Id>,
+  ): EventStructuredStream<Event, Id>;
+}
+
+export class IncrementalJsonScanner {
+  constructor(options?: StructuredStreamOptions);
+  push(chunk: string): StreamState;
+  finish(): StreamState;
+  getFieldState(path: StructuredStreamPath): StructuredStreamFieldState;
+  dispose(): void;
+  readonly backend: "rust-wasm";
+  readonly state: StreamState;
+  /** A live view updated in place; use `StreamState.changes` for reactive updates. */
+  readonly value: JsonValue | undefined;
+}
+
+export class StructuredStreamPool<Id = string> {
+  constructor(options?: StructuredStreamPoolOptions);
+  start(id: Id, initialChunk?: string): ActiveStructuredStream<Id>;
+  push(id: Id, delta: string): ActiveStructuredStream<Id>;
+  finish(id: Id): CompletedStructuredStream<Id>;
+  getFieldState(
+    id: Id,
+    path: StructuredStreamPath,
+  ): StructuredStreamFieldState;
+  abort(id: Id): boolean;
+  has(id: Id): boolean;
+  readonly activeIds: readonly Id[];
+  readonly size: number;
+}
+
+export function createStructuredStream(): IncrementalJsonScanner;
+export function createStructuredStream(
+  options: StructuredStreamOptions,
+): IncrementalJsonScanner;
+export function createStructuredStream<Event, Id = string>(
+  integration: StructuredStreamIntegration<Event, Id>,
+): EventStructuredStream<Event, Id>;
+export function createStructuredStreamPool<Id = string>(
+  options?: StructuredStreamPoolOptions,
+): StructuredStreamPool<Id>;
+
+export const STREAMFOLD_ENGINE: "rust-wasm";
+export const DEFAULT_STREAM_LIMITS: Readonly<
+  Required<StructuredStreamPoolOptions>
+>;