assistant-stream 0.3.16 → 0.3.18

package/dist/core/tool/tool-types.d.ts

@@ -77,7 +77,7 @@ interface ToolCallArgsReader<TArgs extends Record<string, unknown>> {
    *
    * @param fieldPath An array of object keys or array indices.
    */
-  streamText<PathT extends TypePath<TArgs>>(...fieldPath: PathT): TypeAtPath<TArgs, PathT> extends string & infer U ? AsyncIterableStream<U> : never;
+  streamText<PathT extends TypePath<TArgs>>(...fieldPath: PathT): TypeAtPath<TArgs, PathT> extends string & (infer U) ? AsyncIterableStream<U> : never;
   /**
    * Returns a stream that will emit complete items in the array
    * at the given path, as they are generated by the LLM.
@@ -115,11 +115,48 @@ type ToolExecutionContext = {
 type ToolExecuteFunction<TArgs, TResult> = (args: TArgs, context: ToolExecutionContext) => TResult | Promise<TResult>;
 type ToolStreamCallFunction<TArgs extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> = (reader: ToolCallReader<TArgs, TResult>, context: ToolExecutionContext) => void;
 type OnSchemaValidationErrorFunction<TResult> = ToolExecuteFunction<unknown, TResult>;
+/**
+ * Per-provider metadata forwarded into the wire request body verbatim.
+ * assistant-ui does not interpret these values; downstream adapters (AI SDK,
+ * custom routes) pass them to the model provider as-is.
+ *
+ * The outer key is the provider name (`anthropic`, `openai`, ...); the inner
+ * object is whatever shape that provider's SDK expects under
+ * `tool.providerOptions[providerName]`. Use this to enable provider-specific
+ * tool behaviors such as Anthropic's `defer_loading`
+ * (`{ anthropic: { deferLoading: true } }`) without adding provider-aware
+ * code in assistant-ui.
+ */
+type ProviderOptions = Record<string, Record<string, unknown>>;
+/**
+ * Controls how a tool call's UI is presented relative to the assistant's
+ * chain-of-thought trace.
+ *
+ * - `"inline"` — the tool call is part of the reasoning trace and is folded
+ *   into the chain-of-thought grouping alongside other routine tool calls.
+ * - `"standalone"` — the tool call is surfaced on its own, outside the
+ *   chain-of-thought grouping (e.g. a human-in-the-loop prompt, a generative
+ *   UI surface, or an important action UI worth showing prominently).
+ *
+ * This is a client-side presentation hint only; it does not affect how the
+ * tool is exposed to or executed by the model.
+ */
+type ToolDisplay = "standalone" | "inline";
 type ToolBase<TArgs extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> = {
   /**
    * @deprecated Experimental, API may change.
    */
   streamCall?: ToolStreamCallFunction<TArgs, TResult>;
+  /**
+   * How this tool's UI is presented relative to the chain-of-thought trace.
+   *
+   * Defaults to `"inline"` (folded into the chain-of-thought grouping).
+   * Set `"standalone"` to surface the tool call on its own. `human` tools are
+   * always `"standalone"` and cannot opt out.
+   *
+   * @see ToolDisplay
+   */
+  display?: ToolDisplay;
 };
 type BackendTool<TArgs extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> = ToolBase<TArgs, TResult> & {
   /** Tool that is executed by the backend rather than in the browser. */type: "backend";
@@ -129,6 +166,24 @@ type BackendTool<TArgs extends Record<string, unknown> = Record<string, unknown>
   execute?: undefined;
   toModelOutput?: undefined;
   experimental_onSchemaValidationError?: undefined;
+  providerOptions?: undefined;
+};
+/**
+ * Backend tool as *authored* (a {@link ToolDeclaration}), before the build
+ * splits it: it may declare a `description`, `parameters`, and a server-side
+ * `execute`. The canonical {@link BackendTool} keeps these `undefined` because,
+ * once split, the client never sees them and the server consumes them through a
+ * server adapter rather than the shared {@link Tool} shape.
+ */
+type BackendToolDeclaration<TArgs extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> = ToolBase<TArgs, TResult> & {
+  type: "backend"; /** Natural-language description shown to the model when selecting tools. */
+  description?: string | undefined; /** Schema for the arguments the model must provide when calling the tool. */
+  parameters?: StandardSchemaV1<TArgs> | JSONSchema7 | undefined; /** Prevents the tool from being exposed to the model while true. */
+  disabled?: boolean; /** Executes the tool on the server after the model provides valid arguments. */
+  execute?: ToolExecuteFunction<TArgs, TResult>; /** Converts the execution result into model-visible output. */
+  toModelOutput?: ToolModelOutputFunction<TArgs, TResult>; /** Handles invalid tool arguments when schema validation fails. */
+  experimental_onSchemaValidationError?: OnSchemaValidationErrorFunction<TResult>;
+  providerOptions?: ProviderOptions;
 };
 type FrontendTool<TArgs extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> = ToolBase<TArgs, TResult> & {
   /** Tool that is executed in the frontend runtime. */type: "frontend"; /** Natural-language description shown to the model when selecting tools. */
@@ -138,15 +193,18 @@ type FrontendTool<TArgs extends Record<string, unknown> = Record<string, unknown
   execute: ToolExecuteFunction<TArgs, TResult>; /** Converts the execution result into model-visible output. */
   toModelOutput?: ToolModelOutputFunction<TArgs, TResult>; /** Handles invalid tool arguments when schema validation fails. */
   experimental_onSchemaValidationError?: OnSchemaValidationErrorFunction<TResult>;
+  providerOptions?: ProviderOptions;
 };
 type HumanTool<TArgs extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> = ToolBase<TArgs, TResult> & {
   /** Tool that pauses the run until a user or UI supplies a result. */type: "human"; /** Natural-language description shown to the model when selecting tools. */
   description?: string | undefined; /** Schema for the arguments the model must provide when requesting input. */
   parameters: StandardSchemaV1<TArgs> | JSONSchema7; /** Prevents the tool from being exposed to the model while true. */
-  disabled?: boolean;
+  disabled?: boolean; /** Human tools are always surfaced standalone and cannot opt out. */
+  display?: "standalone";
   execute?: undefined;
   toModelOutput?: undefined;
   experimental_onSchemaValidationError?: undefined;
+  providerOptions?: ProviderOptions;
 };
 /**
  * Definition for a tool that can be exposed to the assistant model.
@@ -190,6 +248,13 @@ type HumanTool<TArgs extends Record<string, unknown> = Record<string, unknown>,
  * ```
  */
 type Tool<TArgs extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> = FrontendTool<TArgs, TResult> | BackendTool<TArgs, TResult> | HumanTool<TArgs, TResult> | ToolWithoutType<TArgs, TResult>;
+/**
+ * A tool as *authored* — the permissive counterpart to {@link Tool}. Unlike
+ * {@link Tool}, a `backend` entry may declare `description`, `parameters`, and a
+ * server-side `execute`. Use this for the input of authoring helpers (e.g.
+ * `defineToolkit`); the canonical {@link Tool} is the output.
+ */
+type ToolDeclaration<TArgs extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> = FrontendTool<TArgs, TResult> | BackendToolDeclaration<TArgs, TResult> | HumanTool<TArgs, TResult> | ToolWithoutType<TArgs, TResult>;
 /**
  * @deprecated Use {@link Tool} with an explicit `type` field instead.
  */
@@ -197,5 +262,5 @@ type ToolWithoutType<TArgs extends Record<string, unknown> = Record<string, unkn
   type?: undefined;
 };
 //#endregion
-export { Tool, ToolCallArgsReader, ToolCallReader, ToolCallResponseReader, ToolExecuteFunction, ToolExecutionContext, ToolModelContentPart, ToolModelOutputFunction, ToolStreamCallFunction, ToolWithoutType };
+export { ProviderOptions, Tool, ToolCallArgsReader, ToolCallReader, ToolCallResponseReader, ToolDeclaration, ToolExecuteFunction, ToolExecutionContext, ToolModelContentPart, ToolModelOutputFunction, ToolStreamCallFunction, ToolWithoutType };
 //# sourceMappingURL=tool-types.d.ts.map

package/dist/core/tool/tool-types.d.ts.map

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

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

@@ -1 +1 @@
-{"version":3,"file":"Counter.d.ts","names":[],"sources":["../../../src/core/utils/Counter.ts"],"mappings":";cAAa,OAAA;EACJ,KAAA;EAEP,EAAE,CAAA;AAAA"}
+{"version":3,"file":"Counter.d.ts","names":[],"sources":["../../../src/core/utils/Counter.ts"],"mappings":";cAAa,OAAA;EACJ,KAAA;EAEP,EAAE;AAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"withPromiseOrValue.d.ts","names":[],"sources":["../../../src/core/utils/withPromiseOrValue.ts"],"mappings":";iBAAgB,kBAAA,GAAA,CACd,QAAA,QAAgB,CAAA,GAAI,WAAA,CAAY,CAAA,GAChC,WAAA,GAAc,KAAA,EAAO,CAAA,KAAM,WAAA,eAC3B,YAAA,GAAe,KAAA,cAAmB,WAAA,gBACjC,WAAA"}
+{"version":3,"file":"withPromiseOrValue.d.ts","names":[],"sources":["../../../src/core/utils/withPromiseOrValue.ts"],"mappings":";iBAAgB,kBAAA,IACd,QAAA,QAAgB,CAAA,GAAI,WAAA,CAAY,CAAA,GAChC,WAAA,GAAc,KAAA,EAAO,CAAA,KAAM,WAAA,eAC3B,YAAA,GAAe,KAAA,cAAmB,WAAA,gBACjC,WAAA"}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { TextStreamController } from "./core/modules/text.js";
-import { Tool, ToolCallReader, ToolModelContentPart, ToolModelOutputFunction } from "./core/tool/tool-types.js";
+import { ProviderOptions, Tool, ToolCallReader, ToolDeclaration, ToolModelContentPart, ToolModelOutputFunction } from "./core/tool/tool-types.js";
 import { ToolResponse, ToolResponseLike } from "./core/tool/ToolResponse.js";
 import { ToolCallStreamController } from "./core/modules/tool-call.js";
 import { AssistantMessage, AssistantMessageTiming, DataPart } from "./core/utils/types.js";
@@ -20,4 +20,4 @@ import { UIMessageStreamDecoder, UIMessageStreamDecoderOptions } from "./core/se
 import { ToolExecutionStream } from "./core/tool/ToolExecutionStream.js";
 import { ToToolsJSONSchemaOptions, ToolJSONSchema, toJSONSchema, toPartialJSONSchema, toToolsJSONSchema } from "./core/tool/schema-utils.js";
 import { ToolResultStreamOptions, toolResultStream, unstable_runPendingTools } from "./core/tool/toolResultStream.js";
-export { type AssistantMessage, AssistantMessageAccumulator, AssistantMessageStream, type AssistantMessageTiming, AssistantStream, type AssistantStreamChunk, type AssistantStreamController, AssistantTransportDecoder, AssistantTransportEncoder, type DataPart, DataStreamDecoder, DataStreamEncoder, type GenericAssistantMessage, type GenericFilePart, type GenericMessage, type GenericSystemMessage, type GenericTextPart, type GenericToolCallPart, type GenericToolMessage, type GenericToolResultPart, type GenericUserMessage, type ObjectStreamChunk, ObjectStreamResponse, PlainTextDecoder, PlainTextEncoder, type TextStreamController, type ToToolsJSONSchemaOptions, type Tool, type ToolCallReader, type ToolCallStreamController, ToolExecutionStream, type ToolJSONSchema, type ToolModelContentPart, type ToolModelOutputFunction, ToolResponse, type ToolResponseLike, type ToolResultStreamOptions, type UIMessageStreamChunk, type UIMessageStreamDataChunk, UIMessageStreamDecoder, type UIMessageStreamDecoderOptions, createAssistantStream, createAssistantStreamController, createAssistantStreamResponse, createObjectStream, fromObjectStreamResponse, toGenericMessages, toJSONSchema, toPartialJSONSchema, toToolsJSONSchema, createInitialMessage as unstable_createInitialMessage, unstable_runPendingTools, toolResultStream as unstable_toolResultStream };
+export { type AssistantMessage, AssistantMessageAccumulator, AssistantMessageStream, type AssistantMessageTiming, AssistantStream, type AssistantStreamChunk, type AssistantStreamController, AssistantTransportDecoder, AssistantTransportEncoder, type DataPart, DataStreamDecoder, DataStreamEncoder, type GenericAssistantMessage, type GenericFilePart, type GenericMessage, type GenericSystemMessage, type GenericTextPart, type GenericToolCallPart, type GenericToolMessage, type GenericToolResultPart, type GenericUserMessage, type ObjectStreamChunk, ObjectStreamResponse, PlainTextDecoder, PlainTextEncoder, type ProviderOptions, type TextStreamController, type ToToolsJSONSchemaOptions, type Tool, type ToolCallReader, type ToolCallStreamController, type ToolDeclaration, ToolExecutionStream, type ToolJSONSchema, type ToolModelContentPart, type ToolModelOutputFunction, ToolResponse, type ToolResponseLike, type ToolResultStreamOptions, type UIMessageStreamChunk, type UIMessageStreamDataChunk, UIMessageStreamDecoder, type UIMessageStreamDecoderOptions, createAssistantStream, createAssistantStreamController, createAssistantStreamResponse, createObjectStream, fromObjectStreamResponse, toGenericMessages, toJSONSchema, toPartialJSONSchema, toToolsJSONSchema, createInitialMessage as unstable_createInitialMessage, unstable_runPendingTools, toolResultStream as unstable_toolResultStream };

package/dist/node_modules/.pnpm/@types_json-schema@7.0.15/node_modules/@types/json-schema/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":["JSONSchema4TypeName","JSONSchema4Type","JSONSchema4Object","JSONSchema4Array","key","Array","JSONSchema4Version","JSONSchema4","id","$ref","$schema","title","description","default","multipleOf","maximum","exclusiveMaximum","minimum","exclusiveMinimum","maxLength","minLength","pattern","additionalItems","items","maxItems","minItems","uniqueItems","maxProperties","minProperties","required","additionalProperties","definitions","k","properties","patternProperties","dependencies","enum","type","allOf","anyOf","oneOf","not","extends","format","JSONSchema6TypeName","JSONSchema6Type","JSONSchema6Object","JSONSchema6Array","JSONSchema6Version","JSONSchema6Definition","JSONSchema6","$id","contains","propertyNames","const","examples","JSONSchema7TypeName","JSONSchema7Type","JSONSchema7Object","JSONSchema7Array","JSONSchema7Version","JSONSchema7Definition","JSONSchema7","$comment","$defs","if","then","else","contentMediaType","contentEncoding","readOnly","writeOnly","ValidationResult","ValidationError","valid","errors","property","message","validate","instance","schema","checkPropertyChange","value","mustBeValid","result"],"sources":["../../../../../../../../../node_modules/.pnpm/@types+json-schema@7.0.15/node_modules/@types/json-schema/index.d.ts"],"x_google_ignoreList":[0],"mappings":";;;;;;;;;;KA+iBYwD,mBAAAA;AAAAA;;;;;KAaAC,eAAAA;AAAAA,qBAINC,iBAAAA,GACAC,gBAAgB;AAAA;AAAA,UAILD,iBAAAA;EAAAA,CACZtD,GAAAA,WAAcqD,eAAe;AAAA;AAAA;AAAA;AAAA,UAKjBE,gBAAAA,SAAyBtD,KAAK,CAACoD,eAAAA;;;;;;;;;;;;KAapCG,kBAAAA;;;;;KAMAC,qBAAAA,GAAwBC,WAAW;AAAA,UAC9BA,WAAAA;EACbX,GAAAA;EACA1C,IAAAA;EACAC,OAAAA,GAAUkD,kBAAAA;EACVG,QAAAA;;;;;EAMAC,KAAAA;IAAAA,CACK5D,GAAAA,WAAcyD,qBAAAA;EAAAA;;;;EAMnBxB,IAAAA,GAAOmB,mBAAAA,GAAsBA,mBAAAA;EAC7BpB,IAAAA,GAAOqB,eAAAA;EACPH,KAAAA,GAAQG,eAAAA;;;;EAKR3C,UAAAA;EACAC,OAAAA;EACAC,gBAAAA;EACAC,OAAAA;EACAC,gBAAAA;;;;EAKAC,SAAAA;EACAC,SAAAA;EACAC,OAAAA;;;;EAKAE,KAAAA,GAAQsC,qBAAAA,GAAwBA,qBAAAA;EAChCvC,eAAAA,GAAkBuC,qBAAAA;EAClBrC,QAAAA;EACAC,QAAAA;EACAC,WAAAA;EACA0B,QAAAA,GAAWS,qBAAAA;;;;EAKXlC,aAAAA;EACAC,aAAAA;EACAC,QAAAA;EACAI,UAAAA;IAAAA,CACK7B,GAAAA,WAAcyD,qBAAAA;EAAAA;EAEnB3B,iBAAAA;IAAAA,CACK9B,GAAAA,WAAcyD,qBAAAA;EAAAA;EAEnB/B,oBAAAA,GAAuB+B,qBAAAA;EACvB1B,YAAAA;IAAAA,CACK/B,GAAAA,WAAcyD,qBAAAA;EAAAA;EAEnBR,aAAAA,GAAgBQ,qBAAAA;;;;EAKhBI,EAAAA,GAAKJ,qBAAAA;EACLK,IAAAA,GAAOL,qBAAAA;EACPM,IAAAA,GAAON,qBAAAA;;;;EAKPvB,KAAAA,GAAQuB,qBAAAA;EACRtB,KAAAA,GAAQsB,qBAAAA;EACRrB,KAAAA,GAAQqB,qBAAAA;EACRpB,GAAAA,GAAMoB,qBAAAA;;;;EAKNlB,MAAAA;;;;EAKAyB,gBAAAA;EACAC,eAAAA;;;;EAKAtC,WAAAA;IAAAA,CACK3B,GAAAA,WAAcyD,qBAAAA;EAAAA;;;;EAMnBlD,KAAAA;EACAC,WAAAA;EACAC,OAAAA,GAAU4C,eAAAA;EACVa,QAAAA;EACAC,SAAAA;EACAhB,QAAAA,GAAWE,eAAAA;AAAAA"}
+{"version":3,"file":"index.d.ts","names":["JSONSchema4Object","JSONSchema4Array","key","JSONSchema4Type","Array","id","$ref","$schema","JSONSchema4Version","title","description","default","multipleOf","maximum","exclusiveMaximum","minimum","exclusiveMinimum","maxLength","minLength","pattern","additionalItems","JSONSchema4","items","maxItems","minItems","uniqueItems","maxProperties","minProperties","required","additionalProperties","definitions","k","properties","patternProperties","dependencies","enum","type","JSONSchema4TypeName","allOf","anyOf","oneOf","not","extends","format","JSONSchema6Object","JSONSchema6Array","JSONSchema6Type","JSONSchema6","$id","JSONSchema6Version","JSONSchema6Definition","contains","propertyNames","const","JSONSchema6TypeName","examples","JSONSchema7Object","JSONSchema7Array","JSONSchema7Type","JSONSchema7","JSONSchema7Version","$comment","$defs","JSONSchema7Definition","JSONSchema7TypeName","if","then","else","contentMediaType","contentEncoding","readOnly","writeOnly","valid","errors","ValidationError","property","message","instance","schema","ValidationResult","value","result"],"sources":["../../../../../../../../../node_modules/.pnpm/@types+json-schema@7.0.15/node_modules/@types/json-schema/index.d.ts"],"x_google_ignoreList":[0],"mappings":";;;;;;;;;;KA+iBY,mBAAA;AAAA;;;;;KAaA,eAAA;AAAA,qBAIN,iBAAA,GACA,gBAAgB;AAAA;AAAA,UAIL,iBAAA;EAAA,CACZE,GAAAA,WAAc,eAAe;AAAA;AAAA;AAAA;AAAA,UAKjB,gBAAA,SAAyB,KAAK,CAAC,eAAA;;;;;;;;;;;;KAapC,kBAAA;;;;;KAMA,qBAAA,GAAwB,WAAW;AAAA,UAC9B,WAAA;EACb8C,GAAAA;EACA1C,IAAAA;EACAC,OAAAA,GAAU,kBAAA;EACVsD,QAAAA;;;;;EAMAC,KAAAA;IAAAA,CACK5D,GAAAA,WAAc,qBAAA;EAAA;;;;EAMnBkC,IAAAA,GAAO,mBAAA,GAAsB,mBAAA;EAC7BD,IAAAA,GAAO,eAAA;EACPkB,KAAAA,GAAQ,eAAA;;;;EAKRzC,UAAAA;EACAC,OAAAA;EACAC,gBAAAA;EACAC,OAAAA;EACAC,gBAAAA;;;;EAKAC,SAAAA;EACAC,SAAAA;EACAC,OAAAA;;;;EAKAG,KAAAA,GAAQ,qBAAA,GAAwB,qBAAA;EAChCF,eAAAA,GAAkB,qBAAA;EAClBG,QAAAA;EACAC,QAAAA;EACAC,WAAAA;EACA0B,QAAAA,GAAW,qBAAA;;;;EAKXzB,aAAAA;EACAC,aAAAA;EACAC,QAAAA;EACAI,UAAAA;IAAAA,CACK9B,GAAAA,WAAc,qBAAA;EAAA;EAEnB+B,iBAAAA;IAAAA,CACK/B,GAAAA,WAAc,qBAAA;EAAA;EAEnB2B,oBAAAA,GAAuB,qBAAA;EACvBK,YAAAA;IAAAA,CACKhC,GAAAA,WAAc,qBAAA;EAAA;EAEnBkD,aAAAA,GAAgB,qBAAA;;;;EAKhBa,EAAAA,GAAK,qBAAA;EACLC,IAAAA,GAAO,qBAAA;EACPC,IAAAA,GAAO,qBAAA;;;;EAKP7B,KAAAA,GAAQ,qBAAA;EACRC,KAAAA,GAAQ,qBAAA;EACRC,KAAAA,GAAQ,qBAAA;EACRC,GAAAA,GAAM,qBAAA;;;;EAKNE,MAAAA;;;;EAKAyB,gBAAAA;EACAC,eAAAA;;;;EAKAvC,WAAAA;IAAAA,CACK5B,GAAAA,WAAc,qBAAA;EAAA;;;;EAMnBO,KAAAA;EACAC,WAAAA;EACAC,OAAAA,GAAU,eAAA;EACV2D,QAAAA;EACAC,SAAAA;EACAhB,QAAAA,GAAW,eAAA;AAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"AsyncIterableStream.d.ts","names":[],"sources":["../../src/utils/AsyncIterableStream.ts"],"mappings":";KAAY,mBAAA,MAAyB,aAAA,CAAc,CAAA,IAAK,cAAA,CAAe,CAAA;AAAA,iBAiBvD,qBAAA,GAAA,CACd,MAAA,EAAQ,cAAA,CAAe,CAAA,IACtB,mBAAA,CAAoB,CAAA"}
+{"version":3,"file":"AsyncIterableStream.d.ts","names":[],"sources":["../../src/utils/AsyncIterableStream.ts"],"mappings":";KAAY,mBAAA,MAAyB,aAAA,CAAc,CAAA,IAAK,cAAA,CAAe,CAAA;AAAA,iBAiBvD,qBAAA,IACd,MAAA,EAAQ,cAAA,CAAe,CAAA,IACtB,mBAAA,CAAoB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assistant-stream",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "description": "Streaming utilities for AI assistants",
   "keywords": [
     "ai",
@@ -64,10 +64,10 @@
   },
   "devDependencies": {
     "@types/json-schema": "^7.0.15",
-    "ioredis": "^5.10.1",
-    "redis": "^5.12.1",
+    "ioredis": "^5.11.0",
+    "redis": "^6.0.0",
     "vitest": "^4.1.7",
-    "@assistant-ui/x-buildutils": "0.0.9"
+    "@assistant-ui/x-buildutils": "0.0.10"
   },
   "publishConfig": {
     "access": "public",

package/src/core/modules/assistant-stream.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from "vitest";
+import { createAssistantStreamResponse } from "./assistant-stream";
+import { AssistantStream } from "../AssistantStream";
+import { DataStreamDecoder } from "../serialization/data-stream/DataStream";
+import { AssistantMessageAccumulator } from "../accumulators/assistant-message-accumulator";
+import type { AssistantMessage } from "../utils/types";
+
+const accumulate = async (response: Response): Promise<AssistantMessage> => {
+  const stream = AssistantStream.fromResponse(
+    response,
+    new DataStreamDecoder(),
+  );
+  let last: AssistantMessage | undefined;
+  await stream.pipeThrough(new AssistantMessageAccumulator()).pipeTo(
+    new WritableStream({
+      write(message) {
+        last = message;
+      },
+    }),
+  );
+  return last!;
+};
+
+describe("AssistantStreamController withParentId", () => {
+  it("attaches parentId to text parts across a data-stream round trip", async () => {
+    const response = createAssistantStreamResponse((controller) => {
+      controller.appendText("intro");
+      const group = controller.withParentId("group-1");
+      group.appendSource({
+        type: "source",
+        sourceType: "url",
+        id: "s1",
+        url: "https://example.com",
+        title: "Example",
+      });
+      group.appendText("grouped text");
+    });
+
+    const message = await accumulate(response);
+    const intro = message.parts.find(
+      (p) => p.type === "text" && p.text === "intro",
+    );
+    const grouped = message.parts.find(
+      (p) => p.type === "text" && p.text === "grouped text",
+    );
+    const source = message.parts.find((p) => p.type === "source");
+
+    expect(intro?.parentId).toBeUndefined();
+    expect(grouped?.parentId).toBe("group-1");
+    expect(source?.parentId).toBe("group-1");
+  });
+
+  it("attaches parentId to reasoning parts across a data-stream round trip", async () => {
+    const response = createAssistantStreamResponse((controller) => {
+      controller.appendReasoning("thinking out loud");
+      const group = controller.withParentId("group-1");
+      group.appendReasoning("grouped reasoning");
+    });
+
+    const message = await accumulate(response);
+    const ungrouped = message.parts.find(
+      (p) => p.type === "reasoning" && p.text === "thinking out loud",
+    );
+    const grouped = message.parts.find(
+      (p) => p.type === "reasoning" && p.text === "grouped reasoning",
+    );
+
+    expect(ungrouped?.parentId).toBeUndefined();
+    expect(grouped?.parentId).toBe("group-1");
+  });
+
+  it("opens a new text part when withParentId switches between ids", async () => {
+    const response = createAssistantStreamResponse((controller) => {
+      controller.withParentId("group-1").appendText("first");
+      controller.withParentId("group-2").appendText("second");
+    });
+
+    const message = await accumulate(response);
+    const first = message.parts.find(
+      (p) => p.type === "text" && p.text === "first",
+    );
+    const second = message.parts.find(
+      (p) => p.type === "text" && p.text === "second",
+    );
+
+    expect(first?.parentId).toBe("group-1");
+    expect(second?.parentId).toBe("group-2");
+  });
+
+  it("attaches parentId on addTextPart called directly inside a withParentId scope", async () => {
+    const response = createAssistantStreamResponse((controller) => {
+      const part = controller.withParentId("group-1").addTextPart();
+      part.append("explicit");
+      part.close();
+    });
+
+    const message = await accumulate(response);
+    const text = message.parts.find(
+      (p) => p.type === "text" && p.text === "explicit",
+    );
+
+    expect(text?.parentId).toBe("group-1");
+  });
+});

package/src/core/modules/assistant-stream.ts

@@ -96,6 +96,7 @@ type AssistantStreamControllerState = {
     | {
         controller: TextStreamController;
         kind: "text" | "reasoning";
+        parentId: string | undefined;
       }
     | undefined;
   contentCounter: Counter;
@@ -150,9 +151,13 @@ class AssistantStreamControllerImpl implements AssistantStreamController {
   }
 
   appendText(textDelta: string) {
-    if (this._state.append?.kind !== "text") {
+    if (
+      this._state.append?.kind !== "text" ||
+      this._state.append.parentId !== this._parentId
+    ) {
       this._state.append = {
         kind: "text",
+        parentId: this._parentId,
         controller: this.addTextPart(),
       };
     }
@@ -160,9 +165,13 @@ class AssistantStreamControllerImpl implements AssistantStreamController {
   }
 
   appendReasoning(textDelta: string) {
-    if (this._state.append?.kind !== "reasoning") {
+    if (
+      this._state.append?.kind !== "reasoning" ||
+      this._state.append.parentId !== this._parentId
+    ) {
       this._state.append = {
         kind: "reasoning",
+        parentId: this._parentId,
         controller: this.addReasoningPart(),
       };
     }
@@ -171,13 +180,13 @@ class AssistantStreamControllerImpl implements AssistantStreamController {
 
   addTextPart() {
     const [stream, controller] = createTextStreamController();
-    this._addPart({ type: "text" }, stream);
+    this._addPart(this._withParentIdOption({ type: "text" }), stream);
     return controller;
   }
 
   addReasoningPart() {
     const [stream, controller] = createTextStreamController();
-    this._addPart({ type: "reasoning" }, stream);
+    this._addPart(this._withParentIdOption({ type: "reasoning" }), stream);
     return controller;
   }
 

package/src/core/object/ObjectStreamResponse.ts

@@ -12,10 +12,10 @@ export class ObjectStreamEncoder extends PipeableTransformStream<
       readable
         .pipeThrough(
           (() => {
-            class ObjectStreamTransformer
-              implements
-                Transformer<ObjectStreamChunk, readonly ObjectStreamOperation[]>
-            {
+            class ObjectStreamTransformer implements Transformer<
+              ObjectStreamChunk,
+              readonly ObjectStreamOperation[]
+            > {
               #isFirstChunk = true;
 
               start() {

package/src/core/serialization/data-stream/DataStream.ts

@@ -419,7 +419,6 @@ export class DataStreamDecoder extends PipeableTransformStream<
         flush() {
           activeToolCallArgsText?.close();
           activeToolCallArgsText = undefined;
-          // biome-ignore lint/suspicious/useIterableCallbackReturn: forEach callback intentionally has no return
           toolCallControllers.forEach((controller) => controller.close());
           toolCallControllers.clear();
         },

package/src/core/serialization/ui-message-stream/UIMessageStream.ts

@@ -264,7 +264,6 @@ export class UIMessageStreamDecoder extends PipeableTransformStream<
         },
         flush() {
           activeToolCallArgsText?.close();
-          // biome-ignore lint/suspicious/useIterableCallbackReturn: forEach callback intentionally has no return
           toolCallControllers.forEach((ctrl) => ctrl.close());
           toolCallControllers.clear();
         },

package/src/core/tool/ToolCallReader.ts

@@ -232,9 +232,9 @@ class ForEachHandle<T> implements Handle {
 }
 
 // Implementation of ToolCallReader that uses stream of partial JSON
-export class ToolCallArgsReaderImpl<T extends ReadonlyJSONObject>
-  implements ToolCallArgsReader<T>
-{
+export class ToolCallArgsReaderImpl<
+  T extends ReadonlyJSONObject,
+> implements ToolCallArgsReader<T> {
   private argTextDeltas: ReadableStream<string>;
   private handles: Set<Handle> = new Set();
   private args: unknown = parsePartialJsonObject("");
@@ -334,7 +334,7 @@ export class ToolCallArgsReaderImpl<T extends ReadonlyJSONObject>
 
   streamText<PathT extends TypePath<T>>(
     ...fieldPath: PathT
-  ): TypeAtPath<T, PathT> extends string & infer U
+  ): TypeAtPath<T, PathT> extends string & (infer U)
     ? AsyncIterableStream<U>
     : never {
     // Use a type assertion to convert the complex TypePath to a simple array
@@ -395,9 +395,9 @@ export class ToolCallArgsReaderImpl<T extends ReadonlyJSONObject>
   }
 }
 
-export class ToolCallResponseReaderImpl<TResult extends ReadonlyJSONValue>
-  implements ToolCallResponseReader<TResult>
-{
+export class ToolCallResponseReaderImpl<
+  TResult extends ReadonlyJSONValue,
+> implements ToolCallResponseReader<TResult> {
   constructor(private readonly promise: Promise<ToolResponse<TResult>>) {}
 
   public get() {
@@ -408,8 +408,7 @@ export class ToolCallResponseReaderImpl<TResult extends ReadonlyJSONValue>
 export class ToolCallReaderImpl<
   TArgs extends ReadonlyJSONObject,
   TResult extends ReadonlyJSONValue,
-> implements ToolCallReader<TArgs, TResult>
-{
+> implements ToolCallReader<TArgs, TResult> {
   public readonly args: ToolCallArgsReaderImpl<TArgs>;
   public readonly response: ToolCallResponseReaderImpl<TResult>;
   private readonly writable: WritableStream<string>;

package/src/core/tool/ToolResponse.ts

@@ -1,6 +1,7 @@
 import type { ReadonlyJSONValue } from "../../utils/json/json-value";
 import type {
   ToolModelContentPart,
+  // oxlint-disable-next-line no-unused-vars -- referenced from JSDoc {@link} below
   ToolModelOutputFunction,
 } from "./tool-types";
 

package/src/core/tool/schema-utils.test.ts

@@ -430,6 +430,62 @@ describe("toToolsJSONSchema", () => {
         properties: { converted: { type: "boolean" } },
       });
     });
+
+    it("forwards providerOptions verbatim when present", () => {
+      const tools: Record<string, Tool> = {
+        myTool: {
+          description: "Test",
+          parameters: { type: "object", properties: {} },
+          providerOptions: { anthropic: { deferLoading: true } },
+        },
+      };
+
+      const result = toToolsJSONSchema(tools);
+      expect(result.myTool).toEqual({
+        description: "Test",
+        parameters: { type: "object", properties: {} },
+        providerOptions: { anthropic: { deferLoading: true } },
+      });
+    });
+
+    it("omits providerOptions when absent", () => {
+      const tools: Record<string, Tool> = {
+        myTool: {
+          parameters: { type: "object", properties: {} },
+        },
+      };
+
+      const result = toToolsJSONSchema(tools);
+      expect(result.myTool).not.toHaveProperty("providerOptions");
+    });
+  });
+
+  describe("stable ordering", () => {
+    it("emits tool names in alphabetical order", () => {
+      const tools: Record<string, Tool> = {
+        zebra: { parameters: { type: "object", properties: {} } },
+        apple: { parameters: { type: "object", properties: {} } },
+        mango: { parameters: { type: "object", properties: {} } },
+      };
+
+      const result = toToolsJSONSchema(tools);
+      expect(Object.keys(result)).toEqual(["apple", "mango", "zebra"]);
+    });
+
+    it("produces byte-identical output regardless of insertion order", () => {
+      const a: Record<string, Tool> = {
+        zebra: { parameters: { type: "object", properties: {} } },
+        apple: { parameters: { type: "object", properties: {} } },
+      };
+      const b: Record<string, Tool> = {
+        apple: { parameters: { type: "object", properties: {} } },
+        zebra: { parameters: { type: "object", properties: {} } },
+      };
+
+      expect(JSON.stringify(toToolsJSONSchema(a))).toBe(
+        JSON.stringify(toToolsJSONSchema(b)),
+      );
+    });
   });
 
   describe("edge cases", () => {

package/src/core/tool/schema-utils.ts

@@ -1,6 +1,6 @@
 import type { JSONSchema7 } from "json-schema";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { Tool } from "./tool-types";
+import type { ProviderOptions, Tool } from "./tool-types";
 
 /**
  * Type for a tool definition with JSON Schema parameters.
@@ -8,6 +8,7 @@ import type { Tool } from "./tool-types";
 export type ToolJSONSchema = {
   description?: string;
   parameters: JSONSchema7;
+  providerOptions?: ProviderOptions;
 };
 
 export type ToToolsJSONSchemaOptions = {
@@ -135,6 +136,11 @@ function defaultToolFilter(_name: string, tool: Tool): boolean {
 /**
  * Converts a record of tools to a record of tool definitions with JSON Schema parameters.
  * By default, filters out disabled tools and backend tools.
+ *
+ * Entries are emitted in alphabetical order so the resulting request body is
+ * byte-identical regardless of the order in which tools were registered. This
+ * keeps provider prompt caches stable across renders that mount tools in
+ * different orders.
  */
 export function toToolsJSONSchema(
   tools: Record<string, Tool> | undefined,
@@ -147,11 +153,15 @@ export function toToolsJSONSchema(
   return Object.fromEntries(
     Object.entries(tools)
       .filter(([name, tool]) => filter(name, tool) && tool.parameters)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
       .map(([name, tool]) => [
         name,
         {
           ...(tool.description && { description: tool.description }),
           parameters: toJSONSchema(tool.parameters!),
+          ...(tool.providerOptions && {
+            providerOptions: tool.providerOptions,
+          }),
         },
       ]),
   );