llm

package
v0.0.310 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 26, 2026 License: MIT Imports: 58 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	AnthropicCredAuto   = "auto"    // Default cascade: api_key → env
	AnthropicCredAPIKey = "api_key" // Force: explicit api_key from config only
	AnthropicCredEnv    = "env"     // Force: ANTHROPIC_API_KEY env var only
)

Anthropic credential mode constants for the config "credentials" field. These control which authentication method is used. "auto" (or empty) uses the default cascade; any other value forces that specific method.

View Source 
const (
	PhaseCompacting                 = "Compacting"
	PhaseCompactingWriteBrief       = "Compacting: write brief"
	PhaseCompactingSummarizeHistory = "Compacting: summarize history"
	PhaseCompactingResumeTask       = "Compacting: resume task"
)
View Source 
const (
	// ServiceTierFast is Codex/ChatGPT's API value for user-facing "fast" mode.
	ServiceTierFast = "priority"
	// ServiceTierFastAlias is the legacy/user-facing alias accepted in config and requests.
	ServiceTierFastAlias = "fast"
)
View Source 
const (
	SuggestCommandsToolName = "suggest_commands"
	EditToolName            = "edit"
	UnifiedDiffToolName     = "unified_diff"
	WebSearchToolName       = "web_search"
)
View Source 
const (
	DiffOperationCreate = "create"
)

Diff operation identifiers for structured diff rendering.

View Source 
const EditToolDescription = "" /* 215-byte string literal not displayed */

EditToolDescription is the description for the edit tool.

View Source 
const EmbeddedFileIntro = "The following user-provided file attachments are embedded below:"

EmbeddedFileIntro introduces one or more file bodies embedded directly in a prompt. It is exported so UI/export code can strip embedded bodies from display while preserving them in session history.

View Source 
const ModelSwapEventType = "model_swap"
View Source 
const (
	ReadURLToolName = "read_url"
)
View Source 
const UnifiedDiffToolDescription = `` /* 929-byte string literal not displayed */

UnifiedDiffToolDescription is the description for the unified diff tool.

View Source 
const WarningPhasePrefix = "WARNING: "

WarningPhasePrefix is the prefix for warning-level phase events. Phase events starting with this prefix are rendered as visible warnings in both the TUI and plain text output.

Variables

View Source 
var ErrListModelsUnsupported = errors.New("provider does not support model listing")

ErrListModelsUnsupported is returned by RetryProvider.ListModels when the inner provider does not implement model listing. Callers that prefer a curated fallback (the web /v1/models handler) can detect this and fall through, while callers that want to surface the limitation (cmd/models.go) can report it.

View Source 
var ImageProviderModels = map[string][]string{
	"debug":      {"random"},
	"gemini":     {"gemini-2.5-flash-image", "gemini-3-pro-image-preview", "gemini-3.1-flash-image-preview"},
	"openai":     {"gpt-image-2", "gpt-image-1.5", "gpt-image-1-mini"},
	"chatgpt":    {"gpt-5.4-mini", "gpt-5.4"},
	"xai":        {"grok-2-image", "grok-2-image-1212"},
	"venice":     {"nano-banana-pro", "nano-banana-2", "flux-2-pro", "flux-2-max", "gpt-image-1-5", "imagineart-1.5-pro", "recraft-v4", "recraft-v4-pro", "seedream-v4", "seedream-v5-lite", "qwen-image", "qwen-image-2", "qwen-image-2-pro", "grok-imagine-image", "grok-imagine-image-pro", "hunyuan-image-v3", "venice-sd35", "hidream", "chroma", "z-image-turbo", "wan-2-7-text-to-image", "wan-2-7-pro-text-to-image", "lustify-sdxl", "lustify-v7", "lustify-v8", "wai-Illustrious", "bria-bg-remover", "qwen-edit", "nano-banana-pro-edit", "nano-banana-2-edit", "flux-2-max-edit", "gpt-image-1-5-edit", "seedream-v4-edit", "seedream-v5-lite-edit", "qwen-image-2-edit", "qwen-image-2-pro-edit", "grok-imagine-edit", "firered-image-edit"},
	"flux":       {"flux-2-pro", "flux-kontext-pro", "flux-2-max"},
	"openrouter": {"google/gemini-2.5-flash-image", "google/gemini-3-pro-image-preview", "openai/gpt-5-image", "openai/gpt-5-image-mini", "bytedance-seed/seedream-4.5", "black-forest-labs/flux.2-pro"},
}
View Source 
var ProviderFastModels = map[string]string{
	"anthropic":  "claude-haiku-4-5",
	"openai":     "gpt-5.4-nano",
	"chatgpt":    "gpt-5.4-mini",
	"copilot":    "gpt-4.1",
	"gemini":     "gemini-2.5-flash-lite",
	"gemini-cli": "gemini-2.5-flash-lite",
	"xai":        "grok-3-mini-fast",
	"zen":        "minimax-m2.5-free",
	"vllm":       "Qwen/Qwen3.5-122B-A10B",
	"bedrock":    "claude-haiku-4-5",
	"venice":     "llama-3.2-3b",
	"nearai":     "Qwen/Qwen3.6-35B-A3B-FP8",
	"sambanova":  "Meta-Llama-3.3-70B-Instruct",
	"openrouter": "anthropic/claude-haiku-4-5",
	"claude-bin": "haiku",
	"ollama":     ollamaChatDefaultModel,
}

ProviderFastModels contains the default lightweight model for each provider type. These are used for short control-plane tasks (interrupt classification, summarization).

View Source 
var ProviderModels = map[string][]ModelEntry{
	"anthropic": {

		{ID: "claude-fable-5", InputLimit: 980_000, OutputLimit: 128_000},
		{ID: "claude-opus-4-8", InputLimit: 980_000, OutputLimit: 128_000},
		{ID: "claude-opus-4-7", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-opus-4-7-1m", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4-6", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4-6-1m", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-opus-4-6", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-opus-4-6-1m", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4-5", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4-5-1m", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-opus-4-5", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-haiku-4-5", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4-1m", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-opus-4", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-haiku-4", InputLimit: 180_000, OutputLimit: 64_000},
	},
	"openai": {
		{ID: "gpt-5.5", InputLimit: 922_000, OutputLimit: 128_000},
		{ID: "gpt-5.4", InputLimit: 922_000, OutputLimit: 128_000},
		{ID: "gpt-5.4-mini", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5.4-nano", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5.3-codex", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5.2-codex", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5.2", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5.1", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5-mini", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5-nano", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "o3-mini", InputLimit: 100_000, OutputLimit: 100_000},
	},
	"chatgpt": {

		{ID: "gpt-5.5", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5.4", InputLimit: 922_000, OutputLimit: 128_000},
		{ID: "gpt-5.4-mini", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5.3-codex", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5.3-codex-spark", InputLimit: 100_000, OutputLimit: 16_000},
		{ID: "gpt-5.2-codex", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5.2", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5.1-codex-max", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5.1-codex", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5.1-codex-mini", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5.1", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5-codex", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5-codex-mini", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5", InputLimit: 272_000, OutputLimit: 128_000},
	},
	"openrouter": {
		{ID: "x-ai/grok-code-fast-1"},
	},
	"gemini": {
		{ID: "gemini-3-pro-preview", InputLimit: 936_000, OutputLimit: 65_536},
		{ID: "gemini-3-pro-preview-thinking", InputLimit: 936_000, OutputLimit: 65_536},
		{ID: "gemini-3-flash-preview", InputLimit: 983_000, OutputLimit: 65_536},
		{ID: "gemini-3-flash-preview-thinking", InputLimit: 983_000, OutputLimit: 65_536},
		{ID: "gemini-2.5-flash", InputLimit: 983_000, OutputLimit: 65_536},
		{ID: "gemini-2.5-flash-lite", InputLimit: 983_000, OutputLimit: 65_536},
	},
	"gemini-cli": {
		{ID: "gemini-3-pro-preview", InputLimit: 936_000, OutputLimit: 65_536},
		{ID: "gemini-3-pro-preview-thinking", InputLimit: 936_000, OutputLimit: 65_536},
		{ID: "gemini-3-flash-preview", InputLimit: 983_000, OutputLimit: 65_536},
		{ID: "gemini-3-flash-preview-thinking", InputLimit: 983_000, OutputLimit: 65_536},
		{ID: "gemini-2.5-flash", InputLimit: 983_000, OutputLimit: 65_536},
		{ID: "gemini-2.5-flash-lite", InputLimit: 983_000, OutputLimit: 65_536},
	},
	"zen": {
		{ID: "minimax-m2.5-free", InputLimit: 168_000, OutputLimit: 32_000},
		{ID: "big-pickle", InputLimit: 168_000, OutputLimit: 32_000},
		{ID: "gpt-5-nano", InputLimit: 96_000, OutputLimit: 32_000},
		{ID: "nemotron-3-super-free", InputLimit: 96_000, OutputLimit: 32_000},
		{ID: "trinity-large-preview-free", InputLimit: 96_000, OutputLimit: 32_000},
		{ID: "qwen3.6-plus-free", InputLimit: 900_000, OutputLimit: 100_000},
	},
	"claude-bin": {

		{ID: "opus", ReasoningEfforts: claudeBinOpusEffortVariants},
		{ID: "opus-low"},
		{ID: "opus-medium"},
		{ID: "opus-high"},
		{ID: "opus-xhigh"},
		{ID: "opus-max"},
		{ID: "sonnet", ReasoningEfforts: claudeBinSonnetEffortVariants},
		{ID: "sonnet-low"},
		{ID: "sonnet-medium"},
		{ID: "sonnet-high"},
		{ID: "fable", ReasoningEfforts: claudeBinFableEffortVariants},
		{ID: "fable-low"},
		{ID: "fable-medium"},
		{ID: "fable-high"},
		{ID: "fable-xhigh"},
		{ID: "fable-max"},
		{ID: "haiku"},
	},
	"xai": {

		{ID: "grok-4-1-fast", InputLimit: 1_970_000, OutputLimit: 32_000},
		{ID: "grok-4-1-fast-reasoning", InputLimit: 1_970_000, OutputLimit: 32_000},
		{ID: "grok-4-1-fast-non-reasoning", InputLimit: 1_970_000, OutputLimit: 32_000},

		{ID: "grok-4", InputLimit: 192_000, OutputLimit: 64_000},
		{ID: "grok-4-fast-reasoning", InputLimit: 192_000, OutputLimit: 64_000},
		{ID: "grok-4-fast-non-reasoning", InputLimit: 192_000, OutputLimit: 64_000},

		{ID: "grok-3", InputLimit: 123_000, OutputLimit: 8_192},
		{ID: "grok-3-fast", InputLimit: 123_000, OutputLimit: 8_192},
		{ID: "grok-3-mini", InputLimit: 123_000, OutputLimit: 8_192},
		{ID: "grok-3-mini-fast", InputLimit: 123_000, OutputLimit: 8_192},

		{ID: "grok-code-fast-1", InputLimit: 246_000, OutputLimit: 16_384},

		{ID: "grok-2", InputLimit: 123_000, OutputLimit: 8_192},
	},
	"ollama": {

		{ID: "qwen2.5-coder:7b", InputLimit: 30_000, OutputLimit: 8_192},
		{ID: "qwen2.5-coder:14b", InputLimit: 30_000, OutputLimit: 8_192},
		{ID: "qwen2.5-coder:32b", InputLimit: 30_000, OutputLimit: 8_192},
		{ID: "qwen3:8b", InputLimit: 30_000, OutputLimit: 8_192},
		{ID: "qwen3:8b-think", InputLimit: 30_000, OutputLimit: 8_192},
		{ID: "qwen3:14b", InputLimit: 30_000, OutputLimit: 8_192},
		{ID: "qwen3:14b-think", InputLimit: 30_000, OutputLimit: 8_192},
		{ID: "qwen3:32b", InputLimit: 30_000, OutputLimit: 8_192},
		{ID: "qwen3:32b-think", InputLimit: 30_000, OutputLimit: 8_192},

		{ID: "llama3.3:70b", InputLimit: 120_000, OutputLimit: 8_192},
		{ID: "llama3.2:3b", InputLimit: 120_000, OutputLimit: 8_192},
		{ID: "llama3.2:1b", InputLimit: 120_000, OutputLimit: 8_192},

		{ID: "deepseek-r1:7b", InputLimit: 30_000, OutputLimit: 8_192},
		{ID: "deepseek-r1:14b", InputLimit: 30_000, OutputLimit: 8_192},
		{ID: "deepseek-r1:32b", InputLimit: 30_000, OutputLimit: 8_192},
	},
	"bedrock": {

		{ID: "claude-opus-4-8", InputLimit: 980_000, OutputLimit: 128_000},
		{ID: "claude-opus-4-7", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-opus-4-7-1m", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4-6", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4-6-1m", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-opus-4-6", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-opus-4-6-1m", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4-5", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4-5-1m", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-opus-4-5", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-haiku-4-5", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4-1m", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-opus-4", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-haiku-4", InputLimit: 180_000, OutputLimit: 64_000},
	},
	"venice": {},
	"nearai": {

		{ID: "zai-org/GLM-5.1-FP8", InputLimit: 202_752},
		{ID: "Qwen/Qwen3.6-35B-A3B-FP8", InputLimit: 262_144},
		{ID: "Qwen/Qwen3-VL-30B-A3B-Instruct", InputLimit: 256_000},
		{ID: "Qwen/Qwen3-30B-A3B-Instruct-2507", InputLimit: 262_144},
		{ID: "openai/gpt-oss-120b", InputLimit: 131_000},
		{ID: "google/gemma-4-31B-it", InputLimit: 262_144},
	},
	"sambanova": {

		{ID: "gpt-oss-120b", InputLimit: 131_072, OutputLimit: 8_192},
		{ID: "MiniMax-M2.7", InputLimit: 192_000, OutputLimit: 8_192},
		{ID: "DeepSeek-V3.1", InputLimit: 128_000, OutputLimit: 8_192},
		{ID: "Meta-Llama-3.3-70B-Instruct", InputLimit: 128_000, OutputLimit: 8_192},
		{ID: "DeepSeek-V3.2", InputLimit: 32_000, OutputLimit: 8_192},
		{ID: "gemma-3-12b-it", InputLimit: 128_000, OutputLimit: 8_192},
		{ID: "Llama-4-Maverick-17B-128E-Instruct", InputLimit: 128_000, OutputLimit: 8_192},
	},
}

ProviderModels contains curated fallback model entries for providers without dynamic discovery or for offline/default UIs. Dynamic providers such as Copilot may intentionally omit entries and populate model IDs from their live cache. When adding a curated model, include InputLimit/OutputLimit if known.

Functions

func BaseModelAndEffortForProvider added in v0.0.264 

func BaseModelAndEffortForProvider(provider, model string) (base string, effort string)

BaseModelAndEffortForProvider returns the switchable base model and current reasoning effort for provider/model when the suffix is explicitly supported by that provider's model metadata. Unknown suffix-like endings are preserved as part of the base model name (for example, gpt-5.1-codex-max is not parsed as effort=max for GPT-5 providers because GPT-5 does not support max).

func BuildCompactionStaticInfo added in v0.0.274 

func BuildCompactionStaticInfo(messages []Message, inputLimit int) string

BuildCompactionStaticInfo returns a deterministic, bounded <PREVIOUS_TURNS> block of high-signal context to supplement an LLM-written continuation summary. The block is capped at 30k chars or 5% of the provider input window converted to chars with approxBytesPerToken, whichever is smaller. If inputLimit is unknown, the 30k char cap is used.

func BuildResponsesToolChoice added in v0.0.34 

func BuildResponsesToolChoice(choice ToolChoice) interface{}

BuildResponsesToolChoice converts ToolChoice to Open Responses format

func BuildResponsesTools added in v0.0.34 

func BuildResponsesTools(specs []ToolSpec) []any

BuildResponsesTools converts []ToolSpec to Open Responses format with schema normalization

func CallIDFromContext added in v0.0.42 

func CallIDFromContext(ctx context.Context) string

CallIDFromContext extracts the tool call ID from context, or returns empty string. Used by spawn_agent to get the call ID for event bubbling.

func ClampOutputTokens added in v0.0.115 

func ClampOutputTokens(requested int, model string) int

ClampOutputTokens returns the requested output token count clamped to the model's maximum output limit. If the model is unknown (limit=0) or the requested value is within bounds, it is returned unchanged. This allows callers like Compact() to always set a budget without worrying about per-model limits — providers call this to silently cap the value.

func Classify added in v0.0.101 

func Classify(ctx context.Context, provider Provider, prompt string, timeout time.Duration) (string, error)

Classify sends a short prompt and returns the first lowercase word in the model response.

func CleanupOldLogs added in v0.0.34 

func CleanupOldLogs(baseDir string, maxAge time.Duration) error

CleanupOldLogs removes JSONL log files older than maxAge from the specified directory. This prevents debug logs from accumulating indefinitely.

func CompactionSummaryDisplayText added in v0.0.274 

func CompactionSummaryDisplayText(text string) string

CompactionSummaryDisplayText extracts the human-authored summary/action block from an internal compaction message. If the message uses the older untagged format, deterministic PREVIOUS_TURNS transcript data is stripped so UI placeholders describe the concise summary instead of bulky internal context.

func ContextWithCallID added in v0.0.42 

func ContextWithCallID(ctx context.Context, callID string) context.Context

ContextWithCallID returns a new context with the tool call ID set. Used by the engine to pass the call ID to spawn_agent for event bubbling.

func ContextWithSessionID added in v0.0.286 

func ContextWithSessionID(ctx context.Context, sessionID string) context.Context

ContextWithSessionID returns a new context with the session ID set. Used by the engine so tools (e.g. file-change recording) know which session a tool execution belongs to.

func DebugRawEvent added in v0.0.10 

func DebugRawEvent(enabled bool, event Event)

DebugRawEvent prints each stream event with a timestamp.

func DebugRawRequest added in v0.0.10 

func DebugRawRequest(enabled bool, providerName, credential string, req Request, label string)

DebugRawRequest prints the raw request with all message parts in debug mode.

func DebugRawSection added in v0.0.10 

func DebugRawSection(enabled bool, label, body string)

DebugRawSection prints a timestamped debug section.

func DebugRawToolCall added in v0.0.10 

func DebugRawToolCall(enabled bool, call ToolCall)

DebugRawToolCall prints a tool call with raw JSON arguments and a timestamp.

func DebugRawToolResult added in v0.0.10 

func DebugRawToolResult(enabled bool, id, name, content string)

DebugRawToolResult prints a tool result payload with a timestamp.

func DebugToolCall added in v0.0.10 

func DebugToolCall(enabled bool, call ToolCall)

DebugToolCall prints a tool call in debug mode with readable formatting.

func DebugToolResult added in v0.0.10 

func DebugToolResult(enabled bool, id, name, content string)

DebugToolResult prints a tool result in debug mode with readable formatting.

func DedupeEffortVariants added in v0.0.168 

func DedupeEffortVariants(ids []string) []string

DedupeEffortVariants removes effort-suffixed aliases (e.g. "opus-high", "gpt-5.4-medium") when the base model is also present in the list. Used by UIs that expose reasoning effort through a dedicated selector, where "<base>-<effort>" entries just duplicate what the selector covers. Order is preserved; entries without a matching base are kept as-is.

func DedupeEffortVariantsForProvider added in v0.0.264 

func DedupeEffortVariantsForProvider(provider string, ids []string) []string

DedupeEffortVariantsForProvider removes effort-suffixed aliases only when the suffix is an explicitly supported reasoning effort for the provider/model and the corresponding base model is present. Natural model names such as gpt-5.1-codex-max are preserved when "max" is not a supported effort for that base model.

func DefaultReasoningEffortsForProviderType added in v0.0.264 

func DefaultReasoningEffortsForProviderType(providerType string) []string

func EditToolSchema added in v0.0.9 

func EditToolSchema() map[string]interface{}

EditToolSchema returns the JSON schema for the edit tool.

func EffortVariantsFor added in v0.0.80 

func EffortVariantsFor(model string) []string

EffortVariantsFor returns the legacy provider-agnostic effort suffixes for a model, or nil if none. Prefer ReasoningEffortsForProviderModel when provider context is available, because effort support is model- and provider-specific.

This compatibility helper intentionally preserves the historical GPT-5 heuristic used by older tests and callers that have only a bare model name.

func EmbeddedFileDisplayName added in v0.0.257 

func EmbeddedFileDisplayName(filename string) string

EmbeddedFileDisplayName returns a single-line, path-free name suitable for prompt markers and provider filenames. Browser uploads normally provide a base name already, but API clients may send absolute paths or control characters.

func EstimateMessageTokens added in v0.0.80 

func EstimateMessageTokens(msgs []Message) int

EstimateMessageTokens returns an approximate token count for a slice of messages by summing all text content across parts.

func EstimateTokens added in v0.0.80 

func EstimateTokens(text string) int

EstimateTokens returns an approximate token count for a string using a simple 4-bytes-per-token heuristic (same as codex).

func ExpandWithEffortVariants added in v0.0.80 

func ExpandWithEffortVariants(models []string) []string

ExpandWithEffortVariants expands a model list by appending legacy provider-agnostic GPT-5 effort variants. Prefer ExpandWithEffortVariantsForProvider when provider context is available.

func ExpandWithEffortVariantsForProvider added in v0.0.264 

func ExpandWithEffortVariantsForProvider(provider string, models []string) []string

ExpandWithEffortVariantsForProvider expands a model list by appending valid effort variants after each switchable base model for the given provider. Existing effort-suffixed entries are kept but not expanded again. Output is de-duplicated while preserving first-seen order.

func ExtractEmbeddedFileNames added in v0.0.257 

func ExtractEmbeddedFileNames(content string) []string

ExtractEmbeddedFileNames returns display names from embedded file markers.

func ExtractToolInfo added in v0.0.49 

func ExtractToolInfo(call ToolCall) string

ExtractToolInfo extracts a preview string from tool call arguments. Used for displaying tool calls in the UI (e.g., "(path:main.go)" for read_file).

func FilterOpenRouterModels added in v0.0.24 

func FilterOpenRouterModels(models []string, prefix string) []string

func FormatEmbeddedFileText added in v0.0.257 

func FormatEmbeddedFileText(filename, mediaType, text string) string

FormatEmbeddedFileText wraps user-provided file contents in explicit markers so models can tell where an embedded attachment starts and ends. The contents are fenced as markdown, using a fence longer than any backtick run in the file.

func FormatModelSwapMarker added in v0.0.205 

func FormatModelSwapMarker(marker ModelSwapMarker) string

func FormatTokenCount added in v0.0.80 

func FormatTokenCount(tokens int) string

FormatTokenCount returns a human-readable string for a token count (e.g., "128K", "1M", "200K"). Returns "" for zero or negative values.

func GetBuiltInProviderNames added in v0.0.15 

func GetBuiltInProviderNames() []string

GetBuiltInProviderNames returns the built-in provider type names

func GetCachedCopilotModels added in v0.0.275 

func GetCachedCopilotModels() []string

GetCachedCopilotModels returns the last live model list fetched from Copilot. It never performs network or auth work, so it is safe for shell completion and provider pickers. Run `term-llm models --provider copilot` to refresh it.

func GetCachedOpenRouterModels added in v0.0.24 

func GetCachedOpenRouterModels(apiKey string) []string

func GetCachedVeniceModels added in v0.0.268 

func GetCachedVeniceModels(apiKey string) []string

func GetDebugPresets added in v0.0.46 

func GetDebugPresets() map[string]debugPreset

GetDebugPresets returns a copy of available presets for testing.

func GetImageProviderNames added in v0.0.6 

func GetImageProviderNames() []string

GetImageProviderNames returns valid provider names for image generation

func GetProviderCompletions added in v0.0.6 

func GetProviderCompletions(toComplete string, isImage bool, cfg *config.Config) []string

GetProviderCompletions returns completions for the --provider flag It handles both provider-only and provider:model completion scenarios. For LLM providers, pass a config to include custom provider names.

func GetProviderNames added in v0.0.6 

func GetProviderNames(cfg *config.Config) []string

GetProviderNames returns valid provider names from config plus built-in types. If cfg is nil, returns only built-in provider names.

func InputLimitForModel added in v0.0.80 

func InputLimitForModel(model string) int

InputLimitForModel returns the effective input token limit for a known model using canonical (direct API) numbers. This is the maximum number of tokens that can be sent as input — not the total context window (input + output). Returns 0 for unknown models. For provider-specific limits, use InputLimitForProviderModel instead.

func InputLimitForProviderModel added in v0.0.80 

func InputLimitForProviderModel(providerName, model string) int

InputLimitForProviderModel returns the effective input token limit for a model accessed through a specific provider. Some providers expose/reroute models with limits that differ from the model's canonical direct-API limit. The providerName can be either a provider type (e.g., "copilot") or a custom provider name — it is resolved to the underlying type automatically. Most providers fall back to canonical numbers when provider-specific data is unavailable; dynamic providers such as Copilot and Venice avoid that fallback because canonical model-prefix tables can be wrong for their routed models.

func IsEncryptedReasoningDelta added in v0.0.258 

func IsEncryptedReasoningDelta(event Event) bool

IsEncryptedReasoningDelta reports whether a reasoning delta only carries encrypted replay metadata and should be withheld from interactive UI streams.

func IsInternalCompactionSummaryText added in v0.0.274 

func IsInternalCompactionSummaryText(text string) bool

IsInternalCompactionSummaryText reports whether text is an internal context compaction summary message. UI layers use this to hide the bulky internal prompt in normal chat while still exposing it in inspectors/debug views.

func IsMaxTurnsExceeded added in v0.0.259 

func IsMaxTurnsExceeded(err error) bool

IsMaxTurnsExceeded reports whether err indicates agentic-loop turn exhaustion. It preserves compatibility with older string-only errors while preferring the typed error for new call sites.

func MaxTurnsExceededWarning added in v0.0.259 

func MaxTurnsExceededWarning(maxTurns int) string

MaxTurnsExceededWarning returns the user-facing warning emitted before the stream terminates with MaxTurnsExceededError.

func MessageAttachmentSummary added in v0.0.254 

func MessageAttachmentSummary(msg Message) string

MessageAttachmentSummary returns a compact summary of non-text content.

func MessageText added in v0.0.254 

func MessageText(msg Message) string

MessageText returns the concatenated text parts of a message.

func ModelSupportsFast added in v0.0.231 

func ModelSupportsFast(model ModelInfo) bool

ModelSupportsFast reports whether model metadata advertises fast mode.

func ModelSupportsServiceTier added in v0.0.231 

func ModelSupportsServiceTier(model ModelInfo, tier string) bool

ModelSupportsServiceTier reports whether model metadata advertises tier.

func NormalizeMediaType added in v0.0.257 

func NormalizeMediaType(mediaType string) string

NormalizeMediaType lowercases a MIME type and strips optional parameters.

func NormalizeServiceTier added in v0.0.231 

func NormalizeServiceTier(value string) string

NormalizeServiceTier maps user-facing aliases to API values. Unknown values are returned trimmed so future service tiers can pass through when supported.

func OutputLimitForModel added in v0.0.115 

func OutputLimitForModel(model string) int

OutputLimitForModel returns the maximum output tokens for a known model. Returns 0 for unknown models.

func ParseModelEffort added in v0.0.176 

func ParseModelEffort(model string) (string, string)

ParseModelEffort extracts effort suffix from model name. "gpt-5.2-high" -> ("gpt-5.2", "high") "gpt-5.2-xhigh" -> ("gpt-5.2", "xhigh") "gpt-5.2" -> ("gpt-5.2", "")

func ParseProviderModel added in v0.0.6 

func ParseProviderModel(s string, cfg *config.Config) (string, string, error)

ParseProviderModel parses "provider:model" or just "provider" from a flag value. Returns (provider, model, error). Model will be empty if not specified. For the new config format, we validate against configured providers or built-in types.

func ParseUnifiedDiff added in v0.0.9 

func ParseUnifiedDiff(call ToolCall) (string, error)

ParseUnifiedDiff parses a unified_diff tool call payload.

func PricingForProviderModel added in v0.0.239 

func PricingForProviderModel(provider, model string) (inputPrice, outputPrice float64, ok bool)

PricingForProviderModel returns known provider-specific pricing in USD per million input/output tokens.

func PromptForChatGPTAuth added in v0.0.260 

func PromptForChatGPTAuth() (*credentials.ChatGPTCredentials, error)

PromptForChatGPTAuth prompts the user to authenticate with ChatGPT. Prefers the device-code flow so auth works on headless/remote/containerized boxes; falls back to the localhost browser flow if the backend doesn't advertise device-code support. Exported so `term-llm auth login chatgpt` can drive the same flow used by lazy auth.

func PromptForCopilotAuth added in v0.0.260 

func PromptForCopilotAuth() (*credentials.CopilotCredentials, error)

PromptForCopilotAuth prompts the user to authenticate with GitHub Copilot. Returns an error if running in a non-interactive context (e.g., scripts, CI). Exported so `term-llm auth login copilot` can drive the same flow used by lazy auth.

func ProviderModelIDs added in v0.0.140 

func ProviderModelIDs(provider string) []string

ProviderModelIDs returns model IDs for a built-in provider. Copilot is populated from the latest live model-list cache instead of a hardcoded list. For callers that might receive a custom alias name, use ResolveProviderModelIDs.

func ReasoningEffortsForProviderModel added in v0.0.264 

func ReasoningEffortsForProviderModel(provider, model string) []string

ReasoningEffortsForProviderModel returns the valid suffix-based reasoning efforts for the provider/model pair. If model is already suffixed with a supported effort, the efforts for its base model are returned.

func RefreshCopilotCacheSync added in v0.0.275 

func RefreshCopilotCacheSync(models []ModelInfo)

RefreshCopilotCacheSync stores a freshly fetched Copilot model list for completions and offline provider/model pickers.

func RefreshOpenRouterCacheSync added in v0.0.24 

func RefreshOpenRouterCacheSync(apiKey string, models []ModelInfo)

func RefreshVeniceCacheSync added in v0.0.267 

func RefreshVeniceCacheSync(models []ModelInfo)

func RegisterConfigLimits added in v0.0.124 

func RegisterConfigLimits(limits []ConfigModelLimit)

RegisterConfigLimits registers model token limits from user configuration. These are used as a fallback when hardcoded tables return 0. Limits are stored provider-scoped; model-only fallback is populated only when all providers defining a model agree on the same limits.

func RegisterConfigReasoningEfforts added in v0.0.264 

func RegisterConfigReasoningEfforts(entries []ConfigModelReasoningEfforts)

RegisterConfigReasoningEfforts registers per-provider/model reasoning-effort capabilities from user configuration. Always call it on config load (even with nil) so reloads clear stale capabilities.

func RegisterProviderAliases added in v0.0.140 

func RegisterProviderAliases(aliases map[string]string)

RegisterProviderAliases registers custom provider name → built-in type mappings from user config. This allows provider-scoped limits to resolve correctly for aliases like "acme" → "venice".

func ResolveProviderModelIDs added in v0.0.140 

func ResolveProviderModelIDs(name string) []string

ResolveProviderModelIDs returns curated model IDs for a provider, resolving custom aliases (e.g., "acme" → "venice") via registered provider aliases and built-in type inference.

func SessionIDFromContext added in v0.0.286 

func SessionIDFromContext(ctx context.Context) string

SessionIDFromContext extracts the session ID from context, or returns empty string.

func SortModelIDsByPopularity added in v0.0.169 

func SortModelIDsByPopularity(provider, defaultModel string, ids []string) []string

SortModelIDsByPopularity orders ids so the picker shows the models a user is most likely to pick first, then everything else alpha-sorted for easy scanning. The ranking signal comes from ResolveProviderModelIDs: curated entries for static providers and cached live entries for dynamic providers such as Copilot. defaultModel is pinned to the very top — always included even if absent from ids, so the user's configured model stays reachable when an upstream provider drops it from /v1/models. IDs not in the curated list fall through to alpha-sort.

Centralizing this here means the web picker, TUI picker, and CLI completion all agree on what "popular first" means.

func StripEmbeddedFileText added in v0.0.257 

func StripEmbeddedFileText(content string) string

StripEmbeddedFileText removes embedded file bodies from a display/export copy of a user message. It intentionally does not mutate stored message parts.

func TranscribeFile added in v0.0.97 

func TranscribeFile(ctx context.Context, filePath string, opts TranscribeOptions) (string, error)

TranscribeFile sends an audio file to a Whisper-compatible API and returns the transcript. Supported formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm.

func TranscribeWithConfig added in v0.0.97 

func TranscribeWithConfig(ctx context.Context, cfg *config.Config, filePath, language, providerOverride string) (string, error)

TranscribeWithConfig transcribes an audio file using the provider configured in cfg. providerOverride, if non-empty, overrides cfg.Transcription.Provider.

Supported provider names: "openai" (default), "mistral" (Voxtral), "venice", "elevenlabs", "local" (whisper.cpp server), "whisper-cli" (whisper.cpp CLI binary). The whisper-cli case is delegated back to cmd via the transcribeWhisperCLI function — callers that don't support it (e.g. Telegram) will get an unsupported-provider error, which is intentional.

func TruncateToolResult added in v0.0.80 

func TruncateToolResult(content string, maxChars int) string

TruncateToolResult preserves the first half and last half of long tool results, inserting a truncation marker in the middle. Uses rune count to avoid splitting multi-byte UTF-8 characters.

func TruncateTranscriptForDuration added in v0.0.131 

func TruncateTranscriptForDuration(duration time.Duration, transcript string) string

TruncateTranscriptForDuration truncates a transcript to a plausible word count based on audio duration (350 words per minute). Returns the original if within bounds.

func TruncateTranscriptIfImplausible added in v0.0.131 

func TruncateTranscriptIfImplausible(ctx context.Context, filePath, transcript string) string

TruncateTranscriptIfImplausible truncates a transcript that is impossibly long for the audio duration (e.g. hallucinated repetitions). Returns the original transcript unchanged if ffprobe is unavailable or the length is plausible.

func UnifiedDiffToolSchema added in v0.0.9 

func UnifiedDiffToolSchema() map[string]interface{}

UnifiedDiffToolSchema returns the JSON schema for the unified diff tool.

func ValidateClaudeBinModel added in v0.0.165 

func ValidateClaudeBinModel(model string) error

ValidateClaudeBinModel rejects model strings that are bare effort levels (e.g. "claude-bin:max"). Without this check the effort would be silently treated as the model name and CLAUDE_CODE_EFFORT_LEVEL would never be set.

Types

type AnthropicProvider 

type AnthropicProvider struct {
	// contains filtered or unexported fields
}

AnthropicProvider implements Provider using the Anthropic API.

func NewAnthropicProvider 

func NewAnthropicProvider(apiKey, model, credentialMode string) (*AnthropicProvider, error)

NewAnthropicProvider creates a new Anthropic provider. The credentialMode parameter controls which authentication method is used:

  • "" or "auto": try the cascade (api_key → env)
  • "api_key": use only the explicit apiKey parameter
  • "env": use only the ANTHROPIC_API_KEY environment variable

func (*AnthropicProvider) Capabilities added in v0.0.10 

func (p *AnthropicProvider) Capabilities() Capabilities

func (*AnthropicProvider) Credential added in v0.0.10 

func (p *AnthropicProvider) Credential() string

func (*AnthropicProvider) ListModels added in v0.0.8 

func (p *AnthropicProvider) ListModels(ctx context.Context) ([]ModelInfo, error)

ListModels returns available models from Anthropic.

func (*AnthropicProvider) Name 

func (p *AnthropicProvider) Name() string

func (*AnthropicProvider) Stream added in v0.0.10 

func (p *AnthropicProvider) Stream(ctx context.Context, req Request) (Stream, error)

type AssistantSnapshotCallback added in v0.0.174 

type AssistantSnapshotCallback func(ctx context.Context, turnIndex int, assistantMsg Message) error

AssistantSnapshotCallback is called during streaming whenever accumulated assistant state materially changes (typically right before each EventToolCall emission, sync or async). Multiple fires per turn are expected; implementations MUST upsert the same logical row, not append. assistantMsg contains the in-progress message built from accumulated text/reasoning/toolCalls at the moment of firing. Used to persist "as we go" so content survives process death mid-turn (e.g., consumer cancels context between EventToolCall emission and tool execution).

type BedrockProvider added in v0.0.135 

type BedrockProvider struct {
	// contains filtered or unexported fields
}

BedrockProvider implements Provider using AWS Bedrock with Anthropic Claude models. It delegates all streaming/message logic to an embedded AnthropicProvider, only differing in client creation (AWS credentials instead of API key).

func NewBedrockProvider added in v0.0.135 

func NewBedrockProvider(model, region, profile, accessKey, secretKey, sessionToken string, modelMap map[string]string) (*BedrockProvider, error)

NewBedrockProvider creates a new AWS Bedrock provider for Anthropic Claude models.

func (*BedrockProvider) Capabilities added in v0.0.135 

func (p *BedrockProvider) Capabilities() Capabilities

func (*BedrockProvider) Credential added in v0.0.135 

func (p *BedrockProvider) Credential() string

func (*BedrockProvider) Name added in v0.0.135 

func (p *BedrockProvider) Name() string

func (*BedrockProvider) Stream added in v0.0.135 

func (p *BedrockProvider) Stream(ctx context.Context, req Request) (Stream, error)

type Capabilities added in v0.0.10 

type Capabilities struct {
	NativeWebSearch    bool // Provider has native web search capability
	NativeWebFetch     bool // Provider has native URL fetch capability
	ToolCalls          bool
	SupportsToolChoice bool // Provider supports tool_choice to force specific tool use
	ManagesOwnContext  bool // Provider manages its own context window (skip compaction)
}

Capabilities describe optional provider features.

type ChatGPTProvider added in v0.0.32 

type ChatGPTProvider struct {
	// contains filtered or unexported fields
}

ChatGPTProvider implements Provider using the ChatGPT backend API with native OAuth.

func NewChatGPTProvider added in v0.0.32 

func NewChatGPTProvider(model string) (*ChatGPTProvider, error)

NewChatGPTProvider creates a new ChatGPT provider. If credentials are not available or expired, it will prompt the user to authenticate.

func NewChatGPTProviderWithCreds added in v0.0.32 

func NewChatGPTProviderWithCreds(creds *credentials.ChatGPTCredentials, model string) *ChatGPTProvider

NewChatGPTProviderWithCreds creates a ChatGPT provider with pre-loaded credentials. This is used by the factory when credentials are already resolved.

func NewChatGPTProviderWithCredsAndOptions added in v0.0.204 

func NewChatGPTProviderWithCredsAndOptions(creds *credentials.ChatGPTCredentials, model string, opts ChatGPTProviderOptions) *ChatGPTProvider

func NewChatGPTProviderWithOptions added in v0.0.204 

func NewChatGPTProviderWithOptions(model string, opts ChatGPTProviderOptions) (*ChatGPTProvider, error)

NewChatGPTProviderWithOptions creates a new ChatGPT provider with optional transport settings. If credentials are not available or expired, it will prompt the user to authenticate.

func (*ChatGPTProvider) Capabilities added in v0.0.32 

func (p *ChatGPTProvider) Capabilities() Capabilities

func (*ChatGPTProvider) Credential added in v0.0.32 

func (p *ChatGPTProvider) Credential() string

func (*ChatGPTProvider) ListModels added in v0.0.231 

func (p *ChatGPTProvider) ListModels(ctx context.Context) ([]ModelInfo, error)

ListModels returns ChatGPT Codex backend model metadata, including service tiers.

func (*ChatGPTProvider) ListModelsWithFreshness added in v0.0.231 

func (p *ChatGPTProvider) ListModelsWithFreshness(ctx context.Context) ([]ModelInfo, bool, error)

ListModelsWithFreshness returns model metadata and whether it came from a fresh cache or successful network fetch. If a network fetch fails and stale cache is available, it returns the stale models with fresh=false and nil error.

func (*ChatGPTProvider) Name added in v0.0.32 

func (p *ChatGPTProvider) Name() string

func (*ChatGPTProvider) ResetConversation added in v0.0.111 

func (p *ChatGPTProvider) ResetConversation()

ResetConversation clears server state for the Responses API client.

func (*ChatGPTProvider) Stream added in v0.0.32 

func (p *ChatGPTProvider) Stream(ctx context.Context, req Request) (Stream, error)

type ChatGPTProviderOptions added in v0.0.204 

type ChatGPTProviderOptions struct {
	UseWebSocket     bool
	ServiceTier      string
	FileUploadPolicy *FileUploadPolicy
}

type ClaudeBinProvider added in v0.0.21 

type ClaudeBinProvider struct {
	// contains filtered or unexported fields
}

ClaudeBinProvider implements Provider using the claude CLI binary. This provider shells out to the claude command for inference, using Claude Code's existing authentication.

Note: This provider is NOT safe for concurrent use. Each Stream() call modifies shared state (sessionID, messagesSent). Create separate instances for concurrent streams.

func NewClaudeBinProvider added in v0.0.21 

func NewClaudeBinProvider(model string, env map[string]string) *ClaudeBinProvider

NewClaudeBinProvider creates a new provider that uses the claude binary.

func (*ClaudeBinProvider) Capabilities added in v0.0.21 

func (p *ClaudeBinProvider) Capabilities() Capabilities

func (*ClaudeBinProvider) CleanupMCP added in v0.0.52 

func (p *ClaudeBinProvider) CleanupMCP()

CleanupMCP stops the MCP server and removes the config file. This should be called when the conversation is complete (runtime eviction or server shutdown) — NOT per turn, because the MCP server is deliberately kept alive across turns so Claude CLI can reuse the same URL/token. Also removes any remaining tracked temp files as a safety net in case CleanupTurn was not invoked (e.g. mid-turn abort before stream terminates).

func (*ClaudeBinProvider) CleanupTurn added in v0.0.168 

func (p *ClaudeBinProvider) CleanupTurn()

CleanupTurn removes per-turn resources (currently: tracked temp image files). Safe to call multiple times. Invoked by the engine stream wrapper on stream termination; also runs via defer inside Stream() so it is guaranteed even if the consumer drops the stream.

func (*ClaudeBinProvider) Credential added in v0.0.21 

func (p *ClaudeBinProvider) Credential() string

func (*ClaudeBinProvider) ExportProviderState added in v0.0.289 

func (p *ClaudeBinProvider) ExportProviderState() ([]byte, bool)

ExportProviderState persists Claude Code's session id plus the term-llm transcript boundary already submitted to that session. On runtime rehydrate, ImportProviderState lets claude-bin continue with --resume instead of replaying the whole stored transcript as fresh stdin.

func (*ClaudeBinProvider) ImportProviderState added in v0.0.289 

func (p *ClaudeBinProvider) ImportProviderState(data []byte) error

ImportProviderState restores Claude Code resume state previously returned by ExportProviderState.

func (*ClaudeBinProvider) Name added in v0.0.21 

func (p *ClaudeBinProvider) Name() string

func (*ClaudeBinProvider) ResetConversation added in v0.0.168 

func (p *ClaudeBinProvider) ResetConversation()

ResetConversation clears Claude CLI resume state so the next turn starts a fresh conversation instead of resuming the previous CLI session.

func (*ClaudeBinProvider) SetEnableHooks added in v0.0.120 

func (p *ClaudeBinProvider) SetEnableHooks(enable bool)

SetEnableHooks controls whether Claude Code hooks are allowed to run. Hooks are disabled by default so term-llm sessions don't inherit user-defined Claude Code automation unexpectedly.

func (*ClaudeBinProvider) SetEnv added in v0.0.120 

func (p *ClaudeBinProvider) SetEnv(env map[string]string)

SetEnv configures extra environment variables for the Claude CLI subprocess.

func (*ClaudeBinProvider) SetPreferOAuth added in v0.0.55 

func (p *ClaudeBinProvider) SetPreferOAuth(prefer bool)

SetPreferOAuth controls whether to prefer OAuth auth over API key. When true (default), clears ANTHROPIC_API_KEY for the subprocess so Claude CLI uses OAuth subscription auth instead.

func (*ClaudeBinProvider) SetToolExecutor added in v0.0.49 

func (p *ClaudeBinProvider) SetToolExecutor(executor func(ctx context.Context, name string, args json.RawMessage) (ToolOutput, error))

SetToolExecutor sets the function used to execute tools. This must be called before Stream() if tools are needed. Note: The signature uses an anonymous function type (not mcphttp.ToolExecutor) to satisfy the ToolExecutorSetter interface in engine.go.

func (*ClaudeBinProvider) Stream added in v0.0.21 

func (p *ClaudeBinProvider) Stream(ctx context.Context, req Request) (Stream, error)

type ClaudeCommandError added in v0.0.189 

type ClaudeCommandError struct {
	ExitCode       int
	Err            error
	Args           []string
	CommandLine    string
	Cwd            string
	Effort         string
	ToolsExecuted  bool
	PreferOAuth    bool
	Env            map[string]string
	RemovedEnv     []string
	Stdin          string
	StdinLen       int
	StdinSHA256    string
	StdinTruncated bool
	StdoutTail     string
	StderrTail     string
}

ClaudeCommandError carries enough diagnostics for debug logs to reproduce or inspect a failed claude CLI invocation without dumping the whole process environment (which may contain secrets).

func (*ClaudeCommandError) DebugFields added in v0.0.189 

func (e *ClaudeCommandError) DebugFields() map[string]any

DebugFields is consumed by DebugLogger when this error is emitted as an EventError. Keep field values JSON-friendly.

func (*ClaudeCommandError) Error added in v0.0.189 

func (e *ClaudeCommandError) Error() string

func (*ClaudeCommandError) Unwrap added in v0.0.189 

func (e *ClaudeCommandError) Unwrap() error

type CommandSuggestion 

type CommandSuggestion struct {
	Command     string `json:"command"`
	Explanation string `json:"explanation"`
	Likelihood  int    `json:"likelihood"` // 1-10, how likely this matches user intent
}

CommandSuggestion represents a single command suggestion from the LLM.

func ParseCommandSuggestions added in v0.0.10 

func ParseCommandSuggestions(call ToolCall) ([]CommandSuggestion, error)

ParseCommandSuggestions parses a suggest_commands tool call.

type CompactionCallback added in v0.0.80 

type CompactionCallback func(ctx context.Context, result *CompactionResult) error

CompactionCallback is called after context compaction to allow callers to update their state (e.g., replace in-memory messages, persist changes). The callback must synchronously replace/persist the owner's active context before returning; the engine only updates its in-flight request copy, so owner state that is not updated here can resurrect pre-compaction history later.

type CompactionConfig added in v0.0.80 

type CompactionConfig struct {
	ThresholdRatio       float64 // Legacy/default fraction of context window to trigger compaction (default 0.90)
	SoftThresholdRatio   float64 // Fraction where we try to checkpoint and compact cleanly (default 0.90)
	HardThresholdRatio   float64 // Fraction where we must compact before the next tool/LLM continuation (default 0.95)
	MaxToolResultChars   int     // Max chars per tool result when recording
	SummaryTokenBudget   int     // Max output tokens for the compaction summary
	RecentRawTokenBudget int     // Max tokens of recent raw transcript to carry after compaction (0 = auto, <0 = disabled)
	RecentRawTurns       int     // Max recent user turns to try preserving raw (0 = default, <0 = disabled)
	InputLimit           int     // Provider-effective input token limit (0 = use canonical)
}

CompactionConfig controls when and how context compaction occurs.

func DefaultCompactionConfig added in v0.0.80 

func DefaultCompactionConfig() CompactionConfig

DefaultCompactionConfig returns a CompactionConfig with sensible defaults.

type CompactionResult added in v0.0.80 

type CompactionResult struct {
	Summary        string
	NewMessages    []Message
	OriginalCount  int
	CompactedCount int
	Usage          Usage // Token usage/cost of the helper LLM call that produced the summary.
}

CompactionResult describes what happened during compaction.

func Compact added in v0.0.80 

func Compact(ctx context.Context, provider Provider, model, systemPrompt string, messages []Message, config CompactionConfig) (*CompactionResult, error)

Compact generates a structured continuation brief for the older conversation prefix and returns a compacted message list: [system] + [tagged summary as user] + [ack if needed] + [bounded recent raw suffix].

The tagged summary uses the same shape as soft compaction: deterministic <PREVIOUS_TURNS> excerpts from the summarized prefix plus the model-written <SUMMARY_AND_NEXT_ACTIONS> brief. The raw suffix is not sent to the helper, avoiding extractive-summary overlap while preserving exact recent user/assistant/tool structure for continuation.

Instead of serializing the conversation to text, it appends the compaction instruction to the existing messages — leveraging prompt cache on providers like Anthropic — and enforces a token budget on the output.

func CompactionResultFromBrief added in v0.0.274 

func CompactionResultFromBrief(systemPrompt, brief string, messages []Message, config CompactionConfig) *CompactionResult

CompactionResultFromBrief builds a normal CompactionResult from a continuation brief that has already been produced by an LLM. It intentionally avoids a second summary-helper LLM call: a deterministic <PREVIOUS_TURNS> block from the summarized prefix followed by the LLM's Summary / Next Actions becomes the compacted summary, then a bounded recent raw suffix is replayed as true structured messages.

func SoftCompact added in v0.0.274 

func SoftCompact(ctx context.Context, provider Provider, model, systemPrompt string, messages []Message, config CompactionConfig) (*CompactionResult, error)

SoftCompact performs the one LLM call needed for manual soft compaction. The helper asks for a continuation brief using an isolated provider conversation, records that helper-call usage, and then deterministically reconstructs the compacted context from a <PREVIOUS_TURNS> block, the brief, and any bounded raw suffix selected by the shared compaction split.

type ConfigModelLimit added in v0.0.124 

type ConfigModelLimit struct {
	Provider    string // provider config key (e.g., "cdck", "discourse")
	Model       string
	InputLimit  int
	OutputLimit int
}

ConfigModelLimit holds per-model token limits from user config.

type ConfigModelReasoningEfforts added in v0.0.264 

type ConfigModelReasoningEfforts struct {
	Provider string // provider config key (e.g., "cdck_qwen")
	Model    string
	Efforts  []string
}

ConfigModelReasoningEfforts holds per-provider/model reasoning-effort capabilities from user config.

type CopilotProvider added in v0.0.34 

type CopilotProvider struct {
	// contains filtered or unexported fields
}

CopilotProvider implements Provider using GitHub Copilot's OpenAI-compatible API.

func NewCopilotProvider added in v0.0.34 

func NewCopilotProvider(model string) (*CopilotProvider, error)

NewCopilotProvider creates a new Copilot provider. If credentials are not available or expired, it will prompt the user to authenticate.

func NewCopilotProviderWithCreds added in v0.0.34 

func NewCopilotProviderWithCreds(creds *credentials.CopilotCredentials, model string) *CopilotProvider

NewCopilotProviderWithCreds creates a Copilot provider with pre-loaded credentials. This is used by the factory when credentials are already resolved.

func (*CopilotProvider) Capabilities added in v0.0.34 

func (p *CopilotProvider) Capabilities() Capabilities

func (*CopilotProvider) Credential added in v0.0.34 

func (p *CopilotProvider) Credential() string

func (*CopilotProvider) ListModels added in v0.0.34 

func (p *CopilotProvider) ListModels(ctx context.Context) ([]ModelInfo, error)

ListModels returns available models from the GitHub Copilot API

func (*CopilotProvider) Name added in v0.0.34 

func (p *CopilotProvider) Name() string

func (*CopilotProvider) ResetConversation added in v0.0.34 

func (p *CopilotProvider) ResetConversation()

ResetConversation clears server state for the Responses API client. Called on /clear or new conversation.

func (*CopilotProvider) Stream added in v0.0.34 

func (p *CopilotProvider) Stream(ctx context.Context, req Request) (Stream, error)

type DebugLogger added in v0.0.34 

type DebugLogger struct {
	// contains filtered or unexported fields
}

DebugLogger logs LLM requests and events to JSONL files for debugging. Each session gets its own file based on the session ID.

func NewDebugLogger added in v0.0.34 

func NewDebugLogger(baseDir, sessionID string) (*DebugLogger, error)

NewDebugLogger creates a new DebugLogger. The sessionID is used to create a unique filename for this session. Old log files (>7 days) are automatically cleaned up.

func (*DebugLogger) Close added in v0.0.34 

func (l *DebugLogger) Close() error

Close closes the debug logger and flushes any buffered data. Close is idempotent and safe to call multiple times.

func (*DebugLogger) Flush added in v0.0.34 

func (l *DebugLogger) Flush()

Flush flushes the buffered writer to disk.

func (*DebugLogger) LogEvent added in v0.0.34 

func (l *DebugLogger) LogEvent(event Event)

LogEvent logs an LLM event.

func (*DebugLogger) LogRequest added in v0.0.34 

func (l *DebugLogger) LogRequest(provider, model string, req Request)

LogRequest logs an LLM request.

func (*DebugLogger) LogSessionStart added in v0.0.35 

func (l *DebugLogger) LogSessionStart(command string, args []string, cwd string)

LogSessionStart logs the session start with CLI invocation details.

func (*DebugLogger) LogTurnRequest added in v0.0.34 

func (l *DebugLogger) LogTurnRequest(turn int, provider, model string, req Request)

LogTurnRequest logs a request for a specific turn in an agentic loop. This captures the state after tool results have been appended.

type DebugProvider added in v0.0.46 

type DebugProvider struct {
	// contains filtered or unexported fields
}

DebugProvider streams rich markdown content for performance testing.

func NewDebugProvider added in v0.0.46 

func NewDebugProvider(variant string) *DebugProvider

NewDebugProvider creates a debug provider with the specified variant. Valid variants: fast, normal, slow, realtime, burst Empty string defaults to "normal".

func (*DebugProvider) Capabilities added in v0.0.46 

func (d *DebugProvider) Capabilities() Capabilities

Capabilities returns the provider capabilities.

func (*DebugProvider) Credential added in v0.0.46 

func (d *DebugProvider) Credential() string

Credential returns "none" since debug provider needs no authentication.

func (*DebugProvider) Name added in v0.0.46 

func (d *DebugProvider) Name() string

Name returns the provider name with variant.

func (*DebugProvider) Stream added in v0.0.46 

func (d *DebugProvider) Stream(ctx context.Context, req Request) (Stream, error)

Stream starts streaming content based on the request. If tools are provided and the prompt matches a command pattern, emits a tool call. If tool results are present, emits completion text. Otherwise, streams the debug markdown content.

type DiffData added in v0.0.68 

type DiffData struct {
	File      string `json:"f"`
	Old       string `json:"o"`
	New       string `json:"n"`
	Line      int    `json:"l"`            // 1-indexed starting line number
	Operation string `json:"op,omitempty"` // Optional operation hint, e.g. "create" for new files
}

DiffData represents structured diff information from edit/write tools.

type EditToolCall added in v0.0.5 

type EditToolCall struct {
	FilePath  string `json:"file_path"`
	OldString string `json:"old_string"`
	NewString string `json:"new_string"`
}

EditToolCall represents a single edit tool call (find/replace).

func ParseEditToolCall added in v0.0.10 

func ParseEditToolCall(call ToolCall) (EditToolCall, error)

ParseEditToolCall parses a single edit tool call payload.

type Engine added in v0.0.10 

type Engine struct {
	// contains filtered or unexported fields
}

func NewEngine added in v0.0.10 

func NewEngine(provider Provider, tools *ToolRegistry) *Engine

func (*Engine) AddDynamicTool added in v0.0.90 

func (e *Engine) AddDynamicTool(tool Tool)

AddDynamicTool registers a tool and queues its spec to be injected into the active agentic loop's tool list at the start of the next iteration. Use this instead of engine.Tools().Register() when activating skill tools mid-conversation so the LLM sees them immediately on the next turn.

func (*Engine) CancelInterjection added in v0.0.254 

func (e *Engine) CancelInterjection(id string) bool

CancelInterjection removes a queued, not-yet-committed interjection. It returns false if the ID is unknown or has already been drained for a provider request.

func (*Engine) ClearAllowedTools added in v0.0.37 

func (e *Engine) ClearAllowedTools()

ClearAllowedTools removes the tool filter, allowing all registered tools.

func (*Engine) ClearPendingRequestModelSwitch added in v0.0.292 

func (e *Engine) ClearPendingRequestModelSwitch()

ClearPendingRequestModelSwitch cancels any queued same-provider model change.

func (*Engine) ConfigureContextManagement added in v0.0.80 

func (e *Engine) ConfigureContextManagement(provider Provider, providerName, modelName string, autoCompact bool)

ConfigureContextManagement enables compaction or context tracking based on the provider/model's input limit and the autoCompact setting. Providers that manage their own context, or models without a known limit, clear engine-side tracking/compaction to avoid leaking stale settings. Both inputLimit and compactionConfig are set atomically under a single lock.

func (*Engine) ContextEstimateBaseline added in v0.0.161 

func (e *Engine) ContextEstimateBaseline() (int, int)

ContextEstimateBaseline returns the persisted context-estimate baseline: the last observed total tokens and the message count at which it was observed.

func (*Engine) DrainInterjection added in v0.0.82 

func (e *Engine) DrainInterjection() string

DrainInterjection returns pending interjection text and drains all queued interjections. It is retained for legacy recovery paths; new callers should use DrainInterjections or ListPendingInterjections.

func (*Engine) DrainInterjections added in v0.0.254 

func (e *Engine) DrainInterjections() []QueuedInterjection

DrainInterjections drains all queued interjections and marks returned entries committed. Draining is the atomic handoff after which cancellation fails.

func (*Engine) EstimateTokens added in v0.0.105 

func (e *Engine) EstimateTokens(messages []Message) int

EstimateTokens returns the estimated input token count for the next API call based on the current message list. It uses the most recent API usage as a baseline when possible, then adds heuristic estimates for newly appended messages.

func (*Engine) InputLimit added in v0.0.80 

func (e *Engine) InputLimit() int

InputLimit returns the configured input token limit (0 if unknown).

func (*Engine) Interject added in v0.0.82 

func (e *Engine) Interject(text string)

Interject queues a text user message to be inserted after the current turn's tool results, right before the next LLM turn begins. Safe to call from any goroutine.

func (*Engine) InterjectWithID added in v0.0.178 

func (e *Engine) InterjectWithID(id, text string)

InterjectWithID behaves like Interject but preserves a caller-supplied stable identifier.

func (*Engine) IsToolAllowed added in v0.0.37 

func (e *Engine) IsToolAllowed(name string) bool

IsToolAllowed checks if a tool can be executed under current restrictions.

func (*Engine) LastTotalTokens added in v0.0.80 

func (e *Engine) LastTotalTokens() int

LastTotalTokens returns the total tokens (cached+input+output) from the most recent API response, approximating current context fullness.

func (*Engine) ListPendingInterjections added in v0.0.254 

func (e *Engine) ListPendingInterjections() []QueuedInterjection

ListPendingInterjections returns a snapshot of queued, cancellable interjections.

func (*Engine) PeekInterjection added in v0.0.170 

func (e *Engine) PeekInterjection() string

PeekInterjection returns a text summary of currently pending interjections.

func (*Engine) QueueInterjection added in v0.0.254 

func (e *Engine) QueueInterjection(entry QueuedInterjection) string

QueueInterjection appends a structured interjection to the FIFO pending queue and returns its stable ID. The message role is normalized to RoleUser.

func (*Engine) QueueRequestModelSwitch added in v0.0.292 

func (e *Engine) QueueRequestModelSwitch(model string)

QueueRequestModelSwitch requests a same-provider model change for the next provider turn in an active agentic loop. This is intended for reasoning-effort suffix changes while tools are running: the Engine cannot be replaced safely mid-stream, but req.Model can be updated before the next provider.Stream call.

func (*Engine) QueueRequestRuntimeSwitch added in v0.0.292 

func (e *Engine) QueueRequestRuntimeSwitch(model, reasoningEffort string)

QueueRequestRuntimeSwitch requests a same-provider model/effort change for the next provider turn in an active agentic loop.

func (*Engine) RegisterTool added in v0.0.15 

func (e *Engine) RegisterTool(tool Tool)

RegisterTool adds a tool to the engine's registry.

func (*Engine) ResetConversation added in v0.0.82 

func (e *Engine) ResetConversation()

ResetConversation clears all conversation-specific state from the engine. Called on /clear or /new to start a fresh conversation. This resets compaction tracking, context notices, and provider-side conversation state (e.g., OpenAI Responses API previous_response_id).

func (*Engine) SetAllowedTools added in v0.0.37 

func (e *Engine) SetAllowedTools(tools []string)

SetAllowedTools sets the list of tools that can be executed. When set, only tools in this list can run; all others are blocked. Pass nil or empty slice to allow all tools. The list is intersected with registered tools (can't allow unregistered tools).

func (*Engine) SetAssistantSnapshotCallback added in v0.0.174 

func (e *Engine) SetAssistantSnapshotCallback(cb AssistantSnapshotCallback)

SetAssistantSnapshotCallback sets the callback fired during streaming whenever accumulated assistant state materially changes. Implementations MUST upsert the same logical row (keyed by turn index), not append. Used to persist "as we go" so content survives process death mid-turn. Thread-safe: can be called while streaming is in progress.

func (*Engine) SetCompaction added in v0.0.80 

func (e *Engine) SetCompaction(inputLimit int, config CompactionConfig)

SetCompaction enables context compaction with the given input token limit and configuration. Only enable for models with known input limits. Must be called before Stream() or between streams (not during).

func (*Engine) SetCompactionCallback added in v0.0.80 

func (e *Engine) SetCompactionCallback(cb CompactionCallback)

SetCompactionCallback sets the callback for context compaction events. Thread-safe: can be called while streaming is in progress.

func (*Engine) SetContextEstimateBaseline added in v0.0.161 

func (e *Engine) SetContextEstimateBaseline(lastTotalTokens, lastMessageCount int)

SetContextEstimateBaseline seeds the context-estimate baseline, typically from persisted session state on resume.

func (*Engine) SetContextTracking added in v0.0.80 

func (e *Engine) SetContextTracking(inputLimit int)

SetContextTracking enables token tracking without enabling compaction. Use this to track context fullness when auto_compact is disabled. Must be called before Stream() or between streams (not during).

func (*Engine) SetDebugLogger added in v0.0.34 

func (e *Engine) SetDebugLogger(logger *DebugLogger)

SetDebugLogger sets the debug logger for this engine.

func (*Engine) SetMaxToolOutputChars added in v0.0.80 

func (e *Engine) SetMaxToolOutputChars(n int)

SetMaxToolOutputChars sets the global maximum characters for tool output. Tool results exceeding this limit are truncated with head+tail preservation. Pass 0 to disable global truncation.

func (*Engine) SetResponseCompletedCallback added in v0.0.55 

func (e *Engine) SetResponseCompletedCallback(cb ResponseCompletedCallback)

SetResponseCompletedCallback sets the callback for response completion (before tool execution). The callback receives the assistant message immediately after streaming completes. Thread-safe: can be called while streaming is in progress.

func (*Engine) SetTurnCompletedCallback added in v0.0.41 

func (e *Engine) SetTurnCompletedCallback(cb TurnCompletedCallback)

SetTurnCompletedCallback sets the callback for incremental turn completion. The callback receives messages generated each turn for incremental persistence. Thread-safe: can be called while streaming is in progress.

func (*Engine) Stream added in v0.0.10 

func (e *Engine) Stream(ctx context.Context, req Request) (Stream, error)

Stream returns a stream, applying external tools when needed.

func (*Engine) Tools added in v0.0.15 

func (e *Engine) Tools() *ToolRegistry

Tools returns the engine's tool registry.

func (*Engine) TriggerChaosFailure added in v0.0.229 

func (e *Engine) TriggerChaosFailure()

TriggerChaosFailure arms a one-shot synthetic replayable stream failure. It is intentionally tiny and transport-shaped so UI/debug flows exercise the same recovery paths as a prematurely closed SSE/WebSocket stream.

func (*Engine) UnregisterTool added in v0.0.15 

func (e *Engine) UnregisterTool(name string)

UnregisterTool removes a tool from the engine's registry.

type Event added in v0.0.10 

type Event struct {
	Type                      EventType
	Text                      string
	Model                     string // For EventModelSwitch: request model applied at provider-turn boundary
	ReasoningEffort           string // For EventModelSwitch: request reasoning effort applied at provider-turn boundary
	InterjectionID            string // For EventInterjection: stable ID for matching queued interjections in the UI
	InterjectionStatus        InterjectionStatus
	Message                   Message       // For EventInterjection: structured user message including attachments
	ReasoningItemID           string        // For EventReasoningDelta: reasoning item ID
	ReasoningEncryptedContent string        // For EventReasoningDelta: encrypted reasoning content
	ReasoningKind             ReasoningKind // For EventReasoningDelta: summary/raw/encrypted/unknown classification
	ReasoningSummaryParts     []string      // For EventReasoningDelta: structured display-safe summary parts, when available
	ReasoningIndex            int           // For EventReasoningDelta: provider reasoning block/index when available
	ReasoningFinal            bool          // For EventReasoningDelta: true when provider marks the reasoning block complete
	Tool                      *ToolCall
	ToolCallID                string          // For EventToolExecStart/End: unique ID of this tool invocation
	ToolName                  string          // For EventToolExecStart/End: name of tool being executed
	ToolInfo                  string          // For EventToolExecStart/End: additional info (e.g., URL being fetched)
	ToolArgs                  json.RawMessage // For EventToolExecStart: raw args JSON
	ToolSuccess               bool            // For EventToolExecEnd: whether tool execution succeeded
	ToolOutput                string          // For EventToolExecEnd: the tool's text content
	ToolDiffs                 []DiffData      // For EventToolExecEnd: structured diffs from edit tools
	ToolFileChanges           []FileChange    // For EventToolExecEnd: recorded file changes (file tracking)
	ToolImages                []string        // For EventToolExecEnd: image paths from image tools
	Use                       *Usage
	Err                       error
	// Retry fields (for EventRetry). RetryMaxAttempts == 0 means the retry
	// policy is governed by a time budget rather than a fixed attempt count.
	RetryAttempt     int
	RetryMaxAttempts int
	RetryWaitSecs    float64
	// ToolResponse is set when a provider needs synchronous tool execution (claude_bin MCP).
	// The engine will execute the tool and send the result back on this channel.
	ToolResponse chan<- ToolExecutionResponse
	// Image fields (for EventImageGenerated)
	ImageData     []byte // Raw decoded image bytes
	ImageMimeType string // e.g. "image/png"
	RevisedPrompt string // Model's revised prompt, if any
}

Event represents a streamed output update.

type EventType added in v0.0.10 

type EventType string

EventType describes streaming events. 

const (
	EventTextDelta      EventType = "text_delta"
	EventReasoningDelta EventType = "reasoning_delta" // For thinking models (OpenRouter reasoning_content)
	EventToolCall       EventType = "tool_call"
	EventToolExecStart  EventType = "tool_exec_start" // Emitted when tool execution begins
	EventToolExecEnd    EventType = "tool_exec_end"   // Emitted when tool execution completes
	EventHeartbeat      EventType = "heartbeat"       // Emitted while a long-running tool is still active
	EventUsage          EventType = "usage"
	EventPhase          EventType = "phase" // Emitted for high-level phase changes (Thinking, Searching, etc.)
	EventDone           EventType = "done"
	EventError          EventType = "error"
	EventRetry          EventType = "retry"           // Emitted when retrying after rate limit or transport recovery
	EventAttemptDiscard EventType = "attempt_discard" // Discard provisional assistant output from the current streamed attempt
	EventInterjection   EventType = "interjection"    // User interjected a message mid-stream
	EventModelSwitch    EventType = "model_switch"    // Request model changed at a provider-turn boundary
	EventImageGenerated EventType = "image_generated" // Emitted when a built-in image_generation tool returns an image
)

type FileChange added in v0.0.286 

type FileChange struct {
	Path      string `json:"path"`                // Absolute file path
	Kind      string `json:"kind"`                // "create" | "modify" | "delete"
	Adds      int    `json:"adds"`                // Lines added by this change (0 when truncated)
	Dels      int    `json:"dels"`                // Lines removed by this change (0 when truncated)
	Seq       int64  `json:"seq"`                 // Per-session monotonic change sequence
	Truncated bool   `json:"truncated,omitempty"` // Content not retained (size cap, budget, binary, unknown before)
}

FileChange describes one recorded file modification made by a tool. Emitted on EventToolExecEnd when file-change tracking is enabled. Contents are never carried here — only metadata; the recorded blobs are served on demand by the session file-changes endpoints.

type FileUploadPolicy added in v0.0.257 

type FileUploadPolicy struct {
	NativeMimeTypes    []string
	MaxNativeBytes     int64
	TextEmbedMimeTypes []string
	MaxTextEmbedBytes  int64
}

FileUploadPolicy describes provider-level upload capabilities. Native MIME types are allowed to travel as provider-native file/document inputs. Text embed MIME types are safe to inline as ordinary text on providers without native file support.

func DefaultFileUploadPolicyForProviderType added in v0.0.257 

func DefaultFileUploadPolicyForProviderType(providerType config.ProviderType) FileUploadPolicy

DefaultFileUploadPolicyForProviderType returns the built-in upload defaults for a provider implementation. Only providers with an implemented Responses file path get native file MIME types by default.

func DefaultOpenAIResponsesFileUploadPolicy added in v0.0.257 

func DefaultOpenAIResponsesFileUploadPolicy() FileUploadPolicy

DefaultOpenAIResponsesFileUploadPolicy returns the native file types currently documented for OpenAI Responses-style file input. The same policy is used for ChatGPT/Copilot Responses transports unless overridden in config.

func DefaultPortableTextFileUploadPolicy added in v0.0.257 

func DefaultPortableTextFileUploadPolicy() FileUploadPolicy

DefaultPortableTextFileUploadPolicy allows no native file forwarding but keeps portable text-like uploads useful by inlining their contents.

func EffectiveFileUploadPolicyForProviderConfig added in v0.0.257 

func EffectiveFileUploadPolicyForProviderConfig(providerName string, providerCfg config.ProviderConfig) FileUploadPolicy

EffectiveFileUploadPolicyForProviderConfig merges provider defaults with any config-level overrides. A configured empty native_mime_types list intentionally disables native file forwarding for that provider.

func FileUploadPolicyOverrideForProviderConfig added in v0.0.257 

func FileUploadPolicyOverrideForProviderConfig(providerName string, providerCfg config.ProviderConfig) *FileUploadPolicy

FileUploadPolicyOverrideForProviderConfig returns nil when no file_upload block was configured, allowing provider constructors to use their built-in defaults.

func (FileUploadPolicy) AllowsNative added in v0.0.257 

func (p FileUploadPolicy) AllowsNative(mediaType string, sizeBytes int64) bool

func (FileUploadPolicy) AllowsTextEmbed added in v0.0.257 

func (p FileUploadPolicy) AllowsTextEmbed(mediaType string, sizeBytes int64) bool

type FinishingTool added in v0.0.49 

type FinishingTool interface {
	IsFinishingTool() bool
}

FinishingTool is an optional interface for tools that signal agent completion. When a finishing tool is executed, the agentic loop should stop after this turn. Example: output capture tools like set_commit_message.

type GeminiCLIProvider added in v0.0.31 

type GeminiCLIProvider struct {
	// contains filtered or unexported fields
}

GeminiCLIProvider implements Provider using Google Code Assist API with OAuth

func NewGeminiCLIProvider added in v0.0.31 

func NewGeminiCLIProvider(creds *credentials.GeminiOAuthCredentials, model string) *GeminiCLIProvider

func (*GeminiCLIProvider) Capabilities added in v0.0.31 

func (p *GeminiCLIProvider) Capabilities() Capabilities

func (*GeminiCLIProvider) Credential added in v0.0.31 

func (p *GeminiCLIProvider) Credential() string

func (*GeminiCLIProvider) Name added in v0.0.31 

func (p *GeminiCLIProvider) Name() string

func (*GeminiCLIProvider) Stream added in v0.0.31 

func (p *GeminiCLIProvider) Stream(ctx context.Context, req Request) (Stream, error)

type GeminiProvider 

type GeminiProvider struct {
	// contains filtered or unexported fields
}

GeminiProvider implements Provider using the Google Gemini API.

func NewGeminiProvider 

func NewGeminiProvider(apiKey, model string) *GeminiProvider

func (*GeminiProvider) Capabilities added in v0.0.10 

func (p *GeminiProvider) Capabilities() Capabilities

func (*GeminiProvider) Credential added in v0.0.10 

func (p *GeminiProvider) Credential() string

func (*GeminiProvider) Name 

func (p *GeminiProvider) Name() string

func (*GeminiProvider) Stream added in v0.0.10 

func (p *GeminiProvider) Stream(ctx context.Context, req Request) (Stream, error)

type HTTPStatusError added in v0.0.305 

type HTTPStatusError = providerhttp.StatusError

HTTPStatusError is the shared typed HTTP status error used by provider implementations. It preserves response headers so Retry-After can be handled centrally by the retry wrapper.

func NewHTTPStatusError added in v0.0.305 

func NewHTTPStatusError(provider string, resp *http.Response, body []byte) *HTTPStatusError

NewHTTPStatusError returns a typed provider HTTP status error.

func NewHTTPStatusErrorString added in v0.0.305 

func NewHTTPStatusErrorString(provider string, statusCode int, status string, header http.Header, body string) *HTTPStatusError

NewHTTPStatusErrorString returns a typed provider HTTP status error using already-normalized response metadata/body text.

type HandoverResult added in v0.0.134 

type HandoverResult struct {
	Document    string    // The handover document text
	NewMessages []Message // [system] + [handover doc as user] + [assistant ack]
	SourceAgent string
	TargetAgent string
}

HandoverResult describes the outcome of a handover compression.

func Handover added in v0.0.134 

func Handover(ctx context.Context, provider Provider, model, currentSystemPrompt, newSystemPrompt string, messages []Message, sourceAgent, targetAgent string, config CompactionConfig) (*HandoverResult, error)

Handover generates a handover document from the conversation history using the outgoing provider. This is the Tier 2 fallback used when file-based handover is not available. The result contains reconstructed messages suitable for the new agent: [new system prompt] + [handover doc] + [assistant ack].

func HandoverFromFile added in v0.0.134 

func HandoverFromFile(content, newSystemPrompt, sourceAgent, targetAgent string) *HandoverResult

HandoverFromFile creates a HandoverResult from an existing handover document file (Tier 1: zero LLM cost). Used when the outgoing agent has enable_handover set and has written content to the handover directory.

type InterjectionStatus added in v0.0.254 

type InterjectionStatus string
const (
	InterjectionQueued    InterjectionStatus = "queued"
	InterjectionCommitted InterjectionStatus = "committed"
)

type InterruptAction added in v0.0.101 

type InterruptAction int
const (
	InterruptCancel InterruptAction = iota
	InterruptInterject
)

func ClassifyInterrupt added in v0.0.101 

func ClassifyInterrupt(ctx context.Context, fastProvider Provider, msg string, activity InterruptActivity) InterruptAction

ClassifyInterrupt decides how to handle a new user message while a stream is active. It uses instant heuristics first and then an optional fast LLM call.

func ClassifyInterruptImmediate added in v0.0.105 

func ClassifyInterruptImmediate(msg string) (InterruptAction, bool)

ClassifyInterruptImmediate applies zero-latency local heuristics for common interrupt intents. It returns (action, true) when a heuristic matched.

type InterruptActivity added in v0.0.101 

type InterruptActivity struct {
	CurrentTask string
	ToolsRun    []string
	ActiveTool  string
	ProseLen    int
}

InterruptActivity summarizes active stream state for interrupt classification.

type JSONSchema added in v0.0.213 

type JSONSchema struct {
	Type                 *JSONSchemaType
	Description          string
	Enum                 []interface{}
	Items                *JSONSchema
	Properties           map[string]*JSONSchema
	Required             []string
	AdditionalProperties *JSONSchemaAdditionalProperties
	AnyOf                []*JSONSchema
	Extras               map[string]interface{}
}

JSONSchema is a typed, intentionally small JSON Schema model for tool input schemas. Unknown keywords are preserved in Extras so first-party metadata such as default/title/minimum and MCP extension fields are not dropped while we gradually migrate away from raw map schemas.

func ParseToolJSONSchema added in v0.0.213 

func ParseToolJSONSchema(raw interface{}) (*JSONSchema, error)

ParseToolJSONSchema sanitizes a raw JSON-schema-like value from first-party tools or MCP and parses it into a typed schema model. It is deliberately permissive: malformed schema fragments are coerced to broad string/object/ array shapes rather than making an entire LLM request fail.

func ParseToolJSONSchemaMap added in v0.0.213 

func ParseToolJSONSchemaMap(schema map[string]interface{}) (*JSONSchema, error)

ParseToolJSONSchemaMap is a convenience wrapper for map-based ToolSpec.Schema.

func (*JSONSchema) MarshalJSON added in v0.0.213 

func (s *JSONSchema) MarshalJSON() ([]byte, error)

MarshalJSON keeps the typed model easy to inspect in debug output and tests.

func (*JSONSchema) ToMap added in v0.0.213 

func (s *JSONSchema) ToMap() map[string]interface{}

ToMap serializes the typed schema back to a map representation accepted by the existing provider-specific normalizers.

func (*JSONSchema) ToOpenAIParameters added in v0.0.213 

func (s *JSONSchema) ToOpenAIParameters(strict bool) map[string]interface{}

ToOpenAIParameters serializes the typed schema into the OpenAI Responses function-tool `parameters` shape. In strict mode this applies OpenAI's stricter structured-output subset on top of the provider-neutral sanitized schema.

func (*JSONSchema) ToOpenResponsesParameters added in v0.0.213 

func (s *JSONSchema) ToOpenResponsesParameters() map[string]interface{}

ToOpenResponsesParameters serializes the typed schema into the provider-neutral Open Responses function-tool `parameters` shape. It intentionally avoids OpenAI-specific strict-schema rewrites such as forcing every property into `required` or converting free-form maps to arrays.

type JSONSchemaAdditionalProperties added in v0.0.213 

type JSONSchemaAdditionalProperties struct {
	Bool   *bool
	Schema *JSONSchema
}

JSONSchemaAdditionalProperties represents the two valid forms of additionalProperties: a boolean or a schema for free-form map values.

type JSONSchemaPrimitiveType added in v0.0.213 

type JSONSchemaPrimitiveType string

JSONSchemaPrimitiveType is the JSON Schema primitive type subset supported by OpenAI tool schemas and by the sanitizer we use for broad MCP schemas. 

const (
	JSONSchemaString  JSONSchemaPrimitiveType = "string"
	JSONSchemaNumber  JSONSchemaPrimitiveType = "number"
	JSONSchemaBoolean JSONSchemaPrimitiveType = "boolean"
	JSONSchemaInteger JSONSchemaPrimitiveType = "integer"
	JSONSchemaObject  JSONSchemaPrimitiveType = "object"
	JSONSchemaArray   JSONSchemaPrimitiveType = "array"
	JSONSchemaNull    JSONSchemaPrimitiveType = "null"
)

type JSONSchemaType added in v0.0.213 

type JSONSchemaType struct {
	Types []JSONSchemaPrimitiveType
}

JSONSchemaType represents JSON Schema's `type`, which can be either one primitive type or a union of primitive types in source schemas. Provider adapters may serialize unions differently (for example OpenAI strict mode uses anyOf rather than a type array).

type MaxTurnsExceededError added in v0.0.259 

type MaxTurnsExceededError struct {
	MaxTurns int
}

MaxTurnsExceededError reports that the agentic loop exhausted its configured turn budget before reaching a natural completion.

func (*MaxTurnsExceededError) Error added in v0.0.259 

func (e *MaxTurnsExceededError) Error() string

type Message added in v0.0.10 

type Message struct {
	Role        Role
	Parts       []Part
	CacheAnchor bool // provider should apply cache_control to this message (Anthropic-specific)
}

Message holds a role with structured parts.

func AssistantText added in v0.0.10 

func AssistantText(text string) Message

func FilterConversationMessages added in v0.0.205 

func FilterConversationMessages(messages []Message) []Message

FilterConversationMessages removes durable UI/session event markers and other non-conversation rows before context is sent to providers, compaction, handover, or token estimation. It returns a shallow copy preserving cache anchors.

func ModelSwapEventMessage added in v0.0.205 

func ModelSwapEventMessage(marker ModelSwapMarker) Message

ModelSwapEventMessage returns a RoleEvent message suitable for durable transcript storage. It intentionally uses a text part containing structured JSON so existing session storage schemas can persist it without migration.

func ReconstructHandoverHistory added in v0.0.134 

func ReconstructHandoverHistory(systemPrompt, document, sourceAgent, targetAgent string) []Message

ReconstructHandoverHistory builds the message list for the new agent: [SystemText(newSystemPrompt)] + [handover doc (user, CacheAnchor)] + [assistant ack].

func SystemText added in v0.0.10 

func SystemText(text string) Message

func ToolErrorMessage added in v0.0.23 

func ToolErrorMessage(id, name, errorText string, thoughtSig []byte) Message

ToolErrorMessage creates a tool result message that indicates an error. The error is passed to the LLM so it can respond gracefully instead of failing the stream.

func ToolResultMessage added in v0.0.10 

func ToolResultMessage(id, name, content string, thoughtSig []byte) Message

ToolResultMessage creates a tool result message from a plain string. Convenience wrapper for callers that only have text content (no diffs/images).

func ToolResultMessageFromOutput added in v0.0.68 

func ToolResultMessageFromOutput(id, name string, output ToolOutput, thoughtSig []byte) Message

func UserImageMessage added in v0.0.89 

func UserImageMessage(mediaType, base64Data, caption string) Message

UserImageMessage creates a user message with an image and an optional text caption.

func UserImageMessageWithPath added in v0.0.89 

func UserImageMessageWithPath(mediaType, base64Data, filePath, caption string) Message

UserImageMessageWithPath creates a user message with an image, an optional local file path (so tools like image_generate can reference it), and an optional caption.

func UserText added in v0.0.10 

func UserText(text string) Message

type MockProvider added in v0.0.25 

type MockProvider struct {
	Requests []Request // Recorded requests for verification
	// contains filtered or unexported fields
}

MockProvider is a configurable provider for testing. It returns scripted responses and records all requests for verification.

func NewMockProvider added in v0.0.25 

func NewMockProvider(name string) *MockProvider

NewMockProvider creates a new mock provider with the given name.

func (*MockProvider) AddError added in v0.0.25 

func (m *MockProvider) AddError(err error) *MockProvider

AddError adds a turn that returns an error.

func (*MockProvider) AddTextResponse added in v0.0.25 

func (m *MockProvider) AddTextResponse(text string) *MockProvider

AddTextResponse is a convenience method to add a simple text response.

func (*MockProvider) AddToolCall added in v0.0.25 

func (m *MockProvider) AddToolCall(id, name string, args any) *MockProvider

AddToolCall is a convenience method to add a turn with a single tool call.

func (*MockProvider) AddTurn added in v0.0.25 

func (m *MockProvider) AddTurn(t MockTurn) *MockProvider

AddTurn adds a response turn and returns the provider for chaining.

func (*MockProvider) Capabilities added in v0.0.25 

func (m *MockProvider) Capabilities() Capabilities

Capabilities returns the provider capabilities.

func (*MockProvider) Credential added in v0.0.25 

func (m *MockProvider) Credential() string

Credential returns "mock" for the mock provider.

func (*MockProvider) CurrentTurn added in v0.0.25 

func (m *MockProvider) CurrentTurn() int

CurrentTurn returns the current turn index (0-based).

func (*MockProvider) Name added in v0.0.25 

func (m *MockProvider) Name() string

Name returns the provider name.

func (*MockProvider) Reset added in v0.0.25 

func (m *MockProvider) Reset()

Reset clears recorded requests and resets the turn index.

func (*MockProvider) ResetTurns added in v0.0.25 

func (m *MockProvider) ResetTurns()

ResetTurns clears the scripted turns and resets the turn index.

func (*MockProvider) Stream added in v0.0.25 

func (m *MockProvider) Stream(ctx context.Context, req Request) (Stream, error)

Stream implements the Provider interface.

func (*MockProvider) TurnCount added in v0.0.25 

func (m *MockProvider) TurnCount() int

TurnCount returns the number of scripted turns.

func (*MockProvider) WithCapabilities added in v0.0.25 

func (m *MockProvider) WithCapabilities(c Capabilities) *MockProvider

WithCapabilities sets the provider capabilities and returns the provider for chaining.

type MockTurn added in v0.0.25 

type MockTurn struct {
	Text      string        // Text to emit (will be chunked for realistic streaming)
	ToolCalls []ToolCall    // Tool calls to emit
	Usage     Usage         // Token usage to report
	Delay     time.Duration // Optional delay before responding (for timeout tests)
	Error     error         // Return this error instead of responding
}

MockTurn represents a single response turn from the mock provider.

type ModelEntry added in v0.0.140 

type ModelEntry struct {
	ID               string
	InputLimit       int      // effective input budget (context - output reserve)
	OutputLimit      int      // max output tokens
	ReasoningEfforts []string // supported suffix-based reasoning-effort aliases (e.g. low, medium, high)
}

ModelEntry describes a model available through a specific provider. InputLimit and OutputLimit are the effective token budgets for compaction and output clamping. A value of 0 means "unknown — fall back to prefix tables in context_window.go".

type ModelInfo added in v0.0.8 

type ModelInfo struct {
	ID                   string             `json:"id"`
	DisplayName          string             `json:"display_name,omitempty"`
	Created              int64              `json:"created,omitempty"`
	OwnedBy              string             `json:"owned_by,omitempty"`
	InputLimit           int                `json:"input_limit,omitempty"` // Max input tokens (0 = unknown)
	InputPrice           float64            `json:"input_price"`           // Pricing per 1M tokens (0 = free, -1 = unknown)
	OutputPrice          float64            `json:"output_price"`          // Pricing per 1M tokens (0 = free, -1 = unknown)
	ServiceTiers         []ModelServiceTier `json:"service_tiers,omitempty"`
	AdditionalSpeedTiers []string           `json:"additional_speed_tiers,omitempty"`
}

ModelInfo represents a model available from a provider.

func CachedChatGPTModels added in v0.0.231 

func CachedChatGPTModels() (models []ModelInfo, fresh bool, err error)

CachedChatGPTModels returns cached ChatGPT model metadata, if present. Fresh is false when the cache is stale but still usable as a network-failure fallback.

func GetCachedCopilotModelInfos added in v0.0.275 

func GetCachedCopilotModelInfos() []ModelInfo

GetCachedCopilotModelInfos returns cached live Copilot model metadata. Stale cache entries are still returned because they are preferable to hardcoded model lists and keep non-network callers fast.

func GetCachedOpenRouterModelInfos added in v0.0.267 

func GetCachedOpenRouterModelInfos(apiKey string) []ModelInfo

func GetCachedVeniceModelInfos added in v0.0.268 

func GetCachedVeniceModelInfos(apiKey string) []ModelInfo

type ModelServiceTier added in v0.0.231 

type ModelServiceTier struct {
	ID          string `json:"id"`
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
}

ModelServiceTier describes an optional service tier advertised by a model catalog.

type ModelSwapMarker added in v0.0.205 

type ModelSwapMarker struct {
	Type         string `json:"type"`
	FromProvider string `json:"from_provider,omitempty"`
	FromModel    string `json:"from_model,omitempty"`
	FromEffort   string `json:"from_effort,omitempty"`
	ToProvider   string `json:"to_provider,omitempty"`
	ToModel      string `json:"to_model,omitempty"`
	ToEffort     string `json:"to_effort,omitempty"`
	Strategy     string `json:"strategy,omitempty"`
	Status       string `json:"status,omitempty"`
	DisplayText  string `json:"display_text,omitempty"`
}

ModelSwapMarker is a durable non-LLM transcript event describing a provider or model switch. Store/render layers may persist this, but provider request builders must filter RoleEvent messages before sending context to an LLM.

func ParseModelSwapMarker added in v0.0.205 

func ParseModelSwapMarker(msg Message) (ModelSwapMarker, bool)

ParseModelSwapMarker extracts a model-swap marker from a durable event message.

type NearAIProvider added in v0.0.243 

type NearAIProvider struct {
	*OpenAICompatProvider
}

func NewNearAIProvider added in v0.0.243 

func NewNearAIProvider(apiKey, model string) *NearAIProvider

func (*NearAIProvider) Capabilities added in v0.0.243 

func (p *NearAIProvider) Capabilities() Capabilities

func (*NearAIProvider) ListModels added in v0.0.243 

func (p *NearAIProvider) ListModels(ctx context.Context) ([]ModelInfo, error)

type NonRecoverableStreamError added in v0.0.227 

type NonRecoverableStreamError struct {
	Err error
}

func (*NonRecoverableStreamError) Error added in v0.0.227 

func (e *NonRecoverableStreamError) Error() string

func (*NonRecoverableStreamError) Unwrap added in v0.0.227 

func (e *NonRecoverableStreamError) Unwrap() error

type OllamaOptions added in v0.0.179 

type OllamaOptions struct {
	Think           *bool
	TopK            *int
	MinP            *float64
	PresencePenalty *float64
	NumCtx          *int
	NumPredict      *int
}

OllamaOptions holds Ollama-native generation knobs that have no equivalent in the shared Request struct.

type OllamaProvider added in v0.0.179 

type OllamaProvider struct {
	// contains filtered or unexported fields
}

OllamaProvider implements Provider using the native Ollama /api/chat endpoint. It supports the think flag (for extended reasoning models like Qwen3), tool calls, and Ollama-native sampling options.

func NewOllamaChatProvider added in v0.0.179 

func NewOllamaChatProvider(baseURL, model string, opts OllamaOptions) *OllamaProvider

NewOllamaChatProvider creates a native Ollama chat provider. baseURL defaults to the OLLAMA_HOST env var, then http://127.0.0.1:11434. model defaults to qwen2.5-coder:7b.

func (*OllamaProvider) Capabilities added in v0.0.179 

func (p *OllamaProvider) Capabilities() Capabilities

func (*OllamaProvider) Credential added in v0.0.179 

func (p *OllamaProvider) Credential() string

func (*OllamaProvider) ListModels added in v0.0.179 

func (p *OllamaProvider) ListModels(ctx context.Context) ([]ModelInfo, error)

ListModels returns locally available Ollama models via /api/tags.

func (*OllamaProvider) Name added in v0.0.179 

func (p *OllamaProvider) Name() string

func (*OllamaProvider) Stream added in v0.0.179 

func (p *OllamaProvider) Stream(ctx context.Context, req Request) (Stream, error)

type OpenAICompatProvider added in v0.0.8 

type OpenAICompatProvider struct {
	// contains filtered or unexported fields
}

OpenAICompatProvider implements Provider for OpenAI-compatible APIs Used by Ollama, LM Studio, and other compatible servers.

func NewOpenAICompatProvider added in v0.0.8 

func NewOpenAICompatProvider(baseURL, apiKey, model, name string) *OpenAICompatProvider

func NewOpenAICompatProviderFull added in v0.0.15 

func NewOpenAICompatProviderFull(baseURL, chatURL, apiKey, model, name string, headers map[string]string) *OpenAICompatProvider

NewOpenAICompatProviderFull creates a provider with full control over URLs. If chatURL is provided, it's used directly for chat completions (no path appending). If only baseURL is provided, /chat/completions is appended. baseURL is normalized to strip /chat/completions if accidentally included.

func NewOpenAICompatProviderWithHeaders added in v0.0.10 

func NewOpenAICompatProviderWithHeaders(baseURL, apiKey, model, name string, headers map[string]string) *OpenAICompatProvider

func NewOpenRouterProvider added in v0.0.10 

func NewOpenRouterProvider(apiKey, model, appURL, appTitle string) *OpenAICompatProvider

NewOpenRouterProvider creates an OpenRouter provider using OpenAI-compatible APIs.

func (*OpenAICompatProvider) Capabilities added in v0.0.10 

func (p *OpenAICompatProvider) Capabilities() Capabilities

func (*OpenAICompatProvider) Credential added in v0.0.10 

func (p *OpenAICompatProvider) Credential() string

func (*OpenAICompatProvider) ListModels added in v0.0.8 

func (p *OpenAICompatProvider) ListModels(ctx context.Context) ([]ModelInfo, error)

ListModels returns available models from the server.

func (*OpenAICompatProvider) Name added in v0.0.8 

func (p *OpenAICompatProvider) Name() string

func (*OpenAICompatProvider) SetModelConfigs added in v0.0.295 

func (p *OpenAICompatProvider) SetModelConfigs(modelConfigs []config.ProviderModelConfig)

func (*OpenAICompatProvider) SetReasoningParser added in v0.0.295 

func (p *OpenAICompatProvider) SetReasoningParser(parseReasoning, includeReasoning *bool, thinkingParam string)

func (*OpenAICompatProvider) Stream added in v0.0.10 

func (p *OpenAICompatProvider) Stream(ctx context.Context, req Request) (Stream, error)

type OpenAIProvider 

type OpenAIProvider struct {
	// contains filtered or unexported fields
}

OpenAIProvider implements Provider using the standard OpenAI API.

func NewOpenAIProvider 

func NewOpenAIProvider(apiKey, model string) *OpenAIProvider

func NewOpenAIProviderWithOptions added in v0.0.204 

func NewOpenAIProviderWithOptions(apiKey, model string, opts OpenAIProviderOptions) *OpenAIProvider

func (*OpenAIProvider) Capabilities added in v0.0.10 

func (p *OpenAIProvider) Capabilities() Capabilities

func (*OpenAIProvider) Credential added in v0.0.10 

func (p *OpenAIProvider) Credential() string

func (*OpenAIProvider) ListModels added in v0.0.31 

func (p *OpenAIProvider) ListModels(ctx context.Context) ([]ModelInfo, error)

func (*OpenAIProvider) Name 

func (p *OpenAIProvider) Name() string

func (*OpenAIProvider) ResetConversation added in v0.0.34 

func (p *OpenAIProvider) ResetConversation()

ResetConversation clears server state for the Responses API client. Called on /clear or new conversation.

func (*OpenAIProvider) Stream added in v0.0.10 

func (p *OpenAIProvider) Stream(ctx context.Context, req Request) (Stream, error)

type OpenAIProviderOptions added in v0.0.204 

type OpenAIProviderOptions struct {
	UseWebSocket     bool
	ServiceTier      string
	FileUploadPolicy *FileUploadPolicy
}

type Part added in v0.0.10 

type Part struct {
	Type                      PartType
	Text                      string
	ReasoningContent          string         // Reasoning summary text or provider thinking content (classified by ReasoningKind)
	ReasoningSummaryParts     []string       // Display-safe Responses reasoning summary array elements, when provider supplies structure
	ReasoningItemID           string         // Responses API reasoning item ID for replay
	ReasoningEncryptedContent string         // Provider encrypted reasoning/signature content for replay; never displayed
	ReasoningKind             ReasoningKind  // Classification for ReasoningContent/replay metadata
	ReasoningSummaryTitle     string         // Optional parsed display title for summary reasoning
	ImageData                 *ToolImageData // User-supplied image (base64-encoded)
	ImagePath                 string         // Local filesystem path to the image (when available, e.g. Telegram uploads)
	FileData                  *ToolFileData  // User-supplied file (base64-encoded)
	FilePath                  string         // Local filesystem path to the file (when available)
	ToolCall                  *ToolCall
	ToolResult                *ToolResult
}

Part represents a single content part.

type PartType added in v0.0.10 

type PartType string

PartType identifies a message content part. 

const (
	PartText       PartType = "text"
	PartImage      PartType = "image"
	PartFile       PartType = "file"
	PartToolCall   PartType = "tool_call"
	PartToolResult PartType = "tool_result"
)

type Provider 

type Provider interface {
	Name() string
	Credential() string // Returns credential type for debugging (e.g., "api_key", "codex", "claude-code")
	Capabilities() Capabilities
	Stream(ctx context.Context, req Request) (Stream, error)
}

Provider streams model output events for a request.

func NewFastProvider added in v0.0.101 

func NewFastProvider(cfg *config.Config, name string) (Provider, error)

NewFastProvider creates a lightweight provider instance for the specified provider key. Resolution order: 1. providers.<name>.fast_provider + fast_model 2. providers.<name>.fast_model on the same provider key 3. built-in ProviderFastModels fallback for inferred provider type Returns nil, nil if no fast model can be resolved.

func NewProvider 

func NewProvider(cfg *config.Config) (Provider, error)

NewProvider creates a new LLM provider based on the config. Providers are wrapped with automatic retry for rate limits (429) and transient errors.

func NewProviderByName added in v0.0.15 

func NewProviderByName(cfg *config.Config, name string, model string) (Provider, error)

NewProviderByName creates a provider by name from the config, with an optional model override. This is useful for per-command provider overrides. If the provider is a built-in type but not explicitly configured, it will be created with default settings.

func WrapWithRetry added in v0.0.12 

func WrapWithRetry(p Provider, config RetryConfig) Provider

WrapWithRetry wraps a provider with retry logic.

type ProviderCleaner added in v0.0.52 

type ProviderCleaner interface {
	CleanupMCP()
}

ProviderCleaner is an optional interface for providers that need cleanup after a conversation ends (e.g., claude-bin's persistent MCP server). Call sites: runtime eviction, server shutdown. Do NOT call per-turn.

type ProviderStateExporter added in v0.0.289 

type ProviderStateExporter interface {
	ExportProviderState() ([]byte, bool)
}

ProviderStateExporter is implemented by stateful providers that can persist opaque conversation transport state outside the user-visible transcript. The returned bytes must be safe to store in the session database.

type ProviderStateImporter added in v0.0.289 

type ProviderStateImporter interface {
	ImportProviderState([]byte) error
}

ProviderStateImporter restores state previously returned by ProviderStateExporter. Providers should validate and ignore unusable state by returning an error rather than partially applying it.

type ProviderTurnCleaner added in v0.0.168 

type ProviderTurnCleaner interface {
	CleanupTurn()
}

ProviderTurnCleaner is an optional interface for providers that need cleanup after each turn's stream ends (e.g., temp image files materialised for a single turn). Engine wraps agentic streams to invoke this on stream termination as a safety net for consumers that drop streams without Close().

type QueuedInterjection added in v0.0.254 

type QueuedInterjection struct {
	ID           string
	Message      Message
	DisplayText  string
	Status       InterjectionStatus
	AutoContinue bool // If true, drain at a text-only turn boundary and continue the run.
}

QueuedInterjection is a structured user message submitted while a run is active. Queued entries are cancellable until the engine drains them into a provider turn.

type RateLimitError added in v0.0.33 

type RateLimitError struct {
	Message        string
	RetryAfter     time.Duration
	PlanType       string
	PrimaryUsed    int
	PrimaryLimit   int
	SecondaryUsed  int
	SecondaryLimit int
}

RateLimitError represents a rate limit error with retry information.

func (*RateLimitError) Error added in v0.0.33 

func (e *RateLimitError) Error() string

func (*RateLimitError) RetryAfterDelay added in v0.0.305 

func (e *RateLimitError) RetryAfterDelay() (time.Duration, bool)

RetryAfterDelay exposes structured Retry-After metadata to the retry loop.

type ReadURLTool added in v0.0.11 

type ReadURLTool struct {
	// contains filtered or unexported fields
}

ReadURLTool fetches web pages using Jina AI Reader by default.

func NewReadURLTool added in v0.0.11 

func NewReadURLTool() *ReadURLTool

func NewReadURLToolWithFetcher added in v0.0.247 

func NewReadURLToolWithFetcher(fetcher URLFetcher) *ReadURLTool

func (*ReadURLTool) Execute added in v0.0.11 

func (t *ReadURLTool) Execute(ctx context.Context, args json.RawMessage) (ToolOutput, error)

func (*ReadURLTool) Preview added in v0.0.25 

func (t *ReadURLTool) Preview(args json.RawMessage) string

func (*ReadURLTool) Spec added in v0.0.11 

func (t *ReadURLTool) Spec() ToolSpec

type ReasoningKind added in v0.0.258 

type ReasoningKind string

ReasoningKind classifies provider reasoning/thinking payloads for safe display. 

const (
	ReasoningKindUnknown   ReasoningKind = "unknown"
	ReasoningKindSummary   ReasoningKind = "summary"
	ReasoningKindRaw       ReasoningKind = "raw"
	ReasoningKindEncrypted ReasoningKind = "encrypted"
)

func MergeReasoningKind added in v0.0.258 

func MergeReasoningKind(current, incoming ReasoningKind) ReasoningKind

MergeReasoningKind combines accumulated and incoming reasoning classifications. Empty incoming kinds mean "no provider signal". Unknown is not a positive classification signal, encrypted is replay-only until displayable summary/raw text arrives, and raw wins over summary when both appear in the same block.

func NormalizeReasoningKind added in v0.0.258 

func NormalizeReasoningKind(kind ReasoningKind) ReasoningKind

NormalizeReasoningKind returns a conservative non-empty reasoning kind.

func NormalizeStoredReasoningKind added in v0.0.258 

func NormalizeStoredReasoningKind(kind ReasoningKind, hasReasoningContent bool) ReasoningKind

NormalizeStoredReasoningKind preserves the historical meaning of persisted assistant parts from before ReasoningKind existed. Those parts stored only display-safe summaries in ReasoningContent, so an empty kind with content is treated as a summary when rendering/exporting stored sessions. Live provider events should continue using NormalizeReasoningKind.

type Request added in v0.0.10 

type Request struct {
	Model                   string
	SessionID               string // Optional session ID for provider-side continuity/caching hints
	Messages                []Message
	Tools                   []ToolSpec
	ToolChoice              ToolChoice
	LastTurnToolChoice      *ToolChoice // If set, force this tool choice on the last agentic turn
	ParallelToolCalls       bool
	Search                  bool
	ForceExternalSearch     bool // If true, use external search even if provider supports native
	DisableExternalWebFetch bool // If true, do not inject external read_url even when provider lacks native fetch
	ReasoningEffort         string
	MaxOutputTokens         int
	Temperature             float32
	TemperatureSet          bool // If true, Temperature was explicitly provided, including zero
	TopP                    float32
	TopPSet                 bool              // If true, TopP was explicitly provided, including zero
	ServiceTier             string            // Optional Responses API service tier; "priority" enables ChatGPT fast mode
	ServiceTierSet          bool              // If true, ServiceTier overrides any provider-level default; empty clears it
	MaxTurns                int               // Max agentic turns for tool execution (0 = use default)
	ToolMap                 map[string]string // Maps client tool names to server tool names (e.g. "WebSearch" → "search")
	Debug                   bool
	DebugRaw                bool
}

Request represents a single model turn.

type ResponseCompletedCallback added in v0.0.55 

type ResponseCompletedCallback func(ctx context.Context, turnIndex int, assistantMsg Message, metrics TurnMetrics) error

ResponseCompletedCallback is called immediately after LLM streaming completes, BEFORE tool execution. This enables incremental persistence of assistant messages so they're saved even if the process crashes during tool execution. The message contains only the assistant's response (no tool results yet).

type ResponsesClient added in v0.0.34 

type ResponsesClient struct {
	BaseURL            string            // Full URL for responses endpoint (e.g., "https://api.openai.com/v1/responses")
	GetAuthHeader      func() string     // Dynamic auth (allows token refresh)
	ExtraHeaders       map[string]string // Provider-specific headers
	HTTPClient         *http.Client      // HTTP client to use
	LastResponseID     string            // Track for conversation continuity (server state)
	DisableServerState bool              // Set to true to disable previous_response_id (e.g., for Copilot)

	// Optional Responses-over-WebSocket transport, controlled by provider config.
	UseWebSocket bool
	// WebSocketServerState enables previous_response_id only for the WebSocket
	// transport while keeping HTTP/SSE full-history. This is used for ChatGPT,
	// whose WebSocket backend supports connection-local continuation but whose
	// HTTP endpoint may reject previous_response_id.
	WebSocketServerState    bool
	WebSocketURL            string
	WebSocketConnectTimeout time.Duration
	WebSocketWriteTimeout   time.Duration
	WebSocketIdleTimeout    time.Duration

	// HandleError, if set, is called for non-200 responses before default handling.
	// Return a non-nil error to short-circuit; return nil to fall through to defaults.
	HandleError func(statusCode int, body []byte, headers http.Header) error
	// OnAuthRetry, if set, is called when a 401/403 is received.
	// The current request context is passed so that refresh operations
	// use a live context rather than a potentially canceled one.
	// If it returns nil (success), the request is retried with fresh credentials.
	// If it returns an error, that error is returned to the caller.
	OnAuthRetry func(ctx context.Context) error
	// contains filtered or unexported fields
}

ResponsesClient makes raw HTTP calls to Open Responses-compliant endpoints. See https://www.openresponses.org/specification

func NewChatGPTResponsesClient added in v0.0.176 

func NewChatGPTResponsesClient(creds *credentials.ChatGPTCredentials) *ResponsesClient

NewChatGPTResponsesClient builds a ResponsesClient pre-configured for the chatgpt.com backend endpoint, handling auth, refresh, and rate-limit error parsing. Shared by the LLM provider and the image provider so both pick up the same headers, token-refresh behaviour, and 429 handling.

func (*ResponsesClient) ResetConversation added in v0.0.34 

func (c *ResponsesClient) ResetConversation()

ResetConversation clears server state (called on /clear or new conversation)

func (*ResponsesClient) Stream added in v0.0.34 

func (c *ResponsesClient) Stream(ctx context.Context, req ResponsesRequest, debugRaw bool) (Stream, error)

Stream makes a streaming request to the Responses API and returns events via a Stream

type ResponsesContentPart added in v0.0.34 

type ResponsesContentPart struct {
	Type     string `json:"type"`
	Text     string `json:"text,omitempty"`
	ImageURL string `json:"image_url,omitempty"` // Plain URL string for Responses API (not object)
	Detail   string `json:"detail,omitempty"`
	Filename string `json:"filename,omitempty"`
	FileData string `json:"file_data,omitempty"`
}

ResponsesContentPart represents a content part (text, image, or file).

type ResponsesImageGenerationTool added in v0.0.176 

type ResponsesImageGenerationTool struct {
	Type         string `json:"type"`                    // "image_generation"
	OutputFormat string `json:"output_format,omitempty"` // "png", "jpeg", "webp"
}

ResponsesImageGenerationTool represents the built-in image_generation tool. See https://platform.openai.com/docs/guides/tools-image-generation

type ResponsesInputItem added in v0.0.34 

type ResponsesInputItem struct {
	Type    string      `json:"type"`
	Role    string      `json:"role,omitempty"`
	Content interface{} `json:"content,omitempty"` // string or []ResponsesContentPart
	// For reasoning type
	ID               string                     `json:"id,omitempty"`
	EncryptedContent string                     `json:"encrypted_content,omitempty"`
	Summary          *responsesReasoningSummary `json:"summary,omitempty"`
	// For function_call type
	CallID    string `json:"call_id,omitempty"`
	Name      string `json:"name,omitempty"`
	Arguments string `json:"arguments,omitempty"`
	// For function_call_output type
	Output string `json:"output,omitempty"`
}

ResponsesInputItem represents an input item in the Open Responses format

func BuildResponsesContinuationInput added in v0.0.219 

func BuildResponsesContinuationInput(messages []Message) []ResponsesInputItem

BuildResponsesContinuationInput converts only the newest turn payload needed for a server-state continuation. Unlike BuildResponsesInput it intentionally skips whole-transcript tool-history sanitization so trailing tool results can be sent back against server-side conversation state without rebuilding earlier turns.

func BuildResponsesContinuationInputWithFilePolicy added in v0.0.257 

func BuildResponsesContinuationInputWithFilePolicy(messages []Message, policy *FileUploadPolicy) []ResponsesInputItem

BuildResponsesContinuationInputWithFilePolicy converts only the newest turn payload needed for a server-state continuation, using the supplied file policy for any new file parts.

func BuildResponsesInput added in v0.0.34 

func BuildResponsesInput(messages []Message) []ResponsesInputItem

BuildResponsesInput converts []Message to Open Responses input format.

func BuildResponsesInputWithFilePolicy added in v0.0.257 

func BuildResponsesInputWithFilePolicy(messages []Message, policy *FileUploadPolicy) []ResponsesInputItem

BuildResponsesInputWithFilePolicy converts []Message to Open Responses input format and sends PartFile as native input_file only when policy allows its MIME type and decoded size. Passing nil uses OpenAI Responses defaults.

func BuildResponsesInputWithInstructions added in v0.0.111 

func BuildResponsesInputWithInstructions(messages []Message) (instructions string, input []ResponsesInputItem)

BuildResponsesInputWithInstructions converts []Message to Open Responses input format, extracting system messages as a separate instructions string instead of including them as developer-role input items. This is used by providers that send system content via the "instructions" request field (e.g., ChatGPT).

func BuildResponsesInputWithInstructionsAndFilePolicy added in v0.0.257 

func BuildResponsesInputWithInstructionsAndFilePolicy(messages []Message, policy *FileUploadPolicy) (instructions string, input []ResponsesInputItem)

BuildResponsesInputWithInstructionsAndFilePolicy is like BuildResponsesInputWithInstructions but gates native input_file parts using the supplied provider policy.

type ResponsesReasoning added in v0.0.34 

type ResponsesReasoning struct {
	Effort  string `json:"effort,omitempty"`  // "low", "medium", "high", "xhigh"
	Summary string `json:"summary,omitempty"` // "auto"
}

ResponsesReasoning configures reasoning effort for models that support it

type ResponsesRequest added in v0.0.34 

type ResponsesRequest struct {
	Model                           string               `json:"model"`
	Instructions                    string               `json:"instructions,omitempty"` // System instructions (alternative to developer-role input items)
	Input                           []ResponsesInputItem `json:"input"`
	Messages                        []Message            `json:"-"`               // Optional raw transcript for lazy input materialization
	ExtractInstructionsFromMessages bool                 `json:"-"`               // When lazily materializing Input from Messages, omit system messages because they are sent via Instructions.
	Tools                           []any                `json:"tools,omitempty"` // Can contain ResponsesTool or ResponsesWebSearchTool
	ToolChoice                      any                  `json:"tool_choice,omitempty"`
	ParallelToolCalls               *bool                `json:"parallel_tool_calls,omitempty"`
	MaxOutputTokens                 int                  `json:"max_output_tokens,omitempty"`
	Temperature                     *float64             `json:"temperature,omitempty"`
	TopP                            *float64             `json:"top_p,omitempty"`
	Reasoning                       *ResponsesReasoning  `json:"reasoning,omitempty"`
	Include                         []string             `json:"include,omitempty"`
	PromptCacheKey                  string               `json:"prompt_cache_key,omitempty"`
	Store                           *bool                `json:"store,omitempty"`
	Generate                        *bool                `json:"generate,omitempty"` // WebSocket warmup support; omitted for normal HTTP/WS requests
	Stream                          bool                 `json:"stream"`
	PreviousResponseID              string               `json:"previous_response_id,omitempty"`
	ServiceTier                     string               `json:"service_tier,omitempty"`
	SessionID                       string               `json:"-"`
	FileUploadPolicy                *FileUploadPolicy    `json:"-"`
}

ResponsesRequest follows the Open Responses spec

type ResponsesTool added in v0.0.34 

type ResponsesTool struct {
	Type        string                 `json:"type"`
	Name        string                 `json:"name"`
	Description string                 `json:"description,omitempty"`
	Parameters  map[string]interface{} `json:"parameters"`
	Strict      bool                   `json:"strict,omitempty"`
}

ResponsesTool represents a tool definition in Open Responses format

type ResponsesWebSearchTool added in v0.0.34 

type ResponsesWebSearchTool struct {
	Type string `json:"type"` // "web_search_preview"
}

ResponsesWebSearchTool represents the web search tool for OpenAI

type RetryConfig added in v0.0.12 

type RetryConfig struct {
	// MaxAttempts limits total attempts. A value of 0 means there is no
	// attempt-count limit and retries are governed by MaxElapsedTime.
	MaxAttempts int
	// MaxElapsedTime limits the retry window from the first attempt. A value of
	// 0 disables the elapsed-time budget (useful for tests/custom fixed attempts).
	MaxElapsedTime time.Duration
	BaseBackoff    time.Duration
	MaxBackoff     time.Duration
}

RetryConfig configures retry behavior.

func DefaultRetryConfig added in v0.0.12 

func DefaultRetryConfig() RetryConfig

DefaultRetryConfig returns sensible defaults for transient provider retries.

type RetryProvider added in v0.0.12 

type RetryProvider struct {
	// contains filtered or unexported fields
}

RetryProvider wraps a provider with automatic retry on transient errors.

func (*RetryProvider) Capabilities added in v0.0.12 

func (r *RetryProvider) Capabilities() Capabilities

func (*RetryProvider) CleanupMCP added in v0.0.52 

func (r *RetryProvider) CleanupMCP()

CleanupMCP forwards to the inner provider if it implements ProviderCleaner. This ensures providers like ClaudeBinProvider get cleaned up properly even when wrapped with retry logic.

func (*RetryProvider) CleanupTurn added in v0.0.168 

func (r *RetryProvider) CleanupTurn()

CleanupTurn forwards to the inner provider if it implements ProviderTurnCleaner so per-turn cleanup survives retry wrapping.

func (*RetryProvider) Credential added in v0.0.12 

func (r *RetryProvider) Credential() string

func (*RetryProvider) ListModels added in v0.0.169 

func (r *RetryProvider) ListModels(ctx context.Context) ([]ModelInfo, error)

ListModels forwards to the inner provider if it implements model listing and applies the same retry policy as Stream for transient HTTP/provider failures. Without this forwarder, callers that type-assert on a ListModels interface would silently miss it on any retry-wrapped provider — and every provider built via NewProvider/NewProviderByName is retry-wrapped.

func (*RetryProvider) Name added in v0.0.12 

func (r *RetryProvider) Name() string

func (*RetryProvider) ResetConversation added in v0.0.146 

func (r *RetryProvider) ResetConversation()

ResetConversation forwards to the inner provider if it implements ResetConversation. This preserves provider-side conversation reset behavior when providers are wrapped with retry logic.

func (*RetryProvider) SetToolExecutor added in v0.0.49 

func (r *RetryProvider) SetToolExecutor(executor func(ctx context.Context, name string, args json.RawMessage) (ToolOutput, error))

SetToolExecutor forwards to the inner provider if it implements ToolExecutorSetter. This ensures providers like ClaudeBinProvider can receive their tool executor even when wrapped with retry logic.

func (*RetryProvider) Stream added in v0.0.12 

func (r *RetryProvider) Stream(ctx context.Context, req Request) (Stream, error)

type Role added in v0.0.10 

type Role string

Role identifies a message role. 

const (
	RoleSystem    Role = "system"
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
	RoleTool      Role = "tool"
	// RoleEvent is a durable UI/session timeline marker. It is never sent to
	// providers as conversation context.
	RoleEvent Role = "event"
	// RoleDeveloper is a privileged instruction role injected by the platform layer.
	// OpenAI/Responses API providers send it as a "developer" role message; Anthropic
	// providers have no native equivalent, so the text is prepended into the next user turn
	// wrapped in <developer>…</developer> tags.
	RoleDeveloper Role = "developer"
)

type SambaNovaProvider added in v0.0.239 

type SambaNovaProvider struct {
	*OpenAICompatProvider
}

func NewSambaNovaProvider added in v0.0.239 

func NewSambaNovaProvider(apiKey, model string) *SambaNovaProvider

func (*SambaNovaProvider) Capabilities added in v0.0.239 

func (p *SambaNovaProvider) Capabilities() Capabilities

func (*SambaNovaProvider) ListModels added in v0.0.239 

func (p *SambaNovaProvider) ListModels(ctx context.Context) ([]ModelInfo, error)

type Stream added in v0.0.10 

type Stream interface {
	Recv() (Event, error)
	Close() error
}

Stream yields events until io.EOF.

func WrapDebugStream added in v0.0.10 

func WrapDebugStream(enabled bool, inner Stream) Stream

type StreamIncompleteError added in v0.0.229 

type StreamIncompleteError struct {
	Transport string
	Terminal  string
	Err       error
}

StreamIncompleteError reports a streaming response that ended before the protocol terminal marker arrived. This must be treated as a failed model response, not a successful completion with truncated output.

func (*StreamIncompleteError) Error added in v0.0.229 

func (e *StreamIncompleteError) Error() string

func (*StreamIncompleteError) Unwrap added in v0.0.229 

func (e *StreamIncompleteError) Unwrap() error

type Tool added in v0.0.10 

type Tool interface {
	Spec() ToolSpec
	Execute(ctx context.Context, args json.RawMessage) (ToolOutput, error)
	// Preview returns a human-readable description of what the tool will do,
	// shown to the user before execution starts (e.g., "Generating image: a cat").
	// Returns empty string if no preview is available.
	Preview(args json.RawMessage) string
}

Tool describes a callable external tool.

type ToolCall added in v0.0.10 

type ToolCall struct {
	ID         string
	Name       string
	Arguments  json.RawMessage
	ToolInfo   string `json:",omitempty"` // Persisted display text for TUI/history (already formatted, e.g. "(main.go)")
	ThoughtSig []byte // Gemini 3 thought signature (must be passed back in result)
}

ToolCall is a model-requested tool invocation.

type ToolChoice added in v0.0.10 

type ToolChoice struct {
	Mode ToolChoiceMode
	Name string
}

ToolChoice configures which tool the model should call.

type ToolChoiceMode added in v0.0.10 

type ToolChoiceMode string

ToolChoiceMode controls tool selection behavior. 

const (
	ToolChoiceAuto     ToolChoiceMode = "auto"
	ToolChoiceNone     ToolChoiceMode = "none"
	ToolChoiceRequired ToolChoiceMode = "required"
	ToolChoiceName     ToolChoiceMode = "name"
)

type ToolContentPart added in v0.0.82 

type ToolContentPart struct {
	Type      ToolContentPartType `json:"type"`
	Text      string              `json:"text,omitempty"`
	ImageData *ToolImageData      `json:"image_data,omitempty"`
}

ToolContentPart represents one structured piece of tool result content. Use a sequence like [text, image_data, text] to preserve multimodal ordering.

type ToolContentPartType added in v0.0.82 

type ToolContentPartType string

ToolContentPartType identifies a structured tool result content item. 

const (
	ToolContentPartText      ToolContentPartType = "text"
	ToolContentPartImageData ToolContentPartType = "image_data"
)

type ToolExecutionResponse added in v0.0.49 

type ToolExecutionResponse struct {
	Result ToolOutput
	Err    error
}

ToolExecutionResponse holds the result of a synchronous tool execution. Used by claude_bin provider to receive results from the engine.

type ToolExecutorSetter added in v0.0.49 

type ToolExecutorSetter interface {
	SetToolExecutor(func(ctx context.Context, name string, args json.RawMessage) (ToolOutput, error))
}

ToolExecutorSetter is an optional interface for providers that need tool execution wired up externally (e.g., claude-bin with HTTP MCP).

type ToolFileData added in v0.0.257 

type ToolFileData struct {
	MediaType string `json:"media_type,omitempty"`
	Base64    string `json:"base64,omitempty"`
	Filename  string `json:"filename,omitempty"`
	SizeBytes int64  `json:"size_bytes,omitempty"`
}

ToolFileData represents base64-encoded file data in user input.

type ToolImageData added in v0.0.82 

type ToolImageData struct {
	MediaType string `json:"media_type,omitempty"`
	Base64    string `json:"base64,omitempty"`
	Detail    string `json:"detail,omitempty"`
}

ToolImageData represents base64-encoded image data in tool output.

type ToolOutput added in v0.0.68 

type ToolOutput struct {
	Content      string            // Text result (sent to LLM)
	ContentParts []ToolContentPart `json:"content_parts,omitempty"` // Structured multimodal tool content for provider formatting
	Diffs        []DiffData        // Structured diff data (for UI rendering)
	Images       []string          // Image paths (for UI rendering)
	FileChanges  []FileChange      `json:"file_changes,omitempty"` // Recorded file changes (when file tracking is enabled)
	TimedOut     bool              // Set by tools that support timeouts (e.g. shell); drives ToolSuccess=false without content sniffing
	IsError      bool              // Set when a tool returned an unsuccessful result (e.g. shell exit code != 0); copied to ToolResult.IsError for UI/history and provider error metadata
}

ToolOutput is the structured return type from Tool.Execute(). Most tools only populate Content. Edit/image tools also populate Diffs/Images.

func TextOutput added in v0.0.68 

func TextOutput(s string) ToolOutput

TextOutput creates a ToolOutput with only text content.

type ToolRegistry added in v0.0.10 

type ToolRegistry struct {
	// contains filtered or unexported fields
}

ToolRegistry stores tools by name for execution.

func NewToolRegistry added in v0.0.10 

func NewToolRegistry() *ToolRegistry

func (*ToolRegistry) AllSpecs added in v0.0.15 

func (r *ToolRegistry) AllSpecs() []ToolSpec

AllSpecs returns the specs for all registered tools in deterministic name order.

func (*ToolRegistry) Get added in v0.0.10 

func (r *ToolRegistry) Get(name string) (Tool, bool)

func (*ToolRegistry) IsFinishingTool added in v0.0.49 

func (r *ToolRegistry) IsFinishingTool(name string) bool

IsFinishingTool returns true if the named tool is a finishing tool.

func (*ToolRegistry) Register added in v0.0.10 

func (r *ToolRegistry) Register(tool Tool)

func (*ToolRegistry) Unregister added in v0.0.15 

func (r *ToolRegistry) Unregister(name string)

type ToolResult added in v0.0.10 

type ToolResult struct {
	ID           string
	Name         string
	Content      string            // Clean text sent to LLM
	ContentParts []ToolContentPart `json:"content_parts,omitempty"` // Structured multimodal tool content
	Display      string            // Deprecated: old marker-based output. Kept only for deserializing pre-structured sessions. TODO: remove once no saved sessions use Display-based diff markers.
	Diffs        []DiffData        `json:"diffs,omitempty"`  // Structured diff data
	Images       []string          `json:"images,omitempty"` // Image paths
	IsError      bool              // True if this result represents a tool execution error
	ThoughtSig   []byte            // Gemini 3 thought signature (passed through from ToolCall)
}

ToolResult is the output from executing a tool call.

type ToolSpec added in v0.0.10 

type ToolSpec struct {
	Name        string
	Description string
	Schema      map[string]interface{}
	// Strict opts this tool into OpenAI strict function-parameter schemas.
	// Default is false to match Codex/OpenAI flagship behavior for broad MCP
	// schemas. When enabled, all object properties are required and free-form maps
	// are converted to strict-compatible key/value arrays.
	Strict bool
}

ToolSpec describes a callable tool.

Tool specs are treated as immutable after registration. In particular, Schema maps returned from registries may be shared across calls; provider code that needs to rewrite a schema must copy it first.

func EditToolSpec added in v0.0.10 

func EditToolSpec() ToolSpec

EditToolSpec returns the tool spec for the edit tool.

func ReadURLToolSpec added in v0.0.11 

func ReadURLToolSpec() ToolSpec

ReadURLToolSpec returns the tool spec for reading web pages.

func SuggestCommandsToolSpec added in v0.0.10 

func SuggestCommandsToolSpec(numSuggestions int) ToolSpec

SuggestCommandsToolSpec returns the tool spec for command suggestions.

func ToolSpecsForRequest added in v0.0.86 

func ToolSpecsForRequest(registry *ToolRegistry, searchEnabled bool) []ToolSpec

ToolSpecsForRequest returns the tool specs to include in a request, filtering out search tools when searchEnabled is false (the engine adds them automatically when req.Search is true). Returns nil if no tools are registered.

func UnifiedDiffToolSpec added in v0.0.10 

func UnifiedDiffToolSpec() ToolSpec

UnifiedDiffToolSpec returns the tool spec for unified diff edits.

func WebSearchToolSpec added in v0.0.10 

func WebSearchToolSpec() ToolSpec

WebSearchToolSpec returns the tool spec for external web search.

type TranscribeOptions added in v0.0.97 

type TranscribeOptions struct {
	APIKey     string
	Endpoint   string // full URL, e.g. "http://localhost:8080/inference" or "https://api.mistral.ai/v1/audio/transcriptions"
	Model      string // optional, overrides default model name sent to API
	Language   string // optional, e.g. "en"
	Provider   string // optional request dialect: "openai" (default), "venice", or "elevenlabs"
	Timestamps bool   // Request timestamp metadata in JSON responses where supported
}

type TurnCompletedCallback added in v0.0.41 

type TurnCompletedCallback func(ctx context.Context, turnIndex int, messages []Message, metrics TurnMetrics) error

TurnCompletedCallback is called after each turn completes with the messages generated during that turn and metrics about the turn. turnIndex is 0-based. If ResponseCompletedCallback successfully handled the assistant message for this turn, messages contains only the later turn messages (usually tool results). Otherwise, messages contains the complete generated turn, including assistant message(s) and tool result(s). Recovery paths that bypass ResponseCompletedCallback also deliver the assistant message here.

type TurnMetrics added in v0.0.41 

type TurnMetrics struct {
	InputTokens       int // Non-cached, non-cache-write input tokens this turn
	OutputTokens      int // Tokens generated as output this turn
	CachedInputTokens int // Input tokens served from cache (cache read) this turn
	CacheWriteTokens  int // Input tokens written to cache (cache creation) this turn
	ToolCalls         int // Number of tools executed this turn
}

TurnMetrics contains metrics collected during a turn.

type URLFetcher added in v0.0.247 

type URLFetcher interface {
	FetchURL(ctx context.Context, url string) (string, error)
}

URLFetcher fetches normalized, public URLs for ReadURLTool.

type Usage added in v0.0.10 

type Usage struct {
	InputTokens       int // Non-cached input tokens (newly processed this turn)
	OutputTokens      int
	CachedInputTokens int // Tokens read from cache (additive with InputTokens, NOT a subset)
	CacheWriteTokens  int // Tokens written to cache (cache_creation_input_tokens)

	// ProviderRawInputTokens is the provider-reported input/prompt token count
	// before term-llm normalization. For OpenAI-family APIs this includes cached
	// tokens; for providers that already report non-cached input separately this
	// may be zero or equal to InputTokens.
	ProviderRawInputTokens int
	// ProviderTotalTokens is the provider-reported total_tokens when available.
	// For OpenAI Responses/Chat Completions this is input_tokens + output_tokens.
	ProviderTotalTokens int
	// ReasoningTokens is provider-reported reasoning output tokens when available.
	ReasoningTokens int
}

Usage captures token usage if available.

InputTokens is the count of non-cached input tokens — i.e. the portion that was freshly processed. CachedInputTokens is the portion served from cache. The two are always additive: InputTokens + CachedInputTokens = total prompt/context size.

All providers must normalise to this convention:

  • Anthropic already reports input_tokens (non-cached) + cache_read_input_tokens separately.
  • OpenAI/ChatGPT reports prompt_tokens (inclusive of cached); providers must subtract the cached portion before populating InputTokens.

func (*Usage) Add added in v0.0.234 

func (u *Usage) Add(other Usage)

Add accumulates another usage value into u.

func (Usage) BillableCountersZero added in v0.0.234 

func (u Usage) BillableCountersZero() bool

BillableCountersZero reports whether the normalized token counters term-llm persists for usage/cost displays are all zero.

func (Usage) IsZero added in v0.0.234 

func (u Usage) IsZero() bool

IsZero reports whether no token usage was reported.

type UserFacingProviderError added in v0.0.190 

type UserFacingProviderError struct {
	Summary string
	Detail  string
	Cause   error
}

func (*UserFacingProviderError) DebugFields added in v0.0.190 

func (e *UserFacingProviderError) DebugFields() map[string]any

func (*UserFacingProviderError) Error added in v0.0.190 

func (e *UserFacingProviderError) Error() string

func (*UserFacingProviderError) Unwrap added in v0.0.190 

func (e *UserFacingProviderError) Unwrap() error

type VLLMProvider added in v0.0.256 

type VLLMProvider struct {
	*OpenAICompatProvider
}

VLLMProvider implements Provider for vLLM's OpenAI-compatible chat API plus vLLM/Qwen-specific thinking controls.

func NewVLLMProvider added in v0.0.256 

func NewVLLMProvider(baseURL, apiKey, model, name string) *VLLMProvider

func NewVLLMProviderFull added in v0.0.256 

func NewVLLMProviderFull(baseURL, chatURL, apiKey, model, name string) *VLLMProvider

type VeniceProvider added in v0.0.98 

type VeniceProvider struct {
	*OpenAICompatProvider
}

func NewVeniceProvider added in v0.0.98 

func NewVeniceProvider(apiKey, model string) *VeniceProvider

func (*VeniceProvider) Capabilities added in v0.0.118 

func (p *VeniceProvider) Capabilities() Capabilities

func (*VeniceProvider) ListModels added in v0.0.141 

func (p *VeniceProvider) ListModels(ctx context.Context) ([]ModelInfo, error)

func (*VeniceProvider) Stream added in v0.0.98 

func (p *VeniceProvider) Stream(ctx context.Context, req Request) (Stream, error)

type WebSearchTool added in v0.0.10 

type WebSearchTool struct {
	// contains filtered or unexported fields
}

WebSearchTool executes searches through a Searcher.

func NewWebSearchTool added in v0.0.10 

func NewWebSearchTool(searcher search.Searcher) *WebSearchTool

func (*WebSearchTool) Execute added in v0.0.10 

func (t *WebSearchTool) Execute(ctx context.Context, args json.RawMessage) (ToolOutput, error)

func (*WebSearchTool) Preview added in v0.0.25 

func (t *WebSearchTool) Preview(args json.RawMessage) string

func (*WebSearchTool) Spec added in v0.0.10 

func (t *WebSearchTool) Spec() ToolSpec

type XAIProvider added in v0.0.31 

type XAIProvider struct {
	// contains filtered or unexported fields
}

XAIProvider implements Provider for the xAI (Grok) API. Uses OpenAI-compatible chat completions for tool calling, and the Responses API for native web/X search.

func NewXAIProvider added in v0.0.31 

func NewXAIProvider(apiKey, model string) *XAIProvider

NewXAIProvider creates a new xAI provider.

func (*XAIProvider) Capabilities added in v0.0.31 

func (p *XAIProvider) Capabilities() Capabilities

func (*XAIProvider) Credential added in v0.0.31 

func (p *XAIProvider) Credential() string

func (*XAIProvider) ListModels added in v0.0.31 

func (p *XAIProvider) ListModels(ctx context.Context) ([]ModelInfo, error)

ListModels returns available models from the xAI API.

func (*XAIProvider) Name added in v0.0.31 

func (p *XAIProvider) Name() string

func (*XAIProvider) Stream added in v0.0.31 

func (p *XAIProvider) Stream(ctx context.Context, req Request) (Stream, error)

type ZenProvider added in v0.0.2 

type ZenProvider struct {
	*OpenAICompatProvider
}

ZenProvider wraps OpenAICompatProvider with models.dev pricing data.

func NewZenProvider added in v0.0.2 

func NewZenProvider(apiKey, model string) *ZenProvider

NewZenProvider creates a ZenProvider preconfigured for OpenCode Zen. Zen provides free access to models like GLM 4.7 via opencode.ai. API key is optional: empty for free tier, or set ZEN_API_KEY for paid models.

func (*ZenProvider) ListModels added in v0.0.25 

func (p *ZenProvider) ListModels(ctx context.Context) ([]ModelInfo, error)

ListModels returns available models with pricing from models.dev.

func (*ZenProvider) Stream added in v0.0.248 

func (p *ZenProvider) Stream(ctx context.Context, req Request) (Stream, error)

Stream normalizes Zen-specific model aliases before delegating to the OpenAI-compatible implementation.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.