ai

type Api ¶

type Api = string

Api identifies the wire protocol family.

const (
	ApiOpenAICompletions     Api = "openai-completions"
	ApiOpenAIResponses       Api = "openai-responses"
	ApiAnthropicMessages     Api = "anthropic-messages"
	ApiBedrockConverseStream Api = "bedrock-converse-stream"
	ApiGoogleGenerativeAI    Api = "google-generative-ai"
	ApiGoogleVertex          Api = "google-vertex"
)

type AssistantEvent ¶

type AssistantEvent interface {
	// contains filtered or unexported methods
}

AssistantEvent is the normalized event emitted by providers during generation.

type AssistantMessage ¶

type AssistantMessage struct {
	Content      []ContentBlock
	Api          string
	Provider     string
	Model        string
	Usage        Usage
	StopReason   StopReason
	ErrorMessage string
	Timestamp    time.Time
}

AssistantMessage contains assistant output and metadata.

type CacheRetention ¶

type CacheRetention = string

CacheRetention controls prompt cache retention preference.

const (
	CacheNone  CacheRetention = "none"
	CacheShort CacheRetention = "short"
	CacheLong  CacheRetention = "long"
)

type ChildToolCallAudit ¶ added in v0.66.0

type ChildToolCallAudit struct {
	ID        string        `json:"id"`
	Name      string        `json:"name"`
	IsError   bool          `json:"is_error"`
	ErrorKind ToolErrorKind `json:"error_kind,omitempty"`
}

ChildToolCallAudit records one Code Mode child invocation after it passed through the shared execution core. It intentionally contains no arguments, result content, or opaque Details: the audit is durable evaluation evidence, never a second provider-facing transcript.

Code Mode bounds this list by its fixed child-call limit. Native tool results leave it empty so their historical wire and persistence behaviour is intact.

type CommandExitError ¶ added in v0.65.0

type CommandExitError struct {
	Tool     string
	ExitCode int
}

CommandExitError is returned by a tool whose command completed with a nonzero exit status. It carries the distinction structurally so no consumer has to parse it back out of the message text.

func (e *CommandExitError) Error() string

type CommandTimeoutError ¶ added in v0.66.0

type CommandTimeoutError struct{ Tool string }

CommandTimeoutError is returned only when the bash call explicitly asked for a timeout and the sandbox reports its timeout sentinel. Consumers must use this type instead of reconstructing timeout meaning from rendered output.

func (e *CommandTimeoutError) Error() string

type CompleteOptions ¶

type CompleteOptions struct {
	StreamOptions
}

CompleteOptions configures non-streaming requests.

type ContentBlock ¶

type ContentBlock interface {
	// contains filtered or unexported methods
}

ContentBlock is the normalized assistant content unit.

func CloneContentBlocks(blocks []ContentBlock) []ContentBlock

func UnmarshalContentBlocks(data []byte) ([]ContentBlock, error)

type ContentBlockJSON ¶ added in v0.60.3

type ContentBlockJSON struct {
	Kind     string `json:"kind"`
	Text     string `json:"text,omitempty"`
	Data     string `json:"data,omitempty"`
	MimeType string `json:"mime_type,omitempty"`
	MediaID  string `json:"media_id,omitempty"`
}

ContentBlockJSON is the serialization for deferred group history, whose events are stored before any session claims them. Ordinary session history stores the same canonical references as message parts instead. There is deliberately no baseline field. The baseline belongs to the media object, not to the block that points at it, so it is read from ctx_media on hydration; a legacy row that still carries the key decodes as an unknown field and is ignored.

type Context ¶

type Context struct {
	System   string
	Messages []Message
	Tools    []ToolDefinition
	Metadata map[string]string
}

Context carries all conversation and tool state for a model request.

type EventDone ¶

type EventDone struct{}

EventDone signals stream completion.

type EventError ¶

type EventError struct {
	Err   error
	Error *AssistantMessage
}

EventError reports terminal provider errors.

type EventStart ¶

type EventStart struct {
	Time    time.Time
	Partial *AssistantMessage
}

