llm

package
v0.0.166 Latest Latest
Warning

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

 Go to latest Published: Apr 17, 2026 License: MIT Imports: 48 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 (
	SuggestCommandsToolName = "suggest_commands"
	EditToolName            = "edit"
	UnifiedDiffToolName     = "unified_diff"
	WebSearchToolName       = "web_search"
)
View Source 
const EditToolDescription = "" /* 215-byte string literal not displayed */

EditToolDescription is the description for the edit tool.

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 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-1.5", "gpt-image-1-mini"},
	"xai":        {"grok-2-image", "grok-2-image-1212"},
	"venice":     {"nano-banana-pro", "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", "venice-sd35", "hidream", "chroma", "z-image-turbo", "lustify-sdxl", "lustify-v7", "wai-Illustrious", "bg-remover", "qwen-edit", "nano-banana-pro-edit", "flux-2-max-edit", "gpt-image-1-5-edit", "seedream-v4-edit", "seedream-v5-lite-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",
	"bedrock":    "claude-haiku-4-5",
	"venice":     "llama-3.2-3b",
	"openrouter": "anthropic/claude-haiku-4-5",
	"claude-bin": "haiku",
}

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-opus-4-7", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-opus-4-7-thinking", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-opus-4-7-1m", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-opus-4-7-1m-thinking", InputLimit: 980_000, OutputLimit: 64_000},

		{ID: "claude-sonnet-4-6", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4-6-thinking", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4-6-1m", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4-6-1m-thinking", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-opus-4-6", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-opus-4-6-thinking", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-opus-4-6-1m", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-opus-4-6-1m-thinking", InputLimit: 980_000, OutputLimit: 64_000},
		{ID: "claude-haiku-4-5", InputLimit: 180_000, OutputLimit: 64_000},
		{ID: "claude-haiku-4-5-thinking", InputLimit: 180_000, OutputLimit: 64_000},
	},
	"openai": {
		{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.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},
	},
	"copilot": {

		{ID: "gpt-4.1", InputLimit: 48_000, OutputLimit: 32_768},

		{ID: "gpt-5.3-codex", InputLimit: 272_000, OutputLimit: 128_000},
		{ID: "gpt-5.2-codex", InputLimit: 144_000, OutputLimit: 128_000},
		{ID: "gpt-5.1-codex", InputLimit: 64_000, OutputLimit: 128_000},
		{ID: "gpt-5.1-codex-max", InputLimit: 64_000, OutputLimit: 128_000},
		{ID: "gpt-5.1-codex-mini", InputLimit: 64_000, OutputLimit: 128_000},

		{ID: "gpt-5.4", InputLimit: 922_000, OutputLimit: 128_000},
		{ID: "gpt-5.2", InputLimit: 64_000, OutputLimit: 128_000},
		{ID: "gpt-5.1", InputLimit: 64_000, OutputLimit: 128_000},
		{ID: "gpt-5-mini", InputLimit: 64_000, OutputLimit: 128_000},

		{ID: "claude-opus-4.6-thinking", InputLimit: 64_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4.6-thinking", InputLimit: 112_000, OutputLimit: 64_000},
		{ID: "claude-opus-4.6", InputLimit: 64_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4.6", InputLimit: 112_000, OutputLimit: 64_000},
		{ID: "claude-opus-4.5", InputLimit: 96_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4.5", InputLimit: 96_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4", InputLimit: 112_000, OutputLimit: 64_000},
		{ID: "claude-haiku-4.5", InputLimit: 96_000, OutputLimit: 64_000},

		{ID: "gemini-3-pro", InputLimit: 64_000, OutputLimit: 65_536},
		{ID: "gemini-3-flash", InputLimit: 64_000, OutputLimit: 65_536},

		{ID: "grok-code-fast-1", InputLimit: 64_000, OutputLimit: 16_384},
		{ID: "raptor-mini"},
	},
	"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"},
		{ID: "opus-low"},
		{ID: "opus-medium"},
		{ID: "opus-high"},
		{ID: "opus-xhigh"},
		{ID: "opus-max"},
		{ID: "sonnet"},
		{ID: "sonnet-low"},
		{ID: "sonnet-medium"},
		{ID: "sonnet-high"},
		{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},
	},
	"bedrock": {

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

		{ID: "venice-uncensored", InputLimit: 32_000, OutputLimit: 8_192},
		{ID: "venice-uncensored-role-play", InputLimit: 128_000, OutputLimit: 4_096},
		{ID: "olafangensan-glm-4.7-flash-heretic", InputLimit: 200_000, OutputLimit: 24_000},
		{ID: "zai-org-glm-4.7-flash", InputLimit: 128_000, OutputLimit: 16_384},
		{ID: "zai-org-glm-5", InputLimit: 198_000, OutputLimit: 32_000},
		{ID: "zai-org-glm-4.6", InputLimit: 198_000, OutputLimit: 16_384},
		{ID: "zai-org-glm-4.7", InputLimit: 198_000, OutputLimit: 16_384},
		{ID: "mistral-small-3-2-24b-instruct", InputLimit: 256_000, OutputLimit: 16_384},
		{ID: "qwen3-235b-a22b-thinking-2507", InputLimit: 128_000, OutputLimit: 16_384},
		{ID: "qwen3-235b-a22b-instruct-2507", InputLimit: 128_000, OutputLimit: 16_384},
		{ID: "qwen3-next-80b", InputLimit: 256_000, OutputLimit: 16_384},
		{ID: "qwen3-coder-480b-a35b-instruct", InputLimit: 256_000, OutputLimit: 65_536},
		{ID: "qwen3-coder-480b-a35b-instruct-turbo", InputLimit: 256_000, OutputLimit: 65_536},
		{ID: "qwen3-5-9b", InputLimit: 256_000, OutputLimit: 32_768},
		{ID: "qwen3-5-35b-a3b", InputLimit: 256_000, OutputLimit: 65_536},
		{ID: "hermes-3-llama-3.1-405b", InputLimit: 128_000, OutputLimit: 16_384},
		{ID: "google-gemma-3-27b-it", InputLimit: 198_000, OutputLimit: 16_384},
		{ID: "google.gemma-4-26b-a4b-it", InputLimit: 256_000, OutputLimit: 12_288},
		{ID: "google.gemma-4-31b-it", InputLimit: 256_000, OutputLimit: 12_288},
		{ID: "grok-41-fast", InputLimit: 1_000_000, OutputLimit: 30_000},
		{ID: "grok-4-20-beta", InputLimit: 2_000_000, OutputLimit: 128_000},
		{ID: "grok-4-20-multi-agent-beta", InputLimit: 2_000_000, OutputLimit: 128_000},
		{ID: "gemini-3-1-pro-preview", InputLimit: 1_000_000, OutputLimit: 32_768},
		{ID: "gemini-3-flash-preview", InputLimit: 256_000, OutputLimit: 65_536},
		{ID: "claude-opus-4-6", InputLimit: 1_000_000, OutputLimit: 128_000},
		{ID: "claude-opus-4-5", InputLimit: 198_000, OutputLimit: 32_768},
		{ID: "claude-sonnet-4-6", InputLimit: 1_000_000, OutputLimit: 64_000},
		{ID: "claude-sonnet-4-5", InputLimit: 198_000, OutputLimit: 64_000},
		{ID: "openai-gpt-oss-120b", InputLimit: 128_000, OutputLimit: 16_384},
		{ID: "openai-gpt-52", InputLimit: 256_000, OutputLimit: 65_536},
		{ID: "openai-gpt-52-codex", InputLimit: 256_000, OutputLimit: 65_536},
		{ID: "openai-gpt-53-codex", InputLimit: 400_000, OutputLimit: 128_000},
		{ID: "openai-gpt-54", InputLimit: 1_000_000, OutputLimit: 131_072},
		{ID: "openai-gpt-54-mini", InputLimit: 400_000, OutputLimit: 128_000},
		{ID: "openai-gpt-54-pro", InputLimit: 1_000_000, OutputLimit: 128_000},
		{ID: "openai-gpt-4o-2024-11-20", InputLimit: 128_000, OutputLimit: 16_384},
		{ID: "openai-gpt-4o-mini-2024-07-18", InputLimit: 128_000, OutputLimit: 16_384},
		{ID: "kimi-k2-thinking", InputLimit: 256_000, OutputLimit: 65_536},
		{ID: "arcee-trinity-large-thinking", InputLimit: 256_000, OutputLimit: 65_536},
		{ID: "kimi-k2-5", InputLimit: 256_000, OutputLimit: 65_536},
		{ID: "deepseek-v3.2", InputLimit: 160_000, OutputLimit: 32_768},
		{ID: "aion-labs.aion-2-0", InputLimit: 128_000, OutputLimit: 32_768},
		{ID: "llama-3.2-3b", InputLimit: 128_000, OutputLimit: 4_096},
		{ID: "llama-3.3-70b", InputLimit: 128_000, OutputLimit: 4_096},
		{ID: "minimax-m21", InputLimit: 198_000, OutputLimit: 32_768},
		{ID: "minimax-m25", InputLimit: 198_000, OutputLimit: 32_768},
		{ID: "minimax-m27", InputLimit: 198_000, OutputLimit: 32_768},
		{ID: "grok-code-fast-1", InputLimit: 256_000, OutputLimit: 10_000},
		{ID: "qwen3-vl-235b-a22b", InputLimit: 256_000, OutputLimit: 16_384},
		{ID: "nvidia-nemotron-3-nano-30b-a3b", InputLimit: 128_000, OutputLimit: 16_384},
	},
}

