@opencode-ai/ai 0.0.0-beta-17492

package/dist/protocols/utils/tool-stream.d.ts

@@ -0,0 +1,639 @@
+import { Effect } from "effect";
+import { AIError, LLMEvent, type ProviderMetadata } from "../../schema/index.js";
+import { type ToolAccumulator } from "../shared.js";
+type StreamKey = string | number;
+/**
+ * One pending streamed tool call. Providers emit the tool identity and JSON
+ * argument text across separate chunks; `input` is the raw JSON string collected
+ * so far, not the parsed object.
+ */
+export interface PendingTool extends ToolAccumulator {
+    readonly providerExecuted?: boolean;
+    readonly providerMetadata?: ProviderMetadata;
+}
+/**
+ * Sparse parser state keyed by the provider's stream-local tool identifier.
+ *
+ * This key is not the final tool-call id (`call_...`). It is the id/index the
+ * provider uses while streaming a partial call: OpenAI Chat / Anthropic /
+ * Bedrock use numeric content indexes, while OpenAI Responses uses string
+ * `item_id`s. The generic keeps each protocol internally consistent.
+ */
+export type State<K extends StreamKey> = Partial<Record<K, PendingTool>>;
+/**
+ * Result of adding argument text to one pending tool call. It returns both the
+ * next `tools` state and the updated `tool` because parsers often need the
+ * current id/name immediately. `events` contains lifecycle and delta events
+ * produced by the append; metadata-only deltas update identity without output.
+ */
+export interface AppendOutcome<K extends StreamKey> {
+    readonly tools: State<K>;
+    readonly tool: PendingTool;
+    readonly events: ReadonlyArray<LLMEvent>;
+}
+/** Create empty accumulator state for one provider stream. */
+export declare const empty: <K extends StreamKey>() => State<K>;
+export declare const isError: <K extends StreamKey>(result: AppendOutcome<K> | AIError) => result is AIError;
+/**
+ * Register a tool call whose start event arrived before any argument deltas.
+ * Used by Anthropic `content_block_start`, Bedrock `contentBlockStart`, and
+ * OpenAI Responses `response.output_item.added`.
+ */
+export declare const start: <K extends StreamKey>(tools: State<K>, key: K, tool: Omit<PendingTool, "input"> & {
+    readonly input?: string;
+}) => Partial<Record<K, PendingTool>>;
+/**
+ * Append a streamed argument delta, starting the tool if this provider encodes
+ * identity on the first delta instead of a separate start event. OpenAI Chat has
+ * this shape: `tool_calls[].index` is the stream key, and `id` / `name` may only
+ * appear on the first delta for that index.
+ */
+export declare const appendOrStart: <K extends StreamKey>(route: string, tools: State<K>, key: K, delta: {
+    readonly id?: string;
+    readonly name?: string;
+    readonly text: string;
+}, missingToolMessage: string) => AppendOutcome<K> | AIError;
+/**
+ * Append argument text to a tool that must already have been started. This keeps
+ * protocols honest when their stream grammar promises a start event before any
+ * argument delta.
+ */
+export declare const appendExisting: <K extends StreamKey>(route: string, tools: State<K>, key: K, text: string, missingToolMessage: string) => AppendOutcome<K> | AIError;
+/**
+ * Finalize one pending tool call: parse the accumulated raw JSON, remove it
+ * from state, and return either a call or a non-executable local input error.
+ * Missing keys are a no-op because some providers emit stop events for
+ * non-tool content blocks.
+ */
+export declare const finish: <K extends StreamKey>(route: string, tools: State<K>, key: K) => Effect.Effect<{
+    tools: Partial<Record<K, PendingTool>>;
+    events?: undefined;
+} | {
+    tools: Partial<Record<K, PendingTool>>;
+    events: readonly ({
+        readonly type: "step-start";
+        readonly index: number;
+    } | {
+        readonly id: string;
+        readonly type: "text-start";
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "text-delta";
+        readonly text: string;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "text-end";
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "reasoning-start";
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "reasoning-delta";
+        readonly text: string;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "reasoning-end";
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "tool-input-start";
+        readonly name: string;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly providerExecuted?: boolean | undefined;
+    } | {
+        readonly type: "tool-input-delta";
+        readonly id: string;
+        readonly name: string;
+        readonly text: string;
+    } | {
+        readonly id: string;
+        readonly type: "tool-input-end";
+        readonly name: string;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly type: "tool-input-error";
+        readonly id: string;
+        readonly name: string;
+        readonly raw: string;
+    } | {
+        readonly id: string;
+        readonly type: "tool-call";
+        readonly name: string;
+        readonly input: unknown;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly providerExecuted?: boolean | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "tool-result";
+        readonly name: string;
+        readonly result: {
+            readonly type: "json";
+            readonly value: unknown;
+        } | {
+            readonly type: "text";
+            readonly value: unknown;
+        } | {
+            readonly type: "error";
+            readonly value: unknown;
+        } | {
+            readonly type: "content";
+            readonly value: readonly ({
+                readonly type: "text";
+                readonly text: string;
+            } | {
+                readonly type: "file";
+                readonly uri: string;
+                readonly mime: string;
+                readonly name?: string | undefined;
+            })[];
+        };
+        readonly output?: {
+            readonly structured: unknown;
+            readonly content: readonly ({
+                readonly type: "text";
+                readonly text: string;
+            } | {
+                readonly type: "file";
+                readonly uri: string;
+                readonly mime: string;
+                readonly name?: string | undefined;
+            })[];
+        } | undefined;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly providerExecuted?: boolean | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "tool-error";
+        readonly name: string;
+        readonly message: string;
+        readonly error?: unknown;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly type: "step-finish";
+        readonly reason: {
+            readonly normalized: "length" | "stop" | "tool-calls" | "content-filter" | "error" | "unknown";
+            readonly raw?: string | undefined;
+        };
+        readonly index: number;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly usage?: import("../../schema/events.js").Usage | undefined;
+    } | {
+        readonly type: "finish";
+        readonly reason: {
+            readonly normalized: "length" | "stop" | "tool-calls" | "content-filter" | "error" | "unknown";
+            readonly raw?: string | undefined;
+        };
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly usage?: import("../../schema/events.js").Usage | undefined;
+    } | {
+        readonly type: "provider-error";
+        readonly message: string;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly classification?: "context-overflow" | "payload-too-large" | undefined;
+    })[];
+}, AIError, never>;
+/**
+ * Finalize one pending tool call with an authoritative final input string.
+ * OpenAI Responses can send accumulated deltas and then repeat the completed
+ * arguments on `response.output_item.done`; the final value wins.
+ */
+export declare const finishWithInput: <K extends StreamKey>(route: string, tools: State<K>, key: K, input: string) => Effect.Effect<{
+    tools: Partial<Record<K, PendingTool>>;
+    events?: undefined;
+} | {
+    tools: Partial<Record<K, PendingTool>>;
+    events: readonly ({
+        readonly type: "step-start";
+        readonly index: number;
+    } | {
+        readonly id: string;
+        readonly type: "text-start";
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "text-delta";
+        readonly text: string;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "text-end";
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "reasoning-start";
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "reasoning-delta";
+        readonly text: string;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "reasoning-end";
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "tool-input-start";
+        readonly name: string;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly providerExecuted?: boolean | undefined;
+    } | {
+        readonly type: "tool-input-delta";
+        readonly id: string;
+        readonly name: string;
+        readonly text: string;
+    } | {
+        readonly id: string;
+        readonly type: "tool-input-end";
+        readonly name: string;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly type: "tool-input-error";
+        readonly id: string;
+        readonly name: string;
+        readonly raw: string;
+    } | {
+        readonly id: string;
+        readonly type: "tool-call";
+        readonly name: string;
+        readonly input: unknown;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly providerExecuted?: boolean | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "tool-result";
+        readonly name: string;
+        readonly result: {
+            readonly type: "json";
+            readonly value: unknown;
+        } | {
+            readonly type: "text";
+            readonly value: unknown;
+        } | {
+            readonly type: "error";
+            readonly value: unknown;
+        } | {
+            readonly type: "content";
+            readonly value: readonly ({
+                readonly type: "text";
+                readonly text: string;
+            } | {
+                readonly type: "file";
+                readonly uri: string;
+                readonly mime: string;
+                readonly name?: string | undefined;
+            })[];
+        };
+        readonly output?: {
+            readonly structured: unknown;
+            readonly content: readonly ({
+                readonly type: "text";
+                readonly text: string;
+            } | {
+                readonly type: "file";
+                readonly uri: string;
+                readonly mime: string;
+                readonly name?: string | undefined;
+            })[];
+        } | undefined;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly providerExecuted?: boolean | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "tool-error";
+        readonly name: string;
+        readonly message: string;
+        readonly error?: unknown;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly type: "step-finish";
+        readonly reason: {
+            readonly normalized: "length" | "stop" | "tool-calls" | "content-filter" | "error" | "unknown";
+            readonly raw?: string | undefined;
+        };
+        readonly index: number;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly usage?: import("../../schema/events.js").Usage | undefined;
+    } | {
+        readonly type: "finish";
+        readonly reason: {
+            readonly normalized: "length" | "stop" | "tool-calls" | "content-filter" | "error" | "unknown";
+            readonly raw?: string | undefined;
+        };
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly usage?: import("../../schema/events.js").Usage | undefined;
+    } | {
+        readonly type: "provider-error";
+        readonly message: string;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly classification?: "context-overflow" | "payload-too-large" | undefined;
+    })[];
+}, AIError, never>;
+/**
+ * Finalize every pending tool call at once. OpenAI Chat has this shape: it does
+ * not emit per-tool stop events, so all accumulated calls finish independently
+ * when the choice receives a terminal `finish_reason`.
+ */
+export declare const finishAll: <K extends StreamKey>(route: string, tools: State<K>) => Effect.Effect<{
+    tools: Partial<Record<K, PendingTool>>;
+    events: ({
+        readonly type: "step-start";
+        readonly index: number;
+    } | {
+        readonly id: string;
+        readonly type: "text-start";
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "text-delta";
+        readonly text: string;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "text-end";
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "reasoning-start";
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "reasoning-delta";
+        readonly text: string;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "reasoning-end";
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "tool-input-start";
+        readonly name: string;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly providerExecuted?: boolean | undefined;
+    } | {
+        readonly type: "tool-input-delta";
+        readonly id: string;
+        readonly name: string;
+        readonly text: string;
+    } | {
+        readonly id: string;
+        readonly type: "tool-input-end";
+        readonly name: string;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly type: "tool-input-error";
+        readonly id: string;
+        readonly name: string;
+        readonly raw: string;
+    } | {
+        readonly id: string;
+        readonly type: "tool-call";
+        readonly name: string;
+        readonly input: unknown;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly providerExecuted?: boolean | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "tool-result";
+        readonly name: string;
+        readonly result: {
+            readonly type: "json";
+            readonly value: unknown;
+        } | {
+            readonly type: "text";
+            readonly value: unknown;
+        } | {
+            readonly type: "error";
+            readonly value: unknown;
+        } | {
+            readonly type: "content";
+            readonly value: readonly ({
+                readonly type: "text";
+                readonly text: string;
+            } | {
+                readonly type: "file";
+                readonly uri: string;
+                readonly mime: string;
+                readonly name?: string | undefined;
+            })[];
+        };
+        readonly output?: {
+            readonly structured: unknown;
+            readonly content: readonly ({
+                readonly type: "text";
+                readonly text: string;
+            } | {
+                readonly type: "file";
+                readonly uri: string;
+                readonly mime: string;
+                readonly name?: string | undefined;
+            })[];
+        } | undefined;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly providerExecuted?: boolean | undefined;
+    } | {
+        readonly id: string;
+        readonly type: "tool-error";
+        readonly name: string;
+        readonly message: string;
+        readonly error?: unknown;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    } | {
+        readonly type: "step-finish";
+        readonly reason: {
+            readonly normalized: "length" | "stop" | "tool-calls" | "content-filter" | "error" | "unknown";
+            readonly raw?: string | undefined;
+        };
+        readonly index: number;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly usage?: import("../../schema/events.js").Usage | undefined;
+    } | {
+        readonly type: "finish";
+        readonly reason: {
+            readonly normalized: "length" | "stop" | "tool-calls" | "content-filter" | "error" | "unknown";
+            readonly raw?: string | undefined;
+        };
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly usage?: import("../../schema/events.js").Usage | undefined;
+    } | {
+        readonly type: "provider-error";
+        readonly message: string;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly classification?: "context-overflow" | "payload-too-large" | undefined;
+    })[];
+}, AIError, never>;
+export * as ToolStream from "./tool-stream.js";