EventStart signals the beginning of an assistant turn.

type EventStop ¶

type EventStop struct {
	Reason  StopReason
	Message *AssistantMessage
}

EventStop signals end of generation with reason.

type EventTextDelta ¶

type EventTextDelta struct {
	ContentIndex int
	Text         string
	Partial      *AssistantMessage
}

EventTextDelta carries incremental text output.

type EventTextEnd ¶

type EventTextEnd struct {
	ContentIndex int
	Content      string
	Partial      *AssistantMessage
}

EventTextEnd signals the end of a text content block.

type EventTextStart ¶

type EventTextStart struct {
	ContentIndex int
	Partial      *AssistantMessage
}

EventTextStart signals the start of a text content block.

type EventThinkingDelta ¶

type EventThinkingDelta struct {
	ContentIndex int
	Thinking     string
	Partial      *AssistantMessage
}

EventThinkingDelta carries incremental reasoning output.

type EventThinkingEnd ¶

type EventThinkingEnd struct {
	ContentIndex int
	Content      string
	Partial      *AssistantMessage
}

EventThinkingEnd signals the end of a thinking content block.

type EventThinkingStart ¶

type EventThinkingStart struct {
	ContentIndex int
	Partial      *AssistantMessage
}

EventThinkingStart signals the start of a thinking content block.

type EventToolCallDelta ¶

type EventToolCallDelta struct {
	ContentIndex int
	ID           string
	Name         string
	Arguments    string
	Partial      *AssistantMessage
}

EventToolCallDelta carries incremental tool-call updates.

type EventToolCallEnd ¶

type EventToolCallEnd struct {
	ContentIndex int
	ToolCall     ToolCall
	Partial      *AssistantMessage
}

EventToolCallEnd signals the end of a tool call content block.

type EventToolCallStart ¶

type EventToolCallStart struct {
	ContentIndex int
	Partial      *AssistantMessage
}

EventToolCallStart signals the start of a tool call content block.

type EventUsage ¶

type EventUsage struct {
	Usage Usage
}

EventUsage reports token usage.

type ImageBaseline ¶ added in v0.61.0

type ImageBaseline struct {
	Text string
}

ImageBaseline is the immutable provider projection for one session image. The zero value is the stable unavailable marker; ready values use the sole V1 text contract validated by Validate.

func ParseImageBaseline(projection string) (ImageBaseline, error)

func (b ImageBaseline) Projection() string

func (b ImageBaseline) Validate() error

type ImageCapability ¶ added in v0.61.0

type ImageCapability int

ImageCapability describes what the configuration says about a model's ability to accept image input. It is deliberately three-valued: "we know it cannot" and "we were never told" are different facts, and callers decide how to treat the latter.

const (
	// ImageUnknown means no input modalities were declared, so the capability
	// was never stated. It is the zero value: an undeclared model is unknown,
	// never implicitly unsupported — callers that must choose treat it as
	// "cannot see", but the distinction stays visible here.
	ImageUnknown ImageCapability = iota
	// ImageSupported means the declared input modalities include images.
	ImageSupported
	// ImageUnsupported means input modalities were declared and images are not
	// among them.
	ImageUnsupported
)

type ImageContent ¶

type ImageContent struct {
	Data     string // base64 encoded
	MimeType string // e.g. "image/jpeg", "image/png"
}

ImageContent represents ephemeral, base64-encoded provider or tool input. It must not be written to new ordinary-session history.

func (ic ImageContent) DataURI() string

type ImageRefContent ¶ added in v0.61.0

type ImageRefContent struct {
	MediaID  string
	Baseline ImageBaseline
}

ImageRefContent is a canonical reference to immutable session media. MIME is owned by the media row and resolved only during authorized hydration.

func (r ImageRefContent) Validate() error

type Message ¶

type Message interface {
	// contains filtered or unexported methods
}

Message is the base conversation entry.

func TransformMessages(messages []Message) []Message

type Model ¶

type Model struct {
	ID            string
	Name          string
	API           string
	Provider      string
	BaseURL       string
	Reasoning     bool
	Input         []string // e.g. ["text", "image"]
	Cost          ModelCost
	ContextWindow int
	MaxTokens     int
	Headers       map[string]string
}

Model identifies a concrete model and its capabilities.

func (m Model) ImageCapability() ImageCapability

type ModelCost ¶

type ModelCost struct {
	ModelRates
	Tiers  []ModelCostTier
	Priced bool
}

ModelCost is a base rate plus whole-request context tiers. Priced separates known-free models from models whose price is unknown.

func (c ModelCost) Configured() bool

func (c ModelCost) RatesFor(promptTokens int) ModelRates

type ModelCostTier ¶ added in v0.66.0

type ModelCostTier struct {
	MinContext int
	ModelRates
}

ModelCostTier applies when the request context reaches MinContext.

type ModelRates ¶ added in v0.66.0

type ModelRates struct {
	Input       float64
	Output      float64
	CacheRead   float64
	CacheWrite  float64
	Reasoning   float64
	InputAudio  float64
	OutputAudio float64
}

ModelRates is a set of per-million-token rates. Zero is a real free rate, never an inheritance sentinel at runtime.

type ModelRequest ¶ added in v0.65.0

type ModelRequest struct {
	Model string
	// contains filtered or unexported fields
}

ModelRequest is the per-model-request scope carried in the context from the agent loop down to the HTTP transport. Provider SDKs retry internally, so the loop never sees how many network requests one logical call took; the transport is the only place that can count them, and this is how the count travels back up.

It holds no telemetry types on purpose: the counter is domain state, the spans that consume it live in the transport (see pkg/httpclient).

func ModelRequestFrom(ctx context.Context) *ModelRequest

func WithModelRequest(ctx context.Context, model string) (context.Context, *ModelRequest)

func (r *ModelRequest) Attempts() int

func (r *ModelRequest) NextAttempt() int

type Provider ¶

type Provider = string

Provider identifies the upstream service.

type StopReason ¶

type StopReason string

StopReason normalizes provider-specific stop signals.

const (
	// StopReasonUnknown is an unrecognized or omitted provider finish reason.
	// Consumers that require a complete response must fail closed on it.
	StopReasonUnknown StopReason = ""
	StopReasonStop    StopReason = "stop"
	StopReasonLength  StopReason = "length"
	StopReasonToolUse StopReason = "toolUse"
	StopReasonError   StopReason = "error"
	StopReasonAborted StopReason = "aborted"
)

type StreamOptions ¶

type StreamOptions struct {
	Temperature     *float64
	MaxTokens       *int
	Reasoning       ThinkingLevel
	ThinkingBudgets *ThinkingBudgets
	Transport       Transport
	CacheRetention  CacheRetention
	SessionID       string
	Headers         map[string]string
	Metadata        map[string]any
	MaxRetryDelayMS *int
	Timeout         time.Duration
}

StreamOptions configures provider-level streaming behavior.

type TextContent ¶

type TextContent struct {
	Text          string
	TextSignature string // legacy id string or TextSignatureV1 JSON
}

TextContent represents plain text output.

type TextSignatureV1 ¶

type TextSignatureV1 struct {
	V     int    `json:"v"`
	ID    string `json:"id"`
	Phase string `json:"phase,omitempty"` // "commentary" | "final_answer"
}

TextSignatureV1 carries model-generated text signature metadata.

type ThinkingBudgets ¶

type ThinkingBudgets struct {
	Minimal *int
	Low     *int
	Medium  *int
	High    *int
}

ThinkingBudgets maps thinking levels to token budgets (token-based providers only).

type ThinkingContent ¶

type ThinkingContent struct {
	Thinking  string
	Signature string
	Redacted  bool
}

ThinkingContent stores provider reasoning metadata.

type ThinkingLevel ¶

type ThinkingLevel = string

ThinkingLevel controls provider reasoning depth.

