stream.ts

export type ApiStream = AsyncGenerator<ApiStreamChunk>

export type ApiStreamChunk =
	| ApiStreamTextChunk
	| ApiStreamUsageChunk
	| ApiStreamReasoningChunk
	| ApiStreamThinkingCompleteChunk
	| ApiStreamGroundingChunk
	| ApiStreamToolCallChunk
	| ApiStreamToolCallStartChunk
	| ApiStreamToolCallDeltaChunk
	| ApiStreamToolCallEndChunk
	| ApiStreamToolCallPartialChunk
	| ApiStreamError

export interface ApiStreamError {
	type: "error"
	error: string
	message: string
}

export interface ApiStreamTextChunk {
	type: "text"
	text: string
}

/**
 * Reasoning/thinking chunk from the API stream.
 * For Anthropic extended thinking, this may include a signature field
 * which is required for passing thinking blocks back to the API during tool use.
 */
export interface ApiStreamReasoningChunk {
	type: "reasoning"
	text: string
	/**
	 * Signature for the thinking block (Anthropic extended thinking).
	 * When present, this indicates a complete thinking block that should be
	 * preserved for tool use continuations. The signature is used to verify
	 * that thinking blocks were generated by Claude.
	 */
	signature?: string
}

/**
 * Signals completion of a thinking block with its verification signature.
 * Used by Anthropic extended thinking to pass the signature needed for
 * tool use continuations and caching.
 */
export interface ApiStreamThinkingCompleteChunk {
	type: "thinking_complete"
	/**
	 * Cryptographic signature that verifies this thinking block was generated by Claude.
	 * Must be preserved and passed back to the API when continuing conversations with tool use.
	 */
	signature: string
}

export interface ApiStreamUsageChunk {
	type: "usage"
	inputTokens: number
	outputTokens: number
	cacheWriteTokens?: number
	cacheReadTokens?: number
	reasoningTokens?: number
	totalCost?: number
}

export interface ApiStreamGroundingChunk {
	type: "grounding"
	sources: GroundingSource[]
}

export interface ApiStreamToolCallChunk {
	type: "tool_call"
	id: string
	name: string
	arguments: string
}

export interface ApiStreamToolCallStartChunk {
	type: "tool_call_start"
	id: string
	name: string
}

export interface ApiStreamToolCallDeltaChunk {
	type: "tool_call_delta"
	id: string
	delta: string
}

export interface ApiStreamToolCallEndChunk {
	type: "tool_call_end"
	id: string
}

/**
 * Raw tool call chunk from the API stream.
 * Providers emit this simple format; NativeToolCallParser handles all state management
 * (tracking, buffering, emitting start/delta/end events).
 */
export interface ApiStreamToolCallPartialChunk {
	type: "tool_call_partial"
	index: number
	id?: string
	name?: string
	arguments?: string
}

export interface GroundingSource {
	title: string
	url: string
	snippet?: string
}