stream.ts

export type ApiStream = AsyncGenerator<ApiStreamChunk>

export type ApiStreamChunk =
	| ApiStreamTextChunk
	| ApiStreamUsageChunk
	| ApiStreamReasoningChunk
	| ApiStreamThinkingCompleteChunk
	| ApiStreamGroundingChunk
	| ApiStreamToolCallChunk
	| ApiStreamToolCallStartChunk
	| ApiStreamToolCallDeltaChunk
	| ApiStreamToolCallEndChunk
	| ApiStreamToolCallPartialChunk
	| ApiStreamToolPreparingChunk
	| ApiStreamResponseMetadataChunk
	| 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
}

/**
 * Progress update on an in-progress tool call argument stream.
 * Carries the tool name and bytes received so far so the UI can show
 * an inline row with a spinner and byte count rather than polluting
 * the thinking bubble.
 */
export interface ApiStreamToolPreparingChunk {
	type: "tool_preparing"
	toolName: string
	byteCount: number
}

/** Response metadata from the Shofer LLM provider (shofer-router).
 *  Emitted once at stream end via the \\x00response_metadata\\x00 marker.
 *  Carries per-request diagnostics: actual model served, latency, token
 *  counts, cost, and failover info. */
export interface ApiStreamResponseMetadataChunk {
	type: "response_metadata"
	/** The composite model ID requested by Shofer. */
	model?: string
	/** The underlying model that actually served the request (may differ
	 *  from model when failover / multi-provider routing is active). */
	actualModel?: string
	/** Time to first byte in milliseconds. */
	ttfbMs?: number
	/** Total time in milliseconds. */
	ttlbMs?: number
	/** Prompt tokens consumed (may be 0 for error responses). */
	promptTokens?: number
	/** Completion tokens generated (may be 0 for error responses). */
	completionTokens?: number
	/** USD cost for this request (approximate, pre-discount). */
	costUsd?: number
	/** Number of provider attempts (1 = first try succeeded). */
	attempts?: number
	/** Error message when the request failed. Undefined on success. */
	error?: string
}

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