const (
	ThinkingMinimal ThinkingLevel = "minimal"
	ThinkingLow     ThinkingLevel = "low"
	ThinkingMedium  ThinkingLevel = "medium"
	ThinkingHigh    ThinkingLevel = "high"
	ThinkingXHigh   ThinkingLevel = "xhigh"
)

type ToolCall ¶

type ToolCall struct {
	ID               string
	Name             string
	Arguments        map[string]any
	ThoughtSignature string
}

ToolCall represents a tool invocation emitted by an assistant.

type ToolDefinition ¶

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

ToolDefinition describes a callable tool exposed to a model.

type ToolErrorKind ¶ added in v0.65.0

type ToolErrorKind string

ToolErrorKind says *why* a tool result is an error. "the tool failed" and "the command ran and told us it failed" are different facts, and a consumer that flattens them (an eval metric, a failure taxonomy) reports healthy exploration as breakage. Empty on a successful result.

const (
	// ToolErrorKindTool is the default failure: the tool itself did not
	// produce a usable result.
	ToolErrorKindTool ToolErrorKind = "tool_error"
	// ToolErrorKindCommandNonzero is a command that ran to completion inside
	// the sandbox and exited nonzero. The tool worked; the command said no.
	ToolErrorKindCommandNonzero ToolErrorKind = "command_nonzero"
	// ToolErrorKindCommandTimeout is a command stopped by its own deadline:
	// the explicit timeout argument, or the sandbox timeout standing in for it
	// when the caller passed none. A signal kill or an outer cancellation is
	// not this: those remain tool errors.
	ToolErrorKindCommandTimeout ToolErrorKind = "command_timeout"
)

type ToolResultMessage ¶

type ToolResultMessage struct {
	ToolCallID string
	ToolName   string
	Content    []ContentBlock // TextContent | ImageContent | ImageRefContent
	Details    any
	IsError    bool
	// ErrorKind classifies IsError. It is empty on older records and on
	// results written by code that predates the split; a reader must treat
	// empty as "unclassified", never as ToolErrorKindCommandNonzero.
	ErrorKind  ToolErrorKind
	Timestamp  time.Time
	References []renderrefs.Reference
	// ChildToolCalls is Code Mode-only host audit metadata. It is deliberately
	// not represented as Content, so providers cannot see or act on it.
	ChildToolCalls []ChildToolCallAudit
}

ToolResultMessage links a tool response to a tool call.

type Transport ¶

type Transport = string

Transport selects the streaming transport.

const (
	TransportSSE       Transport = "sse"
	TransportWebSocket Transport = "websocket"
	TransportAuto      Transport = "auto"
)

type Usage ¶

type Usage struct {
	// Reported distinguishes a provider that sent an all-zero usage payload from
	// one that sent no usage payload at all. Do not infer this from token values.
	Reported        bool
	InputTokens     int
	OutputTokens    int
	ReasoningTokens int
	CacheRead       int
	CacheWrite      int
	TotalTokens     int
	Cost            UsageCost
	// CostConfigured records whether Cost was calculated from declared model
	// rates. A zero Cost without this bit means price is unknown, not free.
	CostConfigured bool
}

Usage tracks token accounting returned by providers. The token categories are disjoint: InputTokens counts only input that was not served from cache, so the four categories can be priced independently. Providers that fold cached tokens into their input count are normalized at their own boundary with UsageWithCachedInput. TotalTokens is the complete normalized total; consumers must not derive it by blindly summing the other fields.

func UsageWithCachedInput(input, output, cacheRead, total int) Usage

func (u Usage) PromptTokens() int

func (u Usage) WithCost(rates ModelCost) Usage

type UsageCost ¶

type UsageCost struct {
	Input      float64
	Output     float64
	Reasoning  float64
	CacheRead  float64
	CacheWrite float64
	Total      float64
}

UsageCost tracks monetary cost per token category.

type UserMessage ¶

type UserMessage struct {
	Content   any
	Timestamp time.Time
}

UserMessage contains user-provided content. Content is string or []ContentBlock (TextContent | ImageContent | ImageRefContent).

func (m UserMessage) TimestampedContent() any