zeroruntime

type AgentEventType string

type CollectOptions struct {
	OnText      func(string)
	OnReasoning func(string)
	OnUsage     func(Usage)
	// OnToolCallStart fires when a tool call opens (id + tool name), and
	// OnToolCallDelta fires for each streamed argument fragment. Together they let
	// a surface render a tool call's arguments LIVE (e.g. a file being written)
	// instead of waiting for the whole call to accumulate. nil is a no-op.
	OnToolCallStart func(id, name string)
	OnToolCallDelta func(id, fragment string)
}

type CollectedStream struct {
	Text             string
	ToolCalls        []ToolCall
	Usage            Usage
	Error            string
	DroppedToolCalls int // malformed tool calls the provider could not dispatch
	// FinishReason is the provider's normalized terminal stop reason when the
	// response did not end normally (FinishReasonLength / FinishReasonContentFilter).
	// It is empty for a normal completion. Truncated reports whether it is set.
	FinishReason string
	// ReasoningBlocks are the response's preserved reasoning artifacts (Anthropic
	// thinking blocks) that must be replayed on the next turn. Empty for providers
	// or runs without extended thinking.
	ReasoningBlocks []ReasoningBlock
	// HasReasoning records whether the provider streamed reasoning deltas. The
	// deltas remain non-answer content, but they still prove the turn was live.
	HasReasoning bool
}

type CompletionRequest struct {
	Messages []Message
	Tools    []ToolDefinition
	// ReasoningEffort, when non-empty, asks a reasoning-capable model to spend the
	// given level of thinking effort ("minimal"/"low"/"medium"/"high"). Each
	// provider adapter maps it to its own API shape (OpenAI reasoning_effort,
	// Anthropic/Gemini thinking budgets) and ignores it for models that do not
	// support reasoning. Empty means "let the provider decide".
	ReasoningEffort string
	// PromptCacheKey, when non-empty, is an opaque stable identifier for the
	// conversation (the session ID). Providers with server-side prefix-cache
	// routing forward it — OpenAI `prompt_cache_key` — so consecutive requests
	// land on a replica that already holds the cached prompt prefix instead of
	// re-billing the full prefix each turn. Providers without an equivalent
	// ignore it.
	PromptCacheKey string
}

type ImageBlock struct {
	MediaType string
	Data      []byte
}

type Message struct {
	Role       MessageRole
	Content    string
	ToolCalls  []ToolCall
	ToolCallID string
	Images     []ImageBlock     // optional; nil for text-only messages
	Reasoning  []ReasoningBlock // optional; preserved thinking blocks to replay
}

type MessageRole string

type Provider interface {
	StreamCompletion(ctx context.Context, request CompletionRequest) (<-chan StreamEvent, error)
}

type ReasoningBlock struct {
	Provider  string // adapter that produced and can replay this block ("anthropic", "gemini")
	Type      string // provider block type ("thinking", "redacted_thinking")
	Text      string // human-readable reasoning text (empty for redacted/opaque blocks)
	Signature string // cryptographic signature the provider requires on replay
	Data      string // opaque provider payload (e.g. Anthropic redacted_thinking data)
}

type StreamEvent struct {
	Type              StreamEventType
	Content           string
	ToolCallID        string
	ToolName          string
	ToolCallSignature string // opaque reasoning signature bound to this call (Gemini thoughtSignature)
	ArgumentsFragment string
	Usage             Usage
	Error             string
	// FinishReason carries the provider's normalized terminal stop reason when a
	// response did not end normally (e.g. FinishReasonLength when the output hit
	// the token cap, or FinishReasonContentFilter when it was filtered). It is
	// empty for a normal completion. Providers set it on the terminal/done event.
	FinishReason string
	// ReasoningBlocks carries completed reasoning artifacts (Anthropic thinking /
	// redacted_thinking blocks) that must be preserved for replay. Providers attach
	// them to the terminal/done event; the collector accumulates them.
	ReasoningBlocks []ReasoningBlock
}

type StreamEventType string

type TokenUsage struct {
	InputTokens       int
	PromptTokens      int
	CachedInputTokens int
	// CacheWriteTokens is the cache-creation (cache-write) portion of the input,
	// billed at a premium rate by providers that support it (e.g. Anthropic).
	// Like CachedInputTokens it is a SUBSET of InputTokens, not additive.
	CacheWriteTokens int
	OutputTokens     int
	CompletionTokens int
	ReasoningTokens  int
}

type ToolCall struct {
	ID        string
	Name      string
	Arguments string
	// Signature carries a provider's opaque reasoning signature bound to this call
	// (Gemini attaches a thoughtSignature to a functionCall part). It must be
	// echoed back with the call on later turns or the provider may reject the
	// multi-turn function-calling conversation. Empty for providers that do not
	// use it. Only the originating adapter interprets it.
	Signature string
}

type ToolDefinition struct {
	Name        string
	Description string
	Parameters  map[string]any
}

type Usage struct {
	InputTokens       int
	OutputTokens      int
	PromptTokens      int
	CompletionTokens  int
	CachedInputTokens int
	CacheWriteTokens  int
	ReasoningTokens   int
}