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 ProviderCapabilities struct {
	// Model is the resolved API model id (informational; may be empty).
	Model string
	// ContextWindow is the model's max input context in tokens; 0 = unknown.
	ContextWindow int
	// MaxOutputTokens is the model's max output tokens per turn; 0 = unknown.
	MaxOutputTokens int
	// SupportsVision mirrors the registry's vision capability.
	SupportsVision bool
	// SupportsReasoning mirrors the registry's reasoning capability.
	SupportsReasoning bool
	// SupportsPromptCache mirrors the registry's prompt-cache capability.
	SupportsPromptCache bool
	// ReasoningEfforts lists the accepted effort tiers, weakest to strongest.
	// nil/empty means the model exposes no effort control.
	ReasoningEfforts []string
	// NativeCompaction reports server-side compaction support. Always false for
	// the default adapter; a future native-compaction session sets it, and the
	// loop branches on it to call TurnSession.Compact instead of the local
	// summarizer.
	NativeCompaction bool
}

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 TurnSession interface {
	// Prewarm optionally primes provider-side state before the first Stream.
	// It must be safe to skip entirely: the default adapter no-ops and returns
	// nil. A non-nil error is advisory — callers proceed without prewarming
	// (best-effort, never fatal).
	Prewarm(ctx context.Context) error

	// Stream issues one completion request. The signature is identical to
	// Provider.StreamCompletion so the default adapter forwards verbatim and
	// callers' stream handling stays byte-for-byte unchanged.
	Stream(ctx context.Context, request CompletionRequest) (<-chan StreamEvent, error)

	// Compact asks the provider to compact the conversation server-side and
	// returns the replacement messages. The default adapter returns
	// ErrCompactionUnsupported; callers then keep their local summarizer path.
	Compact(ctx context.Context, request CompletionRequest) ([]Message, error)

	// Close releases per-run provider state. It must be idempotent and safe to
	// call after a mid-run swap as well as at run teardown. Default: no-op.
	Close() error
}

type TurnSessionProvider interface {
	// OpenTurnSession starts a session for one run. Everything a session needs
	// per request (messages, tools, reasoning effort, prompt-cache key) already
	// arrives on Stream, so nothing beyond ctx is passed here — keeping the
	// seam narrow. The default adapter never errors; a real implementation may
	// fail a handshake, which callers surface as a clean run-start error.
	OpenTurnSession(ctx context.Context) (TurnSession, error)

	// Capabilities returns the resolved model's static capability projection.
	Capabilities() ProviderCapabilities
}

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