@kernl-sdk/protocol 0.4.2 → 0.5.1

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @kernl-sdk/protocol@0.4.2 build /home/runner/work/kernl/kernl/packages/protocol
+> @kernl-sdk/protocol@0.5.1 build /home/runner/work/kernl/kernl/packages/protocol
 > tsc && tsc-alias --resolve-full-paths
 

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @kernl/protocol
 
+## 0.5.1
+
+### Patch Changes
+
+- 884e513: Align with @ai-sdk/provider v3 stable release
+  - Update LanguageModelUsage to nested structure (inputTokens.total, outputTokens.total, etc.)
+  - Update LanguageModelFinishReason to object with unified and raw properties
+  - Rename LanguageModelWarning to SharedWarning with updated structure
+  - Update tool type from "provider-defined" to "provider"
+  - Bump @ai-sdk peer dependencies from beta to stable (^3.0.3)
+
+## 0.5.0
+
+### Minor Changes
+
+- 8815744: **BREAKING:** Refactor event kind naming from kebab-case to dot notation
+
+  This aligns the language model stream/item kinds with the existing realtime events naming convention.
+
+  ### Kind value changes
+
+  | Old                | New                |
+  | ------------------ | ------------------ |
+  | `tool-call`        | `tool.call`        |
+  | `tool-result`      | `tool.result`      |
+  | `text-start`       | `text.start`       |
+  | `text-delta`       | `text.delta`       |
+  | `text-end`         | `text.end`         |
+  | `reasoning-start`  | `reasoning.start`  |
+  | `reasoning-delta`  | `reasoning.delta`  |
+  | `reasoning-end`    | `reasoning.end`    |
+  | `tool-input-start` | `tool.input.start` |
+  | `tool-input-delta` | `tool.input.delta` |
+  | `tool-input-end`   | `tool.input.end`   |
+  | `stream-start`     | `stream.start`     |
+
+  ### ToolInputStartEvent: `toolName` → `toolId`
+
+  The `ToolInputStartEvent` now uses `toolId` to match `ToolCall` and `ToolResult`.
+
+  ### Migration
+
+  If you have persisted thread events, run:
+
+  ```sql
+  UPDATE thread_events SET kind = 'tool.call' WHERE kind = 'tool-call';
+  UPDATE thread_events SET kind = 'tool.result' WHERE kind = 'tool-result';
+  ```
+
 ## 0.4.2
 
 ### Patch Changes

package/dist/language-model/item.d.ts

@@ -144,7 +144,7 @@ export type Message = SystemMessage | AssistantMessage | UserMessage;
  * Tool calls that the model has generated.
  */
 export interface ToolCall extends LanguageModelItemBase {
-    readonly kind: "tool-call";
+    readonly kind: "tool.call";
     /**
      * The identifier of the tool call. It must be unique across all tool calls.
      */
@@ -166,7 +166,7 @@ export interface ToolCall extends LanguageModelItemBase {
  * Result of a tool call that has been executed by the provider.
  */
 export interface ToolResult extends LanguageModelItemBase {
-    readonly kind: "tool-result";
+    readonly kind: "tool.result";
     /**
      * The ID of the tool call that this result is associated with.
      */

package/dist/language-model/model.d.ts

@@ -2,7 +2,6 @@ import { SharedProviderMetadata } from "../provider/index.js";
 import { LanguageModelResponseItem } from "./item.js";
 import { LanguageModelRequest } from "./request.js";
 import { LanguageModelStreamEvent } from "./stream.js";
-import { LanguageModelFunctionTool, LanguageModelProviderTool } from "./tool.js";
 /**
  * Defines the standard interface for language model providers in kernl.
  */
@@ -51,7 +50,7 @@ export interface LanguageModelResponse {
     /**
      * Warnings for the call, e.g. unsupported settings.
      */
-    warnings: LanguageModelWarning[];
+    warnings: SharedWarning[];
     /**
      * Raw response data from the underlying model provider.
      */
@@ -60,7 +59,23 @@ export interface LanguageModelResponse {
 /**
  * Reason why a language model finished generating a response.
  */
-export type LanguageModelFinishReason = "stop" | "length" | "content-filter" | "tool-calls" | "error" | "other" | "unknown";
+export interface LanguageModelFinishReason {
+    /**
+     * Unified finish reason across providers.
+     *
+     * - `stop`: model generated stop sequence
+     * - `length`: model generated maximum number of tokens
+     * - `content-filter`: content filter violation stopped the model
+     * - `tool-calls`: model triggered tool calls
+     * - `error`: model stopped because of an error
+     * - `other`: model stopped for other reasons
+     */
+    unified: "stop" | "length" | "content-filter" | "tool-calls" | "error" | "other";
+    /**
+     * Raw finish reason from the provider.
+     */
+    raw: string | undefined;
+}
 /**
  * Usage information for a language model call.
  *
@@ -69,42 +84,82 @@ export type LanguageModelFinishReason = "stop" | "length" | "content-filter" | "
  */
 export interface LanguageModelUsage {
     /**
-     * The number of input (prompt) tokens used.
+     * Input token usage breakdown.
      */
-    inputTokens: number | undefined;
+    inputTokens: {
+        /**
+         * Total input tokens used.
+         */
+        total: number | undefined;
+        /**
+         * Input tokens that were not cached.
+         */
+        noCache: number | undefined;
+        /**
+         * Input tokens read from cache.
+         */
+        cacheRead: number | undefined;
+        /**
+         * Input tokens written to cache.
+         */
+        cacheWrite: number | undefined;
+    };
     /**
-     * The number of output (completion) tokens used.
+     * Output token usage breakdown.
      */
-    outputTokens: number | undefined;
+    outputTokens: {
+        /**
+         * Total output tokens used.
+         */
+        total: number | undefined;
+        /**
+         * Text generation tokens.
+         */
+        text: number | undefined;
+        /**
+         * Reasoning/thinking tokens.
+         */
+        reasoning: number | undefined;
+    };
+}
+/**
+ * Warning from the model provider for this call. The call will proceed, but e.g.
+ * some settings might not be supported, which can lead to suboptimal results.
+ */
+export type SharedWarning = {
     /**
-     * The total number of tokens as reported by the provider.
-     * This number might be different from the sum of `inputTokens` and `outputTokens`
-     * and e.g. include reasoning tokens or other overhead.
+     * A feature is not supported by the model.
      */
-    totalTokens: number | undefined;
+    type: "unsupported";
     /**
-     * The number of reasoning tokens used.
+     * The feature that is not supported.
      */
-    reasoningTokens?: number | undefined;
+    feature: string;
     /**
-     * The number of cached input tokens.
+     * Additional details about the warning.
      */
-    cachedInputTokens?: number | undefined;
-}
-/**
- * Warning from the model provider for this call. The call will proceed, but e.g.
- * some settings might not be supported, which can lead to suboptimal results.
- */
-export type LanguageModelWarning = {
-    type: "unsupported-setting";
-    setting: Omit<keyof LanguageModelRequest, "input">;
     details?: string;
 } | {
-    type: "unsupported-tool";
-    tool: LanguageModelFunctionTool | LanguageModelProviderTool;
+    /**
+     * A compatibility feature is used that might lead to suboptimal results.
+     */
+    type: "compatibility";
+    /**
+     * The feature that is used in compatibility mode.
+     */
+    feature: string;
+    /**
+     * Additional details about the warning.
+     */
     details?: string;
 } | {
+    /**
+     * Other warning.
+     */
     type: "other";
+    /**
+     * The message of the warning.
+     */
     message: string;
 };
 //# sourceMappingURL=model.d.ts.map

package/dist/language-model/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/language-model/model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAAE,yBAAyB,EAAE,MAAM,QAAQ,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,MAAM,QAAQ,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAExE;;;;OAIG;IACH,MAAM,CACJ,OAAO,EAAE,oBAAoB,GAC5B,aAAa,CAAC,wBAAwB,CAAC,CAAC;CAiB5C;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAOpC;;OAEG;IACH,OAAO,EAAE,yBAAyB,EAAE,CAAC;IAErC;;OAEG;IACH,YAAY,EAAE,yBAAyB,CAAC;IAExC;;OAEG;IACH,KAAK,EAAE,kBAAkB,CAAC;IAE1B;;OAEG;IACH,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IAEjC;;OAEG;IACH,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,MAAM,yBAAyB,GACjC,MAAM,GACN,QAAQ,GACR,gBAAgB,GAChB,YAAY,GACZ,OAAO,GACP,OAAO,GACP,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAEhC;;OAEG;IACH,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAEjC;;;;OAIG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAEhC;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAErC;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IACE,IAAI,EAAE,qBAAqB,CAAC;IAC5B,OAAO,EAAE,IAAI,CAAC,MAAM,oBAAoB,EAAE,OAAO,CAAC,CAAC;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACD;IACE,IAAI,EAAE,kBAAkB,CAAC;IACzB,IAAI,EAAE,yBAAyB,GAAG,yBAAyB,CAAC;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/language-model/model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAAE,yBAAyB,EAAE,MAAM,QAAQ,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAC;AAGpD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAExE;;;;OAIG;IACH,MAAM,CACJ,OAAO,EAAE,oBAAoB,GAC5B,aAAa,CAAC,wBAAwB,CAAC,CAAC;CAiB5C;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAOpC;;OAEG;IACH,OAAO,EAAE,yBAAyB,EAAE,CAAC;IAErC;;OAEG;IACH,YAAY,EAAE,yBAAyB,CAAC;IAExC;;OAEG;IACH,KAAK,EAAE,kBAAkB,CAAC;IAE1B;;OAEG;IACH,QAAQ,EAAE,aAAa,EAAE,CAAC;IAE1B;;OAEG;IACH,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;;OASG;IACH,OAAO,EACH,MAAM,GACN,QAAQ,GACR,gBAAgB,GAChB,YAAY,GACZ,OAAO,GACP,OAAO,CAAC;IAEZ;;OAEG;IACH,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,WAAW,EAAE;QACX;;WAEG;QACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;QAE1B;;WAEG;QACH,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;QAE5B;;WAEG;QACH,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;QAE9B;;WAEG;QACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;KAChC,CAAC;IAEF;;OAEG;IACH,YAAY,EAAE;QACZ;;WAEG;QACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;QAE1B;;WAEG;QACH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;QAEzB;;WAEG;QACH,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;KAC/B,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GACrB;IACE;;OAEG;IACH,IAAI,EAAE,aAAa,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACD;IACE;;OAEG;IACH,IAAI,EAAE,eAAe,CAAC;IAEtB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACD;IACE;;OAEG;IACH,IAAI,EAAE,OAAO,CAAC;IAEd;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC"}

package/dist/language-model/stream.d.ts

@@ -1,5 +1,5 @@
 import { SharedProviderMetadata } from "../provider/index.js";
-import type { LanguageModelFinishReason, LanguageModelUsage, LanguageModelWarning } from "./model.js";
+import type { LanguageModelFinishReason, LanguageModelUsage, SharedWarning } from "./model.js";
 import type { Message, Reasoning, ToolCall, ToolResult } from "./item.js";
 /**
  * Union of all language model stream events.
@@ -22,21 +22,21 @@ export interface StreamEventBase {
  * Stream event indicating the start of a text output.
  */
 export interface TextStartEvent extends StreamEventBase {
-    readonly kind: "text-start";
+    readonly kind: "text.start";
     id: string;
 }
 /**
  * Stream event indicating the end of a text output.
  */
 export interface TextEndEvent extends StreamEventBase {
-    readonly kind: "text-end";
+    readonly kind: "text.end";
     id: string;
 }
 /**
  * Stream event containing a delta (chunk) of text output.
  */
 export interface TextDeltaEvent extends StreamEventBase {
-    readonly kind: "text-delta";
+    readonly kind: "text.delta";
     id: string;
     /**
      * The incremental text chunk.
@@ -47,21 +47,21 @@ export interface TextDeltaEvent extends StreamEventBase {
  * Stream event indicating the start of reasoning output.
  */
 export interface ReasoningStartEvent extends StreamEventBase {
-    readonly kind: "reasoning-start";
+    readonly kind: "reasoning.start";
     id: string;
 }
 /**
  * Stream event indicating the end of reasoning output.
  */
 export interface ReasoningEndEvent extends StreamEventBase {
-    readonly kind: "reasoning-end";
+    readonly kind: "reasoning.end";
     id: string;
 }
 /**
  * Stream event containing a delta (chunk) of reasoning output.
  */
 export interface ReasoningDeltaEvent extends StreamEventBase {
-    readonly kind: "reasoning-delta";
+    readonly kind: "reasoning.delta";
     id: string;
     /**
      * The incremental reasoning text chunk.
@@ -72,12 +72,12 @@ export interface ReasoningDeltaEvent extends StreamEventBase {
  * Stream event indicating the start of tool input generation.
  */
 export interface ToolInputStartEvent extends StreamEventBase {
-    readonly kind: "tool-input-start";
+    readonly kind: "tool.input.start";
     id: string;
     /**
-     * The name of the tool being called.
+     * The identifier of the tool being called.
      */
-    toolName: string;
+    toolId: string;
     /**
      * Optional title for the tool call.
      */
@@ -87,14 +87,14 @@ export interface ToolInputStartEvent extends StreamEventBase {
  * Stream event indicating the end of tool input generation.
  */
 export interface ToolInputEndEvent extends StreamEventBase {
-    readonly kind: "tool-input-end";
+    readonly kind: "tool.input.end";
     id: string;
 }
 /**
  * Stream event containing a delta (chunk) of tool input.
  */
 export interface ToolInputDeltaEvent extends StreamEventBase {
-    readonly kind: "tool-input-delta";
+    readonly kind: "tool.input.delta";
     id: string;
     /**
      * The incremental tool input chunk.
@@ -105,11 +105,11 @@ export interface ToolInputDeltaEvent extends StreamEventBase {
  * Stream event indicating the start of agent execution.
  */
 export interface StartEvent extends StreamEventBase {
-    readonly kind: "stream-start";
+    readonly kind: "stream.start";
     /**
      * Warnings for the call (e.g., unsupported settings).
      */
-    warnings?: LanguageModelWarning[];
+    warnings?: SharedWarning[];
 }
 /**
  * Stream event indicating the completion of agent execution.

package/dist/language-model/stream.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernl-sdk/protocol",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Protocol specification for kernl",
   "keywords": [
     "kernl",

package/src/language-model/item.ts

@@ -195,7 +195,7 @@ export type Message = SystemMessage | AssistantMessage | UserMessage;
  * Tool calls that the model has generated.
  */
 export interface ToolCall extends LanguageModelItemBase {
-  readonly kind: "tool-call";
+  readonly kind: "tool.call";
 
   /**
    * The identifier of the tool call. It must be unique across all tool calls.
@@ -222,7 +222,7 @@ export interface ToolCall extends LanguageModelItemBase {
  * Result of a tool call that has been executed by the provider.
  */
 export interface ToolResult extends LanguageModelItemBase {
-  readonly kind: "tool-result";
+  readonly kind: "tool.result";
 
   /**
    * The ID of the tool call that this result is associated with.

package/src/language-model/model.ts

@@ -85,7 +85,7 @@ export interface LanguageModelResponse {
   /**
    * Warnings for the call, e.g. unsupported settings.
    */
-  warnings: LanguageModelWarning[];
+  warnings: SharedWarning[];
 
   /**
    * Raw response data from the underlying model provider.
@@ -96,14 +96,30 @@ export interface LanguageModelResponse {
 /**
  * Reason why a language model finished generating a response.
  */
-export type LanguageModelFinishReason =
-  | "stop" /* model generated stop sequence */
-  | "length" /* model generated maximum number of tokens */
-  | "content-filter" /* content filter violation stopped the model */
-  | "tool-calls" /* model triggered tool calls */
-  | "error" /* model stopped because of an error */
-  | "other" /* model stopped for other reasons */
-  | "unknown"; /* the model has not transmitted a finish reason */
+export interface LanguageModelFinishReason {
+  /**
+   * Unified finish reason across providers.
+   *
+   * - `stop`: model generated stop sequence
+   * - `length`: model generated maximum number of tokens
+   * - `content-filter`: content filter violation stopped the model
+   * - `tool-calls`: model triggered tool calls
+   * - `error`: model stopped because of an error
+   * - `other`: model stopped for other reasons
+   */
+  unified:
+    | "stop"
+    | "length"
+    | "content-filter"
+    | "tool-calls"
+    | "error"
+    | "other";
+
+  /**
+   * Raw finish reason from the provider.
+   */
+  raw: string | undefined;
+}
 
 /**
  * Usage information for a language model call.
@@ -113,49 +129,96 @@ export type LanguageModelFinishReason =
  */
 export interface LanguageModelUsage {
   /**
-   * The number of input (prompt) tokens used.
+   * Input token usage breakdown.
    */
-  inputTokens: number | undefined;
+  inputTokens: {
+    /**
+     * Total input tokens used.
+     */
+    total: number | undefined;
+
+    /**
+     * Input tokens that were not cached.
+     */
+    noCache: number | undefined;
+
+    /**
+     * Input tokens read from cache.
+     */
+    cacheRead: number | undefined;
+
+    /**
+     * Input tokens written to cache.
+     */
+    cacheWrite: number | undefined;
+  };
 
   /**
-   * The number of output (completion) tokens used.
+   * Output token usage breakdown.
    */
-  outputTokens: number | undefined;
-
-  /**
-   * The total number of tokens as reported by the provider.
-   * This number might be different from the sum of `inputTokens` and `outputTokens`
-   * and e.g. include reasoning tokens or other overhead.
-   */
-  totalTokens: number | undefined;
-
-  /**
-   * The number of reasoning tokens used.
-   */
-  reasoningTokens?: number | undefined;
-
-  /**
-   * The number of cached input tokens.
-   */
-  cachedInputTokens?: number | undefined;
+  outputTokens: {
+    /**
+     * Total output tokens used.
+     */
+    total: number | undefined;
+
+    /**
+     * Text generation tokens.
+     */
+    text: number | undefined;
+
+    /**
+     * Reasoning/thinking tokens.
+     */
+    reasoning: number | undefined;
+  };
 }
 
 /**
  * Warning from the model provider for this call. The call will proceed, but e.g.
  * some settings might not be supported, which can lead to suboptimal results.
  */
-export type LanguageModelWarning =
+export type SharedWarning =
   | {
-      type: "unsupported-setting";
-      setting: Omit<keyof LanguageModelRequest, "input">; // (TODO): allow string
+      /**
+       * A feature is not supported by the model.
+       */
+      type: "unsupported";
+
+      /**
+       * The feature that is not supported.
+       */
+      feature: string;
+
+      /**
+       * Additional details about the warning.
+       */
       details?: string;
     }
   | {
-      type: "unsupported-tool";
-      tool: LanguageModelFunctionTool | LanguageModelProviderTool;
+      /**
+       * A compatibility feature is used that might lead to suboptimal results.
+       */
+      type: "compatibility";
+
+      /**
+       * The feature that is used in compatibility mode.
+       */
+      feature: string;
+
+      /**
+       * Additional details about the warning.
+       */
       details?: string;
     }
   | {
+      /**
+       * Other warning.
+       */
       type: "other";
+
+      /**
+       * The message of the warning.
+       */
       message: string;
     };

package/src/language-model/stream.ts

@@ -3,7 +3,7 @@ import { SharedProviderMetadata } from "@/provider";
 import type {
   LanguageModelFinishReason,
   LanguageModelUsage,
-  LanguageModelWarning,
+  SharedWarning,
 } from "./model";
 import type { Message, Reasoning, ToolCall, ToolResult } from "./item";
 
@@ -49,7 +49,7 @@ export interface StreamEventBase {
  * Stream event indicating the start of a text output.
  */
 export interface TextStartEvent extends StreamEventBase {
-  readonly kind: "text-start";
+  readonly kind: "text.start";
   id: string;
 }
 
@@ -57,7 +57,7 @@ export interface TextStartEvent extends StreamEventBase {
  * Stream event indicating the end of a text output.
  */
 export interface TextEndEvent extends StreamEventBase {
-  readonly kind: "text-end";
+  readonly kind: "text.end";
   id: string;
 }
 
@@ -65,7 +65,7 @@ export interface TextEndEvent extends StreamEventBase {
  * Stream event containing a delta (chunk) of text output.
  */
 export interface TextDeltaEvent extends StreamEventBase {
-  readonly kind: "text-delta";
+  readonly kind: "text.delta";
   id: string;
 
   /**
@@ -78,7 +78,7 @@ export interface TextDeltaEvent extends StreamEventBase {
  * Stream event indicating the start of reasoning output.
  */
 export interface ReasoningStartEvent extends StreamEventBase {
-  readonly kind: "reasoning-start";
+  readonly kind: "reasoning.start";
   id: string;
 }
 
@@ -86,7 +86,7 @@ export interface ReasoningStartEvent extends StreamEventBase {
  * Stream event indicating the end of reasoning output.
  */
 export interface ReasoningEndEvent extends StreamEventBase {
-  readonly kind: "reasoning-end";
+  readonly kind: "reasoning.end";
   id: string;
 }
 
@@ -94,7 +94,7 @@ export interface ReasoningEndEvent extends StreamEventBase {
  * Stream event containing a delta (chunk) of reasoning output.
  */
 export interface ReasoningDeltaEvent extends StreamEventBase {
-  readonly kind: "reasoning-delta";
+  readonly kind: "reasoning.delta";
   id: string;
 
   /**
@@ -107,13 +107,13 @@ export interface ReasoningDeltaEvent extends StreamEventBase {
  * Stream event indicating the start of tool input generation.
  */
 export interface ToolInputStartEvent extends StreamEventBase {
-  readonly kind: "tool-input-start";
+  readonly kind: "tool.input.start";
   id: string;
 
   /**
-   * The name of the tool being called.
+   * The identifier of the tool being called.
    */
-  toolName: string;
+  toolId: string;
 
   /**
    * Optional title for the tool call.
@@ -125,7 +125,7 @@ export interface ToolInputStartEvent extends StreamEventBase {
  * Stream event indicating the end of tool input generation.
  */
 export interface ToolInputEndEvent extends StreamEventBase {
-  readonly kind: "tool-input-end";
+  readonly kind: "tool.input.end";
   id: string;
 }
 
@@ -133,7 +133,7 @@ export interface ToolInputEndEvent extends StreamEventBase {
  * Stream event containing a delta (chunk) of tool input.
  */
 export interface ToolInputDeltaEvent extends StreamEventBase {
-  readonly kind: "tool-input-delta";
+  readonly kind: "tool.input.delta";
   id: string;
 
   /**
@@ -146,12 +146,12 @@ export interface ToolInputDeltaEvent extends StreamEventBase {
  * Stream event indicating the start of agent execution.
  */
 export interface StartEvent extends StreamEventBase {
-  readonly kind: "stream-start";
+  readonly kind: "stream.start";
 
   /**
    * Warnings for the call (e.g., unsupported settings).
    */
-  warnings?: LanguageModelWarning[];
+  warnings?: SharedWarning[];
 }
 
 /**