ProviderModels contains the curated list of common models per LLM provider type. This is the single source of truth for model names AND their token limits. When adding a model, always include InputLimit/OutputLimit if known.

Functions

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 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 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 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 effort suffixes for a model, or nil if none. All GPT-5 family models are reasoning-capable and support effort levels. Handles both direct model names ("gpt-5.4") and vendor-prefixed names ("openai/gpt-5.4").

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 effort variants after each base model. Used for tab-completion where all variants are needed. Models that already end with a known effort suffix are not expanded again.

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 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 GetCachedOpenRouterModels added in v0.0.24 

func GetCachedOpenRouterModels(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. Providers like GitHub Copilot impose their own limits that differ from the model's canonical input 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. Falls back to canonical numbers if no provider-specific data exists.

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 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 ProviderModelIDs added in v0.0.140 

func ProviderModelIDs(provider string) []string

ProviderModelIDs returns just the model ID strings for a provider. This only checks the built-in ProviderModels map by exact key. For callers that might receive a custom alias name, use ResolveProviderModelIDs.

func RefreshOpenRouterCacheSync added in v0.0.24 

func RefreshOpenRouterCacheSync(apiKey string, 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 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 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)

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 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 (*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) 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 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.

func (*ClaudeBinProvider) Credential added in v0.0.21 

func (p *ClaudeBinProvider) Credential() string

func (*ClaudeBinProvider) Name added in v0.0.21 

func (p *ClaudeBinProvider) Name() string

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 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).

type CompactionConfig added in v0.0.80 

type CompactionConfig struct {
	ThresholdRatio     float64 // Fraction of context window to trigger (default 0.80)
	MaxToolResultChars int     // Max chars per tool result when recording
	SummaryTokenBudget int     // Max output tokens for the compaction summary
	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
}

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 summary of the conversation history and returns a compacted message list: [system] + [summary as user] + [recent user messages].

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.

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 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) GetUsage added in v0.0.34 

func (p *CopilotProvider) GetUsage(ctx context.Context) (*CopilotUsage, error)

GetUsage fetches the current Copilot usage and quota information. This uses GitHub's internal API which requires the VS Code OAuth client ID.

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 CopilotQuota added in v0.0.34 

type CopilotQuota struct {
	Entitlement      int     `json:"entitlement"`
	Used             int     `json:"used"`
	Remaining        int     `json:"remaining"`
	PercentRemaining float64 `json:"percent_remaining"`
	Unlimited        bool    `json:"unlimited"`
}

CopilotQuota represents quota information for a specific feature

type CopilotUsage added in v0.0.34 

type CopilotUsage struct {
	Plan        string        `json:"plan"`
	ResetDate   time.Time     `json:"reset_date"`
	PremiumChat *CopilotQuota `json:"premium_chat,omitempty"`
	Chat        *CopilotQuota `json:"chat,omitempty"`
	Completions *CopilotQuota `json:"completions,omitempty"`
}

CopilotUsage represents the usage data from GitHub Copilot

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
}

DiffData represents structured diff information from edit 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
}

Engine orchestrates provider calls and external tool execution.

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) ClearAllowedTools added in v0.0.37 

func (e *Engine) ClearAllowedTools()

ClearAllowedTools removes the tool filter, allowing all registered tools.

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. Skips setup if the provider manages its own context (e.g., claude-bin). 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 the pending interjection text, or "" if none. Non-blocking. Public so the TUI layer can recover a pending interjection when the stream completes without tool calls (the "between turns" injection point was never reached). The recovered text can be placed back in the textarea.

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 user message to be inserted after the current turn's tool results, right before the next LLM turn begins. Non-blocking: if an interjection is already pending, the new one replaces it (only the latest interjection is kept). Safe to call from any goroutine (e.g., the TUI thread).

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) 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) 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) 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
	ReasoningItemID           string // For EventReasoningDelta: reasoning item ID
	ReasoningEncryptedContent string // For EventReasoningDelta: encrypted reasoning content
	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
	ToolImages                []string        // For EventToolExecEnd: image paths from image tools
	Use                       *Usage
	Err                       error
	// Retry fields (for EventRetry)
	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
}

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
	EventInterjection   EventType = "interjection" // User interjected a message mid-stream
)

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 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 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 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 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
}

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)
}

ModelInfo represents a model available from a provider.

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) 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 (*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 Part added in v0.0.10 

type Part struct {
	Type                      PartType
	Text                      string
	ReasoningContent          string         // Reasoning summary text (or thinking content for OpenRouter)
	ReasoningItemID           string         // Responses API reasoning item ID for replay
	ReasoningEncryptedContent string         // Responses API encrypted reasoning content for replay
	ImageData                 *ToolImageData // User-supplied image (base64-encoded)
	ImagePath                 string         // Local filesystem path to the image (when available, e.g. Telegram uploads)
	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"
	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).

type RateLimitError added in v0.0.33 

type RateLimitError struct {
	Message       string
	RetryAfter    time.Duration
	PlanType      string
	PrimaryUsed   int
	SecondaryUsed 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) IsLongWait added in v0.0.33 

func (e *RateLimitError) IsLongWait() bool

IsLongWait returns true if the retry wait is too long for automatic retry.

type ReadURLTool added in v0.0.11 

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

ReadURLTool fetches web pages using Jina AI Reader.

func NewReadURLTool added in v0.0.11 

func NewReadURLTool() *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 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
	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)
	// 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
}

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

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)
}

ResponsesContentPart represents a content part (text or image)

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 BuildResponsesInput added in v0.0.34 

func BuildResponsesInput(messages []Message) []ResponsesInputItem

BuildResponsesInput converts []Message to Open Responses input format

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).

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"`
	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"`
	Stream             bool                 `json:"stream"`
	PreviousResponseID string               `json:"previous_response_id,omitempty"`
	SessionID          string               `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 int
	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 rate limit 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) Credential added in v0.0.12 

func (r *RetryProvider) Credential() string

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"
	// 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 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 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 ToolImageData added in v0.0.82 

type ToolImageData struct {
	MediaType string `json:"media_type,omitempty"`
	Base64    string `json:"base64,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)
	TimedOut     bool              // Set by tools that support timeouts (e.g. shell); drives ToolSuccess=false without content sniffing
}

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{}
	// NoStrict disables OpenAI strict mode for this tool. Use when the schema
	// contains free-form objects (additionalProperties: true) or union types
	// that are incompatible with OpenAI's strict structured-output requirements.
	NoStrict bool
}

ToolSpec describes a callable tool.

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"
}

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, messages contains assistant message(s) and tool result(s).

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 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)
}

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.

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.

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.