llm

package
v0.9.21 Latest Latest
Warning

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

 Go to latest Published: Sep 3, 2026 License: MIT Imports: 63 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 (
	ToolActivityCompleted = "completed"
	ToolActivityFailed    = "failed"
)
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 RunErrorEventType = "run_error"
View Source 
const ToolDiscoverySearchTurnReserve = 2

ToolDiscoverySearchTurnReserve is the minimum number of provider turns needed after discovery: one to call an activated tool and one answer-only final turn.

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 = config.DefaultProviderFastModels()

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{
	"debug": {

		{ID: "compaction", InputLimit: 19_000, OutputLimit: 1_000},
	},
	"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.6-sol", InputLimit: 922_000, OutputLimit: 128_000, ReasoningEfforts: gpt56OpenAIEffortVariants},
		{ID: "gpt-5.6-terra", InputLimit: 922_000, OutputLimit: 128_000, ReasoningEfforts: gpt56OpenAIEffortVariants},
		{ID: "gpt-5.6-luna", InputLimit: 922_000, OutputLimit: 128_000, ReasoningEfforts: gpt56OpenAIEffortVariants},
		{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.6-sol", InputLimit: 372_000, OutputLimit: 128_000, ReasoningEfforts: gpt56ChatGPTEffortVariants},
		{ID: "gpt-5.6-terra", InputLimit: 372_000, OutputLimit: 128_000, ReasoningEfforts: gpt56ChatGPTEffortVariants},
		{ID: "gpt-5.6-luna", InputLimit: 372_000, OutputLimit: 128_000, ReasoningEfforts: gpt56ChatGPTEffortVariants},
		{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},
	},
	"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},
	},

	"opencode-go": {},
	"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"},
	},
	"grok": {

		{ID: "grok-4.6", ReasoningEfforts: grok46ReasoningEfforts},
	},
	"grok-bin": {
		{ID: "grok-4.6", ReasoningEfforts: grokBinEffortVariants},
		{ID: "grok-4.6-low"},
		{ID: "grok-4.6-medium"},
		{ID: "grok-4.6-high"},
		{ID: "grok-4.6-xhigh"},
		{ID: "grok-4.5", ReasoningEfforts: grokBinEffortVariants},
		{ID: "grok-4.5-low"},
		{ID: "grok-4.5-medium"},
		{ID: "grok-4.5-high"},
		{ID: "grok-4.5-xhigh"},
		{ID: "grok-composer-2.5-fast"},
	},
	"cursor-bin": {
		{ID: "auto-smart"},
		{ID: "grok-4.5", ReasoningEfforts: []string{"low", "medium", "high"}},
		{ID: "composer-2.5"},
		{ID: "claude-sonnet-5"},
		{ID: "gpt-5.6-sol"},
	},
	"agy-bin": {
		{ID: "gemini-3.6-flash-high"},
		{ID: "gemini-3.6-flash-medium"},
		{ID: "gemini-3.6-flash-low"},
		{ID: "gemini-3.5-flash-high"},
		{ID: "gemini-3.1-pro-high"},
		{ID: "claude-sonnet-4-6"},
		{ID: "claude-opus-4-6-thinking"},
	},
	"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": concatModelEntries(

		modelsWithLimits(30_000, 8_192,
			"qwen2.5-coder:7b", "qwen2.5-coder:14b", "qwen2.5-coder:32b",
			"qwen3:8b", "qwen3:8b-think", "qwen3:14b", "qwen3:14b-think", "qwen3:32b", "qwen3:32b-think",
		),
		modelsWithLimits(120_000, 8_192, "llama3.3:70b", "llama3.2:3b", "llama3.2:1b"),

		modelsWithLimits(30_000, 8_192, "deepseek-r1:7b", "deepseek-r1:14b", "deepseek-r1:32b"),
	),
	"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 AgyBinHasCredentials added in v0.0.370 

func AgyBinHasCredentials() bool

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 BuildResponsesToolsWithOptions added in v0.0.321 

func BuildResponsesToolsWithOptions(specs []ToolSpec, ptc ProgrammaticToolCallingOptions) []any

BuildResponsesToolsWithOptions applies PTC eligibility only to explicitly named tools and appends the hosted programmatic_tool_calling tool when enabled.

func CachedOllamaModelEffort added in v0.0.397 

func CachedOllamaModelEffort(baseURL, model string) (base, effort string, efforts []string, ok bool)

CachedOllamaModelEffort resolves a live Ollama model or one of its advertised effort variants using endpoint-specific /api/show metadata.

func CachedOllamaReasoningEfforts added in v0.0.397 

func CachedOllamaReasoningEfforts(baseURL, model string) []string

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 ConfiguredProviderReasoningEfforts added in v0.0.375 

func ConfiguredProviderReasoningEfforts(cfg *config.Config, provider string) []string

ConfiguredProviderReasoningEfforts returns the effort profiles advertised for a configured provider's selected model. Explicit models[] metadata wins over the legacy provider-wide reasoning switch.

func ContextWithApprovalTranscript added in v0.0.317 

func ContextWithApprovalTranscript(ctx context.Context, messages []Message) context.Context

ContextWithApprovalTranscript returns a new context carrying the conversation messages that should be used by policy reviewers for tool approval decisions.

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 ContextWithGuardianReviewCapture added in v0.0.404 

func ContextWithGuardianReviewCapture(ctx context.Context) (context.Context, func() []GuardianReview)

ContextWithGuardianReviewCapture installs a per-tool review collector and returns a snapshot function for the execution owner.

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 ContextWithToolRunID added in v0.0.388 

func ContextWithToolRunID(ctx context.Context, runID string) context.Context

ContextWithToolRunID binds dynamic schema activation to one engine run.

func CursorBinHasCredentials added in v0.0.353 

func CursorBinHasCredentials() bool

CursorBinHasCredentials reports whether Cursor Agent can authenticate via CURSOR_API_KEY or a local `cursor-agent login` (cli-config.json authInfo).

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 ExpandCachedOllamaReasoningVariants added in v0.0.397 

func ExpandCachedOllamaReasoningVariants(baseURL string, models []string) []string

func ExpandCachedZenReasoningVariants added in v0.0.402 

func ExpandCachedZenReasoningVariants(models []string) []string

ExpandCachedZenReasoningVariants adds the effort suffixes advertised by the live Zen catalog while preserving its model order.

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 FormatProviderUsage added in v0.0.395 

func FormatProviderUsage(report *ProviderUsage, now time.Time) string

FormatProviderUsage formats a live provider usage report using default meter options.

func FormatProviderUsageWithOptions added in v0.0.395 

func FormatProviderUsageWithOptions(report *ProviderUsage, now time.Time, opts ProviderUsageFormatOptions) string

FormatProviderUsageWithOptions formats a responsive stacked provider usage report.

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 GetCachedAgyBinModels added in v0.9.21 

func GetCachedAgyBinModels() []string

GetCachedAgyBinModels returns the last live model list fetched from the agy CLI. It never spawns agy, so it is safe for shell completion and provider pickers. Run `term-llm models --provider agy-bin` to refresh it.

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 GetCachedCursorBinModels added in v0.0.353 

func GetCachedCursorBinModels() []string

GetCachedCursorBinModels returns the last live model list fetched from Cursor Agent. It never spawns cursor-agent, so it is safe for shell completion and provider pickers. Run `term-llm models --provider cursor-bin` to refresh it.

func GetCachedGrokBinModels added in v0.0.392 

func GetCachedGrokBinModels() []string

GetCachedGrokBinModels returns the last live model list fetched from the Grok Build CLI. It never spawns grok, so it is safe for shell completion and provider pickers. Run `term-llm models --provider grok-bin` to refresh it.

func GetCachedOllamaModels added in v0.0.397 

func GetCachedOllamaModels(baseURL string) []string

GetCachedOllamaModels returns the last live model list fetched for an Ollama endpoint without performing network access. Stale entries remain usable as a completion fallback.

func GetCachedOpenCodeGoModels added in v0.0.380 

func GetCachedOpenCodeGoModels() []string

GetCachedOpenCodeGoModels returns active model IDs from the last successful merged OpenCode Go catalog refresh without performing network access.

func GetCachedOpenCodeGoModelsForAPIKey added in v0.0.392 

func GetCachedOpenCodeGoModelsForAPIKey(apiKey string) []string

GetCachedOpenCodeGoModelsForAPIKey returns active model IDs from the on-disk OpenCode Go catalog cache for the given API key. Unlike GetCachedOpenCodeGoModels, it does not require an in-memory catalog instance, so shell completion (which runs in a fresh process where no provider has been constructed) can read the cache directly.

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 GetCachedZenModels added in v0.0.402 

func GetCachedZenModels() []string

GetCachedZenModels returns model IDs from the last successful Zen catalog refresh without performing network access.

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 HasGoalSteeringPart added in v0.9.0 

func HasGoalSteeringPart(parts []Part) bool

HasGoalSteeringPart reports whether parts carry the durable active-goal marker.

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 IsConfiguredProviderEffortPrefix added in v0.0.375 

func IsConfiguredProviderEffortPrefix(cfg *config.Config, value string) bool

IsConfiguredProviderEffortPrefix reports whether completion is currently filling an effort suffix for a configured provider profile.

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 IsGoalSteeringMessage added in v0.9.0 

func IsGoalSteeringMessage(msg Message) bool

IsGoalSteeringMessage reports whether a message is a marked synthetic active-goal prompt.

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 IsLegacyGoalSteeringText added in v0.9.0 

func IsLegacyGoalSteeringText(text string) bool

IsLegacyGoalSteeringText recognizes goal prompts persisted before the durable marker existed. Callers must additionally establish that the row has no first-party client message ID, because user-authored quoted prompts are data.

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 LogoutGrok added in v0.0.404 

func LogoutGrok(ctx context.Context) (warning string, err error)

LogoutGrok best-effort revokes the refresh token and always removes the same local credential generation. A concurrent login is preserved.

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 PromptForGrokAuth added in v0.0.404 

func PromptForGrokAuth() (*credentials.GrokCredentials, error)

func ProviderModelIDs added in v0.0.140 

func ProviderModelIDs(provider string) []string

ProviderModelIDs returns model IDs for a built-in provider. Copilot, Grok, Zen, agy-bin, cursor-bin, and grok-bin prefer the latest live model-list cache when present; Grok, Zen, agy-bin, cursor-bin, and grok-bin fall back to their curated starter lists when the cache is empty. 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 RecordGuardianReview added in v0.0.404 

func RecordGuardianReview(ctx context.Context, review GuardianReview)

RecordGuardianReview attaches a correlated review to the active tool call.

func RefreshAgyBinCacheSync added in v0.9.21 

func RefreshAgyBinCacheSync(models []ModelInfo)

RefreshAgyBinCacheSync stores a freshly fetched agy CLI model list for completions and offline provider/model pickers.

func RefreshAgyBinModelsIfStale added in v0.9.21 

func RefreshAgyBinModelsIfStale(ctx context.Context, model string, env map[string]string) error

RefreshAgyBinModelsIfStale refreshes the on-disk model catalog when it is missing or older than the shared model-cache TTL. A failed refresh leaves any stale cache available as a completion fallback.

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 RefreshCursorBinCacheSync added in v0.0.353 

func RefreshCursorBinCacheSync(models []ModelInfo)

RefreshCursorBinCacheSync stores a freshly fetched Cursor Agent model list for completions and offline provider/model pickers. IDs are normalized to term-llm's cursor-bin naming (auto-smart, grok-4.5-*).

func RefreshGrokBinCacheSync added in v0.0.392 

func RefreshGrokBinCacheSync(models []ModelInfo)

RefreshGrokBinCacheSync stores a freshly fetched Grok CLI model list for completions and offline provider/model pickers. Base grok-4* IDs are expanded with term-llm's effort-suffix aliases so pickers stay consistent with the curated catalog.

func RefreshGrokBinModelsIfStale added in v0.0.392 

func RefreshGrokBinModelsIfStale(ctx context.Context, model string, env map[string]string) error

RefreshGrokBinModelsIfStale refreshes the on-disk model catalog when it is missing or older than the shared model-cache TTL. A failed refresh leaves any stale cache available as a completion fallback.

func RefreshOllamaModelsIfStale added in v0.0.397 

func RefreshOllamaModelsIfStale(ctx context.Context, baseURL, model string) error

RefreshOllamaModelsIfStale refreshes the endpoint-specific Ollama model cache when it is missing or stale. A failed refresh leaves stale completions usable.

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 RefreshZenCacheSync added in v0.0.402 

func RefreshZenCacheSync(models []ModelInfo)

RefreshZenCacheSync stores freshly fetched Zen model metadata for completion and offline provider/model pickers.

func RefreshZenModelsIfStale added in v0.0.402 

func RefreshZenModelsIfStale(ctx context.Context, apiKey, model string) error

RefreshZenModelsIfStale refreshes the live Zen model cache when it is missing or stale. A failed refresh leaves stale completions available.

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 SupportsReasoningMode added in v0.0.321 

func SupportsReasoningMode(provider, model string) bool

SupportsReasoningMode reports whether a provider/model accepts the public Responses API reasoning.mode control. ChatGPT OAuth intentionally returns false because its Codex backend rejects public-API reasoning modes.

func ToolDiscoverySearchCutoff added in v0.0.388 

func ToolDiscoverySearchCutoff(maxTurns int) int

ToolDiscoverySearchCutoff returns the first attempt on which discovery is closed.

func ToolRunIDFromContext added in v0.0.388 

func ToolRunIDFromContext(ctx context.Context) string

ToolRunIDFromContext returns the active engine run identity.

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 ValidateAgyBinModel added in v0.0.370 

func ValidateAgyBinModel(model string) error

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.

func ValidateCursorBinModel added in v0.0.353 

func ValidateCursorBinModel(model string) error

func ValidateGrokBinModel added in v0.0.321 

func ValidateGrokBinModel(model string) error

ValidateGrokBinModel rejects the common provider:model typo where an effort level is supplied as the whole model. Model names are otherwise deliberately open-ended because `grok models` depends on the user's subscription.

Types

type AgyBinProvider added in v0.0.370 

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

func NewAgyBinProvider added in v0.0.370 

func NewAgyBinProvider(model string, env map[string]string) *AgyBinProvider

func (*AgyBinProvider) Capabilities added in v0.0.370 

func (p *AgyBinProvider) Capabilities() Capabilities

func (*AgyBinProvider) CleanupMCP added in v0.0.370 

func (p *AgyBinProvider) CleanupMCP()

func (*AgyBinProvider) CleanupTurn added in v0.0.370 

func (p *AgyBinProvider) CleanupTurn()

func (*AgyBinProvider) Credential added in v0.0.370 

func (p *AgyBinProvider) Credential() string

func (*AgyBinProvider) ExportProviderState added in v0.0.373 

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

func (*AgyBinProvider) ImportProviderState added in v0.0.373 

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

func (*AgyBinProvider) ListModels added in v0.0.370 

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

ListModels parses the account-specific tab-separated model catalog exposed by `agy models` and saves it in term-llm's shared model cache.

func (*AgyBinProvider) Name added in v0.0.370 

func (p *AgyBinProvider) Name() string

func (*AgyBinProvider) RequestInlineFlush added in v0.0.392 

func (p *AgyBinProvider) RequestInlineFlush()

RequestInlineFlush marks the next tool result so agy ends its current prompt. The engine then starts a new Stream that delivers queued interjections.

func (*AgyBinProvider) ResetConversation added in v0.0.370 

func (p *AgyBinProvider) ResetConversation()

func (*AgyBinProvider) SetEnv added in v0.0.370 

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

func (*AgyBinProvider) SetToolExecutor added in v0.0.370 

func (p *AgyBinProvider) SetToolExecutor(executor func(context.Context, string, json.RawMessage) (ToolOutput, error))

func (*AgyBinProvider) Stream added in v0.0.370 

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

func (*AgyBinProvider) SupportsInlineFlush added in v0.0.392 

func (p *AgyBinProvider) SupportsInlineFlush() bool

SupportsInlineFlush reports that agy-bin can stop its inline tool loop at a tool-result boundary.

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 using Anthropic's default API endpoint.

func NewAnthropicProviderWithBaseURL added in v0.0.380 

func NewAnthropicProviderWithBaseURL(apiKey, model, credentialMode, baseURL string) (*AnthropicProvider, error)

NewAnthropicProviderWithBaseURL 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 CLICommandError added in v0.0.321 

type CLICommandError struct {
	BinName        string
	ErrorType      string
	ExitCode       int
	Err            error
	Args           []string
	CommandLine    string
	Cwd            string
	CLICwd         string
	Effort         string
	ToolsExecuted  bool
	PreferOAuth    bool
	Env            map[string]string
	RemovedEnv     []string
	Stdin          string
	StdinLen       int
	StdinSHA256    string
	StdinTruncated bool
	PromptLen      int
	PromptSHA256   string
	StdoutTail     string
	StderrTail     string
}

CLICommandError carries bounded, redacted diagnostics for a failed local CLI transport. Cwd describes the operating-system process working directory; CLICwd optionally records a distinct provider-level cwd argument. Prompt content should not be included for prompt-file transports; PromptLen and PromptSHA256 are sufficient to correlate failures safely.

func (*CLICommandError) DebugFields added in v0.0.321 

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

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

func (*CLICommandError) Error added in v0.0.321 

func (e *CLICommandError) Error() string

func (*CLICommandError) Unwrap added in v0.0.321 

func (e *CLICommandError) Unwrap() 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)
	InlineToolLoop          bool // Provider completes its MCP/tool loop inside one Stream invocation
	OrderedInlineToolEvents bool // Provider requires streamed text/tool/text order preserved in persisted assistant parts
}

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) NativeToolDiscoverySupport added in v0.0.388 

func (p *ChatGPTProvider) NativeToolDiscoverySupport(model string) NativeToolDiscoverySupport

NativeToolDiscoverySupport is intentionally narrower than the public API's general model family support. It records only the exact ChatGPT OAuth Responses WebSocket combination verified by this integration.

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

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 resume state (sessionID, messagesSent, transcriptDigest). 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) RequestInlineFlush added in v0.0.392 

func (p *ClaudeBinProvider) RequestInlineFlush()

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)

func (*ClaudeBinProvider) SupportsImmediateInterruption added in v0.0.393 

func (p *ClaudeBinProvider) SupportsImmediateInterruption() bool

func (*ClaudeBinProvider) SupportsInlineFlush added in v0.0.392 

func (p *ClaudeBinProvider) SupportsInlineFlush() bool

type ClaudeCommandError added in v0.0.189 

type ClaudeCommandError = CLICommandError

ClaudeCommandError is retained as a compatibility alias for callers and tests.

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
	EphemeralMessages []Message
	OriginalCount     int
	CompactedCount    int
	Model             string // Model used by the helper LLM call.
	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.

func (*CompactionResult) ActiveMessages added in v0.0.339 

func (r *CompactionResult) ActiveMessages() []Message

ActiveMessages returns the durable replacement history plus request-only restoration context. Developer context is placed before the latest user turn so providers without a native developer role can fold it into that turn. The ordinary no-ephemeral path returns NewMessages directly, preserving allocation and identity behavior for existing agents.

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 CursorBinProvider added in v0.0.353 

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

func NewCursorBinProvider added in v0.0.353 

func NewCursorBinProvider(model string, env map[string]string) *CursorBinProvider

func (*CursorBinProvider) Capabilities added in v0.0.353 

func (p *CursorBinProvider) Capabilities() Capabilities

func (*CursorBinProvider) CleanupMCP added in v0.0.353 

func (p *CursorBinProvider) CleanupMCP()

func (*CursorBinProvider) CleanupTurn added in v0.0.353 

func (p *CursorBinProvider) CleanupTurn()

func (*CursorBinProvider) Credential added in v0.0.353 

func (p *CursorBinProvider) Credential() string

func (*CursorBinProvider) ExportProviderState added in v0.0.353 

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

func (*CursorBinProvider) ImportProviderState added in v0.0.353 

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

func (*CursorBinProvider) ListModels added in v0.0.353 

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

ListModels parses the account-specific model list exposed by Cursor Agent.

func (*CursorBinProvider) Name added in v0.0.353 

func (p *CursorBinProvider) Name() string

func (*CursorBinProvider) RequestInlineFlush added in v0.0.392 

func (p *CursorBinProvider) RequestInlineFlush()

RequestInlineFlush marks the next tool result so Cursor Agent ends its current prompt. The engine then starts a new Stream that delivers queued interjections.

func (*CursorBinProvider) ResetConversation added in v0.0.353 

func (p *CursorBinProvider) ResetConversation()

func (*CursorBinProvider) SetEnv added in v0.0.353 

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

func (*CursorBinProvider) SetToolExecutor added in v0.0.353 

func (p *CursorBinProvider) SetToolExecutor(executor func(context.Context, string, json.RawMessage) (ToolOutput, error))

func (*CursorBinProvider) Stream added in v0.0.353 

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

func (*CursorBinProvider) SupportsInlineFlush added in v0.0.392 

func (p *CursorBinProvider) SupportsInlineFlush() bool

SupportsInlineFlush reports that cursor-bin can stop its inline tool loop at a tool-result boundary.

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) LogDiagnostic added in v0.9.0 

func (l *DebugLogger) LogDiagnostic(name string, data map[string]any)

LogDiagnostic writes a low-volume internal diagnostic and flushes it immediately so timeout and crash investigations retain the last known state.

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, jitter, compaction. 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 DiffComment added in v0.0.400 

type DiffComment struct {
	ID       string `json:"id"`
	ParentID string `json:"parent_id,omitempty"`
	Path     string `json:"path"`
	// Scope is the diff view captured by the anchor. Empty means last_turn for
	// comments persisted before scoped Git diffs supported inline comments.
	Scope string `json:"scope,omitempty"`
	Side  string `json:"side"`
	Line  int    `json:"line"`
	// FileChangeSeq is the retained snapshot sequence for last_turn and zero
	// for Git scopes, which do not have a session file-tracker snapshot.
	FileChangeSeq int64                    `json:"file_change_seq"`
	LineText      string                   `json:"line_text"`
	ContextBefore []DiffCommentContextLine `json:"context_before,omitempty"`
	ContextAfter  []DiffCommentContextLine `json:"context_after,omitempty"`
	Instruction   string                   `json:"instruction"`
}

DiffComment is durable, display-only metadata for an instruction anchored to a particular diff snapshot. The adjacent text part carries the actual provider-facing instruction.

type DiffCommentContextLine added in v0.0.400 

type DiffCommentContextLine struct {
	Side string `json:"side"`
	Line int    `json:"line"`
	Text string `json:"text"`
}

DiffCommentContextLine preserves one exact nearby line from the diff that the user saw when submitting an inline instruction.

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 DiscoveredTool added in v0.0.388 

type DiscoveredTool struct {
	Spec       ToolSpec `json:"spec"`
	SchemaHash string   `json:"schema_hash"`
}

DiscoveredTool is a trusted catalogue schema selected by the local planner. SchemaHash binds replay to the authorised catalogue generation that supplied it.

type DynamicToolPublisher added in v0.0.392 

type DynamicToolPublisher interface {
	PublishDynamicTools([]ToolSpec) error
}

DynamicToolPublisher is implemented by providers that must react while a tool loop is active inside one Stream call. Implementations may publish the schema live or arrange a controlled provider boundary before the next tool.

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 it for the currently active run. Calls outside a run only register the tool; durable activation belongs to the planner/tool.

func (*Engine) AddDynamicToolForRun added in v0.0.388 

func (e *Engine) AddDynamicToolForRun(runID string, tool Tool) bool

AddDynamicToolForRun queues a provider schema only for the matching active run.

func (*Engine) AllowedToolsFilter added in v0.0.337 

func (e *Engine) AllowedToolsFilter() (tools []string, present bool)

AllowedToolsFilter returns a copy of the active filter and whether a filter is present. It is used to restore a temporary per-turn skill restriction.

func (*Engine) CancelInterjection added in v0.0.254 

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

CancelInterjection removes a queued, not-yet-committed interjection without transferring its identity to follow-up ownership.

func (*Engine) ClaimInterjection added in v0.0.363 

func (e *Engine) ClaimInterjection(id string) InterjectionClaimStatus

ClaimInterjection atomically transfers a queued interjection to a normal follow-up request. A committed result means the engine already drained the ID and the caller must not submit it again.

func (*Engine) ClaimInterjections added in v0.0.363 

func (e *Engine) ClaimInterjections(ids []string) []InterjectionClaimStatus

ClaimInterjections atomically transfers queued interjections to one normal follow-up request. IDs must be unique. If any ID is already committed or owned by another follow-up, no queued entry is removed.

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) ClearToolSurfacePlanner added in v0.0.388 

func (e *Engine) ClearToolSurfacePlanner(planner ToolSurfacePlanner) bool

ClearToolSurfacePlanner removes planner only when it still owns this engine. This prevents an old planner from detaching a newer replacement.

func (*Engine) CompactionThresholds added in v0.0.328 

func (e *Engine) CompactionThresholds() (soft, hard int, enabled bool)

CompactionThresholds returns the configured soft and hard compaction token thresholds. The final value is false when compaction is disabled or the input limit is unknown.

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 exact total tokens plus a legacy message count retained for compatibility with existing session metadata.

func (*Engine) DiscardPendingInterjections added in v0.0.311 

func (e *Engine) DiscardPendingInterjections() int

DiscardPendingInterjections removes all queued, not-yet-committed interjections and returns how many were discarded.

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. When a provider usage baseline is available, it treats that exact total as covering the transcript through the last assistant message and adds only the structural delta appended after that assistant turn.

func (*Engine) FilterAllowedToolSpecs added in v0.0.337 

func (e *Engine) FilterAllowedToolSpecs(specs []ToolSpec) []ToolSpec

FilterAllowedToolSpecs removes tool definitions that cannot execute under the active allowlist. An omitted filter returns specs unchanged; a present empty filter returns an empty non-nil slice.

func (*Engine) IndirectVision added in v0.0.312 

func (e *Engine) IndirectVision() bool

IndirectVision reports whether image reference mode is enabled.

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) InterjectionIdentityStatus added in v0.9.0 

func (e *Engine) InterjectionIdentityStatus(id string) (InterjectionQueueStatus, bool)

InterjectionIdentityStatus reports engine ownership for a stable ID without mutating the queue. The boolean is false when the engine has never seen it.

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) PrepareCompactionContext added in v0.0.339 

func (e *Engine) PrepareCompactionContext(ctx context.Context, sessionID string, specs []ToolSpec, result *CompactionResult) error

PrepareCompactionContext lets available request-context tools attach request-only restoration state after durable compaction is generated. Callers use this for manual compaction paths; automatic engine compaction calls it with the already-filtered request specs.

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) QueueInterjectionWithStatus added in v0.0.363 

func (e *Engine) QueueInterjectionWithStatus(entry QueuedInterjection) (string, InterjectionQueueStatus)

QueueInterjectionWithStatus reports whether the stable identity was newly queued for an accepting agentic run, rejected because the current/latest run cannot consume it, already queued, transferred to a follow-up, or committed.

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) ReleaseClaimedInterjections added in v0.0.363 

func (e *Engine) ReleaseClaimedInterjections(ids []string)

ReleaseClaimedInterjections ends temporary follow-up ownership. Durable history remains authoritative for requests that reached persistence.

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) ResetSessionState added in v0.0.373 

func (e *Engine) ResetSessionState(sessionID string)

ResetSessionState resets provider continuation and any tool-owned cached projection for a durable session. The durable store remains authoritative.

func (*Engine) RestoreAllowedToolsFilter added in v0.0.337 

func (e *Engine) RestoreAllowedToolsFilter(tools []string, present bool)

RestoreAllowedToolsFilter restores a filter captured by AllowedToolsFilter.

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. Late-bound names are retained, but execution still requires registration.

func (*Engine) SetAllowedToolsFilter added in v0.0.337 

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

SetAllowedToolsFilter applies a present tool allowlist. Unlike SetAllowedTools, an empty slice is meaningful and blocks every callable tool.

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. The message count is legacy metadata; EstimateTokens recomputes the delta boundary from the transcript shape.

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) SetFileTrackingRunLifecycle added in v0.9.0 

func (e *Engine) SetFileTrackingRunLifecycle(recorder FileTrackingRunLifecycle)

SetFileTrackingRunLifecycle installs best-effort persisted run indexing.

func (*Engine) SetIndirectVision added in v0.0.312 

func (e *Engine) SetIndirectVision(enabled bool)

SetIndirectVision enables or disables image reference mode. When enabled, user image parts are not sent to the primary provider. Instead, provider requests contain textual file-path references and an instruction to call the view_image tool when visual content matters.

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) SetRuntimeSwitchCallback added in v0.9.21 

func (e *Engine) SetRuntimeSwitchCallback(cb RuntimeSwitchCallback)

SetRuntimeSwitchCallback sets the callback that records an applied request runtime transition before the target provider turn begins.

func (*Engine) SetToolSurfacePlanner added in v0.0.388 

func (e *Engine) SetToolSurfacePlanner(planner ToolSurfacePlanner)

SetToolSurfacePlanner installs the planner that owns dynamic provider visibility.

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) ToolDiscoveryActiveSpecs added in v0.0.391 

func (e *Engine) ToolDiscoveryActiveSpecs(sessionID string) []ToolSpec

ToolDiscoveryActiveSpecs returns the currently active MCP schemas for a session. It excludes catalogue entries that remain deferred.

func (*Engine) ToolDiscoveryDiagnostics added in v0.0.388 

func (e *Engine) ToolDiscoveryDiagnostics(sessionID string) (ToolDiscoveryDiagnostics, bool)

ToolDiscoveryDiagnostics returns current planner diagnostics when available.

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
	// ProviderTurnIndex identifies the zero-based engine turn that emitted model
	// output. ProviderTurnIndexSet distinguishes the first turn from events that
	// originate outside the engine loop and carry no turn identity.
	ProviderTurnIndex          int
	ProviderTurnIndexSet       bool
	Model                      string // For EventModelSwitch: request model applied at provider-turn boundary
	ReasoningEffort            string // For EventModelSwitch: request reasoning effort applied at provider-turn boundary
	PreviousModel              string // For EventModelSwitch: request model used by the preceding provider turn
	PreviousReasoningEffort    string // For EventModelSwitch: request reasoning effort used by the preceding provider turn
	ModelSwitchBoundaryID      string // For EventModelSwitch: stable identity shared by live and durable transcript markers
	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    // Persisted attributed changes
	ToolFilesystemObservations []FilesystemObservationSummary
	ToolOutputClaimDiagnostics []OutputClaimDiagnostic
	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 bridged tool execution.
	// The engine will execute the tool and send the result back on this channel.
	ToolResponse    chan<- ToolExecutionResponse
	ToolActivity    *ToolActivity        // For EventToolActivity; persisted for display and never forwarded to providers.
	ProviderReplay  *ProviderReplayItem  // For EventProviderReplay; never forwarded to UI consumers.
	DiscoveryCall   *ToolDiscoveryCall   // For EventDiscoveryCall.
	DiscoveryOutput *ToolDiscoveryOutput // For EventDiscoveryOutput.
	// 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.)
	EventCompaction      EventType = "compaction" // Emitted after context compaction has been applied by the owner.
	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
	EventToolActivity    EventType = "tool_activity"    // Internal-only durable display state for provider-managed tools.
	EventProviderReplay  EventType = "provider_replay"  // Internal-only opaque Responses output item.
	EventDiscoveryCall   EventType = "discovery_call"   // Provider-neutral native client-executed discovery request.
	EventDiscoveryOutput EventType = "discovery_output" // Planner-selected schemas returned to native discovery.
)

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 unavailable)
	Dels             int      `json:"dels"` // Lines removed by this change (0 when unavailable)
	Seq              int64    `json:"seq"`  // Per-session monotonic attributed-change sequence
	EventSeq         int64    `json:"event_seq,omitempty"`
	Truncated        bool     `json:"truncated,omitempty"` // Legacy compatibility; ContentStatus is authoritative
	Provenance       string   `json:"provenance,omitempty"`
	Provenances      []string `json:"provenances,omitempty"`
	BaselineState    string   `json:"baseline_state,omitempty"`
	ContentStatus    string   `json:"content_status,omitempty"`
	ContentAvailable bool     `json:"content_available"`
	ClaimCoverage    string   `json:"claim_coverage,omitempty"`
	TrustedPersisted bool     `json:"-"` // set only by the trusted recorder after persistence
}

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 FileTrackingRunLifecycle added in v0.9.0 

type FileTrackingRunLifecycle interface {
	RecordFileTrackingRunStart(context.Context, string, string) error
	RecordFileTrackingRunComplete(context.Context, string, string) error
}

FileTrackingRunLifecycle persists run boundaries independently of file changes.

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/Grok/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 FilesystemObservationSummary added in v0.9.0 

type FilesystemObservationSummary struct {
	ID               int64    `json:"id"`
	Classification   string   `json:"classification"`
	Root             string   `json:"root,omitempty"`
	CreatedCount     int      `json:"created_count"`
	ModifiedCount    int      `json:"modified_count"`
	DeletedCount     int      `json:"deleted_count"`
	SampledPaths     []string `json:"sampled_paths,omitempty"`
	SamplesTruncated bool     `json:"samples_truncated,omitempty"`
	CoverageStatus   string   `json:"coverage_status"`
	EventSeq         int64    `json:"event_seq"`
}

FilesystemObservationSummary describes detected but non-attributed effects.

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 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 GrokBinProvider added in v0.0.321 

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

GrokBinProvider uses the locally installed Grok Build CLI as an authenticated model transport. term-llm remains the sole owner of executable local tools: ACP receives a restricted agent profile plus an isolated in-process HTTP MCP server. When Request.Search selects provider-native search, the profile also permits Grok's read-only web_search, web_fetch, and x_search backend tools. Grok's standard ACP prompt completion metadata supplies provider token usage; image turns temporarily retain the legacy headless transport because Grok 0.2.x does not advertise ACP image prompt support.

Its isolated GROK_HOME does not load custom [model.*] definitions from the user's normal ~/.grok/config.toml; model names remain open-ended and are passed through to the CLI. It is not safe for concurrent conversation streams; create one provider per conversation.

func NewGrokBinProvider added in v0.0.321 

func NewGrokBinProvider(model string, env map[string]string) *GrokBinProvider

func (*GrokBinProvider) Capabilities added in v0.0.321 

func (p *GrokBinProvider) Capabilities() Capabilities

func (*GrokBinProvider) CleanupMCP added in v0.0.321 

func (p *GrokBinProvider) CleanupMCP()

CleanupMCP stops the conversation-scoped ACP process and HTTP tool bridge, then removes per-turn prompt files. It intentionally keeps GROK_HOME because Grok's resumable ACP session data lives there and may be restored after serve runtime eviction.

func (*GrokBinProvider) CleanupTurn added in v0.0.321 

func (p *GrokBinProvider) CleanupTurn()

func (*GrokBinProvider) Credential added in v0.0.321 

func (p *GrokBinProvider) Credential() string

func (*GrokBinProvider) ExportProviderState added in v0.0.321 

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

func (*GrokBinProvider) ImportProviderState added in v0.0.321 

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

func (*GrokBinProvider) ListModels added in v0.0.392 

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

ListModels parses the account-specific model list exposed by `grok models`. Grok fetches this from the remote /v1/models catalog (with a baked-in default_models.json fallback), which is how the CLI itself stays current.

func (*GrokBinProvider) Name added in v0.0.321 

func (p *GrokBinProvider) Name() string

func (*GrokBinProvider) PublishDynamicTools added in v0.0.392 

func (p *GrokBinProvider) PublishDynamicTools(tools []ToolSpec) error

PublishDynamicTools marks the current inline prompt for a controlled provider boundary. Grok Build 1.0.x caches MCP search registrations for the lifetime of an ACP process, so the next Stream call rebuilds the MCP server and resumes the durable session with the expanded tool surface.

func (*GrokBinProvider) RequestInlineFlush added in v0.0.392 

func (p *GrokBinProvider) RequestInlineFlush()

func (*GrokBinProvider) ResetConversation added in v0.0.321 

func (p *GrokBinProvider) ResetConversation()

func (*GrokBinProvider) SetEnv added in v0.0.321 

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

func (*GrokBinProvider) SetPreferOAuth added in v0.0.321 

func (p *GrokBinProvider) SetPreferOAuth(prefer bool)

func (*GrokBinProvider) SetToolExecutor added in v0.0.321 

func (p *GrokBinProvider) SetToolExecutor(executor func(context.Context, string, json.RawMessage) (ToolOutput, error))

func (*GrokBinProvider) Stream added in v0.0.321 

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

func (*GrokBinProvider) SupportsImmediateInterruption added in v0.0.393 

func (p *GrokBinProvider) SupportsImmediateInterruption() bool

func (*GrokBinProvider) SupportsInlineFlush added in v0.0.392 

func (p *GrokBinProvider) SupportsInlineFlush() bool

type GrokProvider added in v0.0.404 

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

func NewGrokProvider added in v0.0.404 

func NewGrokProvider(model string) (*GrokProvider, error)

func NewGrokProviderWithCreds added in v0.0.404 

func NewGrokProviderWithCreds(creds *credentials.GrokCredentials, model string) *GrokProvider

func NewGrokProviderWithCredsAndOptions added in v0.0.404 

func NewGrokProviderWithCredsAndOptions(creds *credentials.GrokCredentials, model string, opts GrokProviderOptions) *GrokProvider

func NewGrokProviderWithOptions added in v0.0.404 

func NewGrokProviderWithOptions(model string, opts GrokProviderOptions) (*GrokProvider, error)

func (*GrokProvider) Capabilities added in v0.0.404 

func (p *GrokProvider) Capabilities() Capabilities

func (*GrokProvider) Credential added in v0.0.404 

func (p *GrokProvider) Credential() string

func (*GrokProvider) ListModels added in v0.0.404 

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

func (*GrokProvider) ListModelsWithFreshness added in v0.0.404 

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

func (*GrokProvider) Name added in v0.0.404 

func (p *GrokProvider) Name() string

func (*GrokProvider) ResetConversation added in v0.0.404 

func (p *GrokProvider) ResetConversation()

func (*GrokProvider) Stream added in v0.0.404 

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

type GrokProviderOptions added in v0.0.404 

type GrokProviderOptions struct {
	FileUploadPolicy *FileUploadPolicy
}

type GuardianReview added in v0.0.404 

type GuardianReview struct {
	Outcome string `json:"outcome"`
	Message string `json:"message"`
	Model   string `json:"model,omitempty"`
	Tool    string `json:"tool,omitempty"`
	Command string `json:"command,omitempty"`
	Path    string `json:"path,omitempty"`
	IsWrite bool   `json:"is_write,omitempty"`
	WorkDir string `json:"workdir,omitempty"`
}

GuardianReview is display-only audit metadata for a Guardian-reviewed tool invocation. Providers must continue to receive only the ordinary tool result.

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 HandoverOptions added in v0.0.358 

type HandoverOptions struct {
	AllowProviderFork bool
}

HandoverOptions controls whether generation may branch from live provider state. Callers must only enable forking at a settled provider boundary.

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
	Model       string
	Usage       Usage
}

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, options HandoverOptions) (*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 ImmediateInterrupter added in v0.0.393 

type ImmediateInterrupter interface {
	SupportsImmediateInterruption() bool
}

ImmediateInterrupter reports that a provider can end an in-flight model turn without waiting for a tool boundary. Engines use the normal agentic loop for these providers even when no tools are exposed so queued interjections have a continuation boundary to consume.

type InlineFlusher added in v0.0.392 

type InlineFlusher interface {
	RequestInlineFlush()
	SupportsInlineFlush() bool
}

InlineFlusher is implemented by inline-loop providers that can end the current CLI prompt at the next tool-result boundary. The engine requests a flush when an interjection is queued so the following Stream can deliver it. RetryProvider implements the methods so factory wrapping stays transparent; SupportsInlineFlush reports whether the inner provider can actually flush.

type InterjectionClaimStatus added in v0.0.363 

type InterjectionClaimStatus string
const (
	InterjectionClaimNotFound      InterjectionClaimStatus = "not_found"
	InterjectionClaimed            InterjectionClaimStatus = "claimed"
	InterjectionClaimFollowUpOwned InterjectionClaimStatus = "follow_up_owned"
	InterjectionClaimCommitted     InterjectionClaimStatus = "committed"
)

type InterjectionQueueStatus added in v0.0.363 

type InterjectionQueueStatus string
const (
	InterjectionQueueQueued        InterjectionQueueStatus = "queued"
	InterjectionQueueAlreadyQueued InterjectionQueueStatus = "already_queued"
	InterjectionQueueFollowUpOwned InterjectionQueueStatus = "follow_up_owned"
	InterjectionQueueCommitted     InterjectionQueueStatus = "committed"
	InterjectionQueueRunFinished   InterjectionQueueStatus = "run_finished"
)

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)
	ApprovalRole            string `json:",omitempty"` // Optional role override for guardian/policy-review transcripts only.
	ClientMessageID         string `json:",omitempty"` // Stable identity for first-party user intent; providers ignore it.
	DisplayText             string `json:",omitempty"` // Optional persistence/UI text when provider-only context is present.
	ResponseID              string `json:",omitempty"` // Stable response owner for persisted/UI projection identity; providers ignore it.
	AssistantSegmentOrdinal int    `json:",omitempty"` // Response-scoped assistant segment identity; -1 when not applicable.
	SegmentStartSequence    int64  `json:",omitempty"` // First response event sequence for this assistant segment, when known.
	SegmentEndSequence      int64  `json:",omitempty"` // Last response event sequence covered by this persisted segment, when known.
}

Message holds a role with structured parts.

func ApprovalTranscriptFromContext added in v0.0.317 

func ApprovalTranscriptFromContext(ctx context.Context) []Message

ApprovalTranscriptFromContext extracts the policy-review transcript messages.

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 GoalSteeringText added in v0.9.0 

func GoalSteeringText(text string) Message

GoalSteeringText creates a provider-visible user-role prompt used to continue an active goal. The marker is persisted for provenance and removed before the adjacent text is sent to providers.

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 RunErrorEventMessage added in v0.0.315 

func RunErrorEventMessage(marker RunErrorMarker) Message

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

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) RecordedRequests added in v0.0.337 

func (m *MockProvider) RecordedRequests() []Request

RecordedRequests returns a snapshot of requests observed by the provider.

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)
	OutputLimit            int                `json:"output_limit,omitempty"`       // Max output tokens (0 = unknown)
	ConfiguredContext      int                `json:"configured_context,omitempty"` // Provider/model runtime context setting (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"`
	ReasoningEfforts       []string           `json:"reasoning_efforts,omitempty"`
	DefaultReasoningEffort string             `json:"default_reasoning_effort,omitempty"`
	ReasoningModes         []string           `json:"reasoning_modes,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 CachedGrokModels added in v0.0.404 

func CachedGrokModels() ([]ModelInfo, bool, error)

func CachedOpenCodeGoModels added in v0.0.380 

func CachedOpenCodeGoModels() ([]ModelInfo, bool, error)

CachedOpenCodeGoModels returns the last complete OpenCode Go model metadata without performing network access. The freshness result uses the provider's short catalog TTL so callers can show cached capabilities immediately while scheduling a background refresh when needed.

func GetCachedAgyBinModelInfos added in v0.9.21 

func GetCachedAgyBinModelInfos() []ModelInfo

GetCachedAgyBinModelInfos returns cached live agy CLI model metadata. Stale entries remain available because they are preferable to the curated fallback and keep non-subprocess callers fast.

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 GetCachedCursorBinModelInfos added in v0.0.353 

func GetCachedCursorBinModelInfos() []ModelInfo

GetCachedCursorBinModelInfos returns cached live Cursor Agent model metadata. Stale cache entries are still returned because they are preferable to the small curated fallback and keep non-subprocess callers fast.

func GetCachedGrokBinModelInfos added in v0.0.392 

func GetCachedGrokBinModelInfos() []ModelInfo

GetCachedGrokBinModelInfos returns cached live Grok CLI model metadata. Stale cache entries are still returned because they are preferable to the small curated fallback and keep non-subprocess callers fast.

func GetCachedOllamaModelInfos added in v0.0.397 

func GetCachedOllamaModelInfos(baseURL string) []ModelInfo

GetCachedOllamaModelInfos returns the last live endpoint-specific Ollama model metadata without performing network access.

func GetCachedOpenRouterModelInfos added in v0.0.267 

func GetCachedOpenRouterModelInfos(apiKey string) []ModelInfo

func GetCachedVeniceModelInfos added in v0.0.268 

func GetCachedVeniceModelInfos(apiKey string) []ModelInfo

func GetCachedZenModelInfos added in v0.0.402 

func GetCachedZenModelInfos() []ModelInfo

GetCachedZenModelInfos returns the last live Zen model catalog without performing network access. Stale entries remain useful for shell completion.

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"`
	BoundaryID   string `json:"boundary_id,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 MultiAgentOptions added in v0.0.321 

type MultiAgentOptions struct {
	Enabled                bool
	EnabledSet             bool
	MaxConcurrentSubagents int
}

type NativeToolDiscoveryPlanner added in v0.0.388 

type NativeToolDiscoveryPlanner interface {
	ResolveNativeToolDiscovery(ctx context.Context, runID string, call ToolDiscoveryCall) (ToolDiscoveryOutput, error)
	FallbackNativeToolDiscovery(runID string, cause error, committed bool) (fallback bool, reason string)
}

NativeToolDiscoveryPlanner is the provider-neutral engine contract for native client-executed discovery. The engine owns call orchestration; planners own search, policy, trusted schema selection, and one-shot fallback decisions.

type NativeToolDiscoveryProvider added in v0.0.388 

type NativeToolDiscoveryProvider interface {
	NativeToolDiscoverySupport(model string) NativeToolDiscoverySupport
}

NativeToolDiscoveryProvider is implemented only by providers that can translate the provider-neutral discovery request and replay parts to their wire protocol. Support must be exact rather than inferred from general tool calling.

type NativeToolDiscoveryRequest added in v0.0.388 

type NativeToolDiscoveryRequest struct {
	Search ToolSpec `json:"search"`
}

NativeToolDiscoveryRequest is provider-neutral orchestration metadata. Search is the planner-owned input contract; provider adapters translate it to their native discovery tool only when NativeToolDiscoverySupport succeeds.

type NativeToolDiscoverySupport added in v0.0.388 

type NativeToolDiscoverySupport struct {
	Supported bool
	Name      string
	Reason    string
}

NativeToolDiscoverySupport describes a provider/model/transport combination whose client-executed discovery protocol has been explicitly verified.

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
	ThinkLevel      string
	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
	Responses        ResponsesOptions
}

type OpenCodeGoProvider added in v0.0.380 

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

OpenCodeGoProvider routes OpenCode Go models to the wire protocol advertised by the live OpenCode model catalog.

func NewOpenCodeGoProvider added in v0.0.380 

func NewOpenCodeGoProvider(apiKey, model string) *OpenCodeGoProvider

func NewOpenCodeGoProviderWithBaseURL added in v0.0.400 

func NewOpenCodeGoProviderWithBaseURL(apiKey, model, baseURL string) *OpenCodeGoProvider

NewOpenCodeGoProviderWithBaseURL creates an OpenCode Go provider using an optional compatible proxy base URL.

func (*OpenCodeGoProvider) Capabilities added in v0.0.380 

func (p *OpenCodeGoProvider) Capabilities() Capabilities

func (*OpenCodeGoProvider) Credential added in v0.0.380 

func (p *OpenCodeGoProvider) Credential() string

func (*OpenCodeGoProvider) ListModels added in v0.0.380 

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

func (*OpenCodeGoProvider) ListModelsWithFreshness added in v0.0.380 

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

func (*OpenCodeGoProvider) Name added in v0.0.380 

func (p *OpenCodeGoProvider) Name() string

func (*OpenCodeGoProvider) RefreshModelMetadata added in v0.0.380 

func (p *OpenCodeGoProvider) RefreshModelMetadata(ctx context.Context) error

func (*OpenCodeGoProvider) Stream added in v0.0.380 

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

type OutputClaimDiagnostic added in v0.9.0 

type OutputClaimDiagnostic struct {
	NormalizedPattern string `json:"normalized_pattern"`
	ClaimKind         string `json:"claim_kind"`
	Reason            string `json:"reason"`
	CoverageStatus    string `json:"coverage_status"`
	MatchingPathCount int    `json:"matching_path_count"`
	Message           string `json:"message,omitempty"`
}

OutputClaimDiagnostic reports confirmation, mismatch, coverage, and tracker failures.

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
	ToolActivity              *ToolActivity
	ProviderReplay            *ProviderReplayItem        // Opaque Responses output item used only for stateless continuation.
	DiscoveryCall             *ToolDiscoveryCall         // Native discovery request emitted by a capable provider.
	DiscoveryOutput           *ToolDiscoveryOutput       // Planner-selected trusted schemas paired to a discovery call.
	SkillActivation           *SkillActivationProvenance // Direct user activation metadata; persisted but not provider content.
	PathNote                  *PathNoteProvenance        // Branch-context metadata; persisted but not sent to providers.
	DiffComment               *DiffComment               // Inline-diff comment anchor; persisted but not sent to providers.
}

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"
	PartToolActivity    PartType = "tool_activity"    // Persisted display-only provider-managed tool activity; never sent to providers.
	PartProviderReplay  PartType = "provider_replay"  // Hidden provider protocol state; never rendered/exported.
	PartDiscoveryCall   PartType = "discovery_call"   // Provider-neutral native discovery call, translated only by capable adapters.
	PartDiscoveryOutput PartType = "discovery_output" // Trusted schemas selected by the local planner for a discovery call.
	PartSkillActivation PartType = "skill_activation" // Persisted direct-activation provenance; never sent to providers.
	PartAgentMention    PartType = "agent_mention"    // Provider-visible delegation instruction; excluded from human-visible text surfaces.
	PartPathNote        PartType = "path_note"        // Persisted branch-context provenance; adjacent text is sent as developer context.
	PartDiffComment     PartType = "diff_comment"     // Persisted inline-diff anchor metadata; never sent to providers.
	PartGoalSteering    PartType = "goal_steering"    // Persisted marker for synthetic active-goal user prompts; adjacent text is sent to providers but hidden from human transcripts.
)

type PathNoteProvenance added in v0.0.377 

type PathNoteProvenance struct {
	SourceSessionID string   `json:"source_session_id"`
	AnchorMessageID int64    `json:"anchor_message_id,omitempty"`
	SourceMessages  int      `json:"source_messages,omitempty"`
	OmittedMessages int      `json:"omitted_messages,omitempty"`
	ReadFiles       []string `json:"read_files,omitempty"`
	ModifiedFiles   []string `json:"modified_files,omitempty"`
	Model           string   `json:"model,omitempty"`
	Focus           string   `json:"focus,omitempty"`
}

PathNoteProvenance identifies generated context carried from the suffix that was left behind when a conversation branch was created.

type PathNotesConfig added in v0.0.377 

type PathNotesConfig struct {
	Focus             string
	InputTokenBudget  int
	OutputTokenBudget int
	MaxWords          int
}

PathNotesConfig controls the bounded helper call that extracts useful context from turns omitted by a conversation branch.

type PathNotesResult added in v0.0.377 

type PathNotesResult struct {
	Notes            string
	ReadFiles        []string
	ModifiedFiles    []string
	SourceMessages   int
	IncludedMessages int
	OmittedMessages  int
	InputTruncated   bool
	Model            string
	Usage            Usage
}

PathNotesResult is a compact, non-authoritative account of work performed on the path that a new conversation branch did not copy.

func GeneratePathNotes added in v0.0.377 

func GeneratePathNotes(ctx context.Context, provider Provider, model string, source []Message, config PathNotesConfig) (*PathNotesResult, error)

GeneratePathNotes makes one isolated, ephemeral provider request over a bounded serialization of the supplied abandoned-path messages.

type ProgrammaticToolCallingOptions added in v0.0.321 

type ProgrammaticToolCallingOptions struct {
	Enabled    bool
	EnabledSet bool
	Tools      []string
}

type PromptCacheOptions added in v0.0.321 

type PromptCacheOptions struct {
	Mode string
	TTL  string
}

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 NewProviderByNameNoRetry added in v0.0.390 

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

NewProviderByNameNoRetry creates the same provider as NewProviderByName but returns the underlying adapter without the production retry wrapper. It is intended for controlled callers such as benchmarks where an implicit retry would hide attempt boundaries and could reuse a now-cacheable payload.

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 (for example, a local CLI provider's persistent MCP server). Call sites: runtime eviction, server shutdown. Do NOT call per-turn.

type ProviderReplayItem added in v0.0.321 

type ProviderReplayItem struct {
	Raw json.RawMessage `json:"raw"`
}

ProviderReplayItem preserves a completed Responses output item byte-for-byte. Raw is persisted for provider continuation but omitted from display and exports.

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 ProviderUsage added in v0.0.395 

type ProviderUsage struct {
	Provider   string                `json:"provider"`
	Plan       string                `json:"plan,omitempty"`
	Source     string                `json:"source,omitempty"`
	Limits     []ProviderUsageLimit  `json:"limits,omitempty"`
	Credits    *ProviderUsageCredits `json:"credits,omitempty"`
	LimitState string                `json:"limit_state,omitempty"`
}

ProviderUsage is a live usage snapshot reported by a provider account.

func FetchProviderUsage added in v0.0.395 

func FetchProviderUsage(ctx context.Context, provider string) (*ProviderUsage, error)

FetchProviderUsage fetches current account-level usage directly from provider.

func FetchProviderUsageWithAPIKey added in v0.0.395 

func FetchProviderUsageWithAPIKey(ctx context.Context, provider, apiKey string) (*ProviderUsage, error)

FetchProviderUsageWithAPIKey fetches live usage with an explicitly resolved API key when the provider requires one. OAuth providers ignore apiKey.

type ProviderUsageCredits added in v0.0.395 

type ProviderUsageCredits struct {
	HasCredits bool   `json:"has_credits"`
	Unlimited  bool   `json:"unlimited"`
	Balance    string `json:"balance,omitempty"`
	Currency   string `json:"currency,omitempty"`
}

ProviderUsageCredits describes optional account credits returned by the provider.

type ProviderUsageFormatOptions added in v0.0.395 

type ProviderUsageFormatOptions struct {
	// Width is the available content width. Zero uses the default meter width.
	Width int
	// ASCII replaces block meter glyphs for limited terminals.
	ASCII bool
}

ProviderUsageFormatOptions controls the shared CLI and TUI usage layout.

type ProviderUsageLimit added in v0.0.395 

type ProviderUsageLimit struct {
	ID              string               `json:"id"`
	Name            string               `json:"name,omitempty"`
	Allowed         bool                 `json:"allowed"`
	LimitReached    bool                 `json:"limit_reached"`
	PrimaryWindow   *ProviderUsageWindow `json:"primary_window,omitempty"`
	SecondaryWindow *ProviderUsageWindow `json:"secondary_window,omitempty"`
}

ProviderUsageLimit describes one provider-enforced usage limit.

type ProviderUsageWindow added in v0.0.395 

type ProviderUsageWindow struct {
	Label           string    `json:"label,omitempty"`
	UsedPercent     float64   `json:"used_percent"`
	DurationMinutes int       `json:"duration_minutes,omitempty"`
	ResetsAt        time.Time `json:"resets_at,omitempty"`
	Detail          string    `json:"detail,omitempty"`
}

ProviderUsageWindow describes one provider usage window.

type QueuedInterjection added in v0.0.254 

type QueuedInterjection struct {
	ID          string
	Message     Message
	DisplayText string
	Status      InterjectionStatus
}

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
	WorkingDir string // Optional working directory for local subprocess providers
	// Ephemeral marks one-shot internal requests (title generation, summaries,
	// vision helpers) that must not participate in provider-side conversation/session
	// state. Stateful providers should avoid resuming an existing session and must
	// not update their stored session boundary.
	Ephemeral bool
	// IncludeDeveloperInContinuation keeps a developer policy immediately before
	// the latest user turn when building a server-state continuation suffix.
	IncludeDeveloperInContinuation bool
	Messages                       []Message
	ApprovalTranscriptPrefix       []Message // Optional policy-review-only evidence prepended to tool approval transcripts; never sent to providers.
	Tools                          []ToolSpec
	ToolChoice                     ToolChoice
	LastTurnToolChoice             *ToolChoice // If set, force this tool choice on the last agentic turn
	// EnableToolDiscovery opts this request into an attached dynamic tool planner.
	// It is internal orchestration state and is not provider metadata.
	EnableToolDiscovery bool
	// NativeToolDiscovery asks a capable provider adapter to expose its native
	// client-executed discovery control tool. Deferred schemas remain in neutral
	// discovery output parts, never in the ordinary top-level Tools slice.
	NativeToolDiscovery *NativeToolDiscoveryRequest
	ParallelToolCalls   bool
	// AllowedToolsPresent applies an internal, request-scoped execution filter.
	// It is consumed by runtimes before calling Engine.Stream and is not provider metadata.
	// A present empty AllowedTools slice intentionally blocks every callable tool.
	AllowedTools            []string
	AllowedToolsPresent     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
	Responses               *ResponsesOptions // Advanced Responses API controls; nil uses provider defaults.
	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 RequestContextTool added in v0.0.339 

type RequestContextTool interface {
	Tool
	PrepareRequestContext(ctx context.Context, sessionID string, messages []Message) ([]Message, error)
	PrepareCompactionContext(ctx context.Context, sessionID string, result *CompactionResult) error
}

RequestContextTool is an optional interface for explicitly configured tools that own restorable, session-scoped model context. Engine invokes it only when that exact tool survives final request filtering and the provider supports tool calls.

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
	WebSocketPoolKey           string
	WebSocketConnectTimeout    time.Duration
	WebSocketWriteTimeout      time.Duration
	WebSocketIdleTimeout       time.Duration
	WebSocketFirstEventTimeout time.Duration
	WebSocketParkedTimeout     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 ResponsesIncompleteError added in v0.0.321 

type ResponsesIncompleteError struct {
	Reason string
}

ResponsesIncompleteError reports an explicit response.incomplete terminal event from the provider. Partial output and usage may have been emitted.

func (*ResponsesIncompleteError) Error added in v0.0.321 

func (e *ResponsesIncompleteError) Error() string

type ResponsesInputItem added in v0.0.34 

type ResponsesInputItem struct {
	Raw           json.RawMessage `json:"-"` // Exact provider output item for stateless replay.
	Type          string          `json:"type"`
	Role          string          `json:"role,omitempty"`
	Content       interface{}     `json:"content,omitempty"` // string or []ResponsesContentPart
	Phase         string          `json:"phase,omitempty"`
	Agent         string          `json:"agent,omitempty"`
	Caller        string          `json:"caller,omitempty"`
	Program       string          `json:"program,omitempty"`
	ProgramOutput string          `json:"program_output,omitempty"`
	Fingerprint   string          `json:"fingerprint,omitempty"`
	// 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"`
	Namespace string `json:"namespace,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.

func (ResponsesInputItem) MarshalJSON added in v0.0.321 

func (i ResponsesInputItem) MarshalJSON() ([]byte, error)

type ResponsesMultiAgent added in v0.0.321 

type ResponsesMultiAgent struct {
	Enabled                bool `json:"enabled"`
	MaxConcurrentSubagents int  `json:"max_concurrent_subagents,omitempty"`
}

type ResponsesNamespace added in v0.0.388 

type ResponsesNamespace struct {
	Type        string                           `json:"type"`
	Name        string                           `json:"name"`
	Description string                           `json:"description,omitempty"`
	Tools       []ResponsesNamespaceFunctionTool `json:"tools"`
}

ResponsesNamespace is the native Responses namespace shape returned from a client-executed tool_search. Only individually selected children are included.

type ResponsesNamespaceFunctionTool added in v0.0.388 

type ResponsesNamespaceFunctionTool 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"`
	AllowedCallers []string               `json:"allowed_callers,omitempty"`
	OutputSchema   map[string]interface{} `json:"output_schema,omitempty"`
	DeferLoading   bool                   `json:"defer_loading"`
}

type ResponsesOptions added in v0.0.321 

type ResponsesOptions struct {
	ReasoningMode           string
	ReasoningContext        string
	MultiAgent              MultiAgentOptions
	ProgrammaticToolCalling ProgrammaticToolCallingOptions
	PromptCache             PromptCacheOptions
}

ResponsesOptions controls advanced OpenAI Responses API execution features. A nil Request.Responses uses provider configuration; a non-nil value overlays its explicitly populated fields on those defaults.

func (ResponsesOptions) IsZero added in v0.0.321 

func (o ResponsesOptions) IsZero() bool

type ResponsesPromptCacheOptions added in v0.0.321 

type ResponsesPromptCacheOptions struct {
	Mode string `json:"mode,omitempty"`
	TTL  string `json:"ttl,omitempty"`
}

type ResponsesReasoning added in v0.0.34 

type ResponsesReasoning struct {
	Effort  string `json:"effort,omitempty"`
	Summary string `json:"summary,omitempty"`
	Mode    string `json:"mode,omitempty"`
	Context string `json:"context,omitempty"`
}

ResponsesReasoning configures GPT-5.6 reasoning execution.

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.
	IncludeDeveloperInContinuation  bool                         `json:"-"`               // Include the developer policy immediately preceding the latest user continuation.
	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"`
	Text                            *ResponsesText               `json:"text,omitempty"`
	Temperature                     *float64                     `json:"temperature,omitempty"`
	TopP                            *float64                     `json:"top_p,omitempty"`
	Reasoning                       *ResponsesReasoning          `json:"reasoning,omitempty"`
	MultiAgent                      *ResponsesMultiAgent         `json:"multi_agent,omitempty"`
	PromptCacheOptions              *ResponsesPromptCacheOptions `json:"prompt_cache_options,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"`
	StreamOptions                   *ResponsesStreamOptions      `json:"stream_options,omitempty"`
	PreviousResponseID              string                       `json:"previous_response_id,omitempty"`
	ServiceTier                     string                       `json:"service_tier,omitempty"`
	SessionID                       string                       `json:"-"`
	ForceHTTP                       bool                         `json:"-"` // Bypass WebSocket for request features that require HTTP/SSE.
	ForceWebSocket                  bool                         `json:"-"` // Require WebSocket and never downgrade this request to HTTP/SSE.
	ExtraHeaders                    map[string]string            `json:"-"` // Request-scoped headers (combined with client headers).
	FileUploadPolicy                *FileUploadPolicy            `json:"-"`
}

ResponsesRequest follows the Open Responses spec

type ResponsesStreamOptions added in v0.0.321 

type ResponsesStreamOptions struct {
	ReasoningSummaryDelivery string `json:"reasoning_summary_delivery,omitempty"`
}

ResponsesStreamOptions contains streaming delivery options for the Responses API.

type ResponsesText added in v0.0.404 

type ResponsesText struct {
	Verbosity string `json:"verbosity,omitempty"`
}

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"`
	AllowedCallers []string               `json:"allowed_callers,omitempty"`
	OutputSchema   map[string]interface{} `json:"output_schema,omitempty"`
}

ResponsesTool represents a tool definition in Open Responses format

type ResponsesToolSearchTool added in v0.0.388 

type ResponsesToolSearchTool struct {
	Type        string                 `json:"type"`
	Execution   string                 `json:"execution"`
	Description string                 `json:"description,omitempty"`
	Parameters  map[string]interface{} `json:"parameters"`
}

ResponsesToolSearchTool is the provider wire shape for native client-executed tool discovery. It is deliberately not represented in ToolSpec.

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 stateful providers 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) ExportProviderState added in v0.0.321 

func (r *RetryProvider) ExportProviderState() ([]byte, bool)

ExportProviderState forwards opaque conversation transport state when the wrapped provider supports persistence.

func (*RetryProvider) ImportProviderState added in v0.0.321 

func (r *RetryProvider) ImportProviderState(data []byte) error

ImportProviderState restores opaque conversation transport state on the wrapped provider.

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) ListModelsWithFreshness added in v0.0.380 

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

func (*RetryProvider) Name added in v0.0.12 

func (r *RetryProvider) Name() string

func (*RetryProvider) NativeToolDiscoverySupport added in v0.0.388 

func (r *RetryProvider) NativeToolDiscoverySupport(model string) NativeToolDiscoverySupport

func (*RetryProvider) PublishDynamicTools added in v0.0.392 

func (r *RetryProvider) PublishDynamicTools(tools []ToolSpec) error

PublishDynamicTools forwards dynamic tool-surface changes to inline-loop providers through the retry wrapper.

func (*RetryProvider) RefreshModelMetadata added in v0.0.380 

func (r *RetryProvider) RefreshModelMetadata(ctx context.Context) error

func (*RetryProvider) RequestInlineFlush added in v0.0.392 

func (r *RetryProvider) RequestInlineFlush()

RequestInlineFlush forwards an inline tool-result flush to the inner provider.

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 CLI bridge providers 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)

func (*RetryProvider) SupportsImmediateInterruption added in v0.0.393 

func (r *RetryProvider) SupportsImmediateInterruption() bool

SupportsImmediateInterruption reports whether the wrapped provider can end model generation immediately rather than waiting for a tool result.

func (*RetryProvider) SupportsInlineFlush added in v0.0.392 

func (r *RetryProvider) SupportsInlineFlush() bool

SupportsInlineFlush reports whether the wrapped provider can stop an inline CLI prompt at the next tool-result boundary.

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 RunErrorMarker added in v0.0.315 

type RunErrorMarker struct {
	Type       string `json:"type"`
	ResponseID string `json:"response_id,omitempty"`
	ErrorType  string `json:"error_type,omitempty"`
	Message    string `json:"message,omitempty"`
}

RunErrorMarker is a durable non-LLM transcript event describing a failed response run. It is shown to users in session history but filtered from model context via RoleEvent.

func ParseRunErrorMarker added in v0.0.315 

func ParseRunErrorMarker(msg Message) (RunErrorMarker, bool)

ParseRunErrorMarker extracts a run-error marker from a durable event message.

type RuntimeSwitch added in v0.9.21 

type RuntimeSwitch struct {
	PreviousModel           string
	PreviousReasoningEffort string
	Model                   string
	ReasoningEffort         string
	ProviderTurnIndex       int
	BoundaryID              string
}

RuntimeSwitch describes the exact request runtime transition applied between provider turns. Empty effort means the provider's automatic/default effort.

type RuntimeSwitchCallback added in v0.9.21 

type RuntimeSwitchCallback func(ctx context.Context, change RuntimeSwitch) error

RuntimeSwitchCallback durably records an applied transition before the next provider turn can produce output.

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 SessionStateResetter added in v0.0.373 

type SessionStateResetter interface {
	ResetSessionState(sessionID string)
}

SessionStateResetter clears a tool's cached projection for one durable session after an out-of-band transcript mutation such as undo/redo.

type SkillActivationProvenance added in v0.0.337 

type SkillActivationProvenance struct {
	Name                string   `json:"name"`
	Source              string   `json:"source"`
	SourcePath          string   `json:"source_path"`
	Origin              string   `json:"origin"`
	Execution           string   `json:"execution"`
	RawArguments        string   `json:"raw_arguments,omitempty"`
	Agent               string   `json:"agent,omitempty"`
	Model               string   `json:"model,omitempty"`
	AllowedTools        []string `json:"allowed_tools,omitempty"`
	AllowedToolsPresent bool     `json:"allowed_tools_present,omitempty"`
	RunID               string   `json:"run_id,omitempty"`
	ChildSessionID      string   `json:"child_session_id,omitempty"`
	Status              string   `json:"status,omitempty"`
	StartedAt           string   `json:"started_at,omitempty"`
	CompletedAt         string   `json:"completed_at,omitempty"`
	ActivatedAt         string   `json:"activated_at"`
}

SkillActivationProvenance records the exact direct invocation and resolved skill source used for a historical turn. The expanded instructions are stored in the containing developer message's text part, so later on-disk edits cannot rewrite session history.

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 TextStreamResult added in v0.0.358 

type TextStreamResult struct {
	Text             string
	ReasoningSummary string
	Usage            Usage
}

TextStreamResult is the common output of one-shot helper conversations such as side questions, compaction summaries, and handover briefs.

func CollectTextStream added in v0.0.358 

func CollectTextStream(stream Stream, observer func(Event) error) (TextStreamResult, error)

CollectTextStream drains a provider stream while consistently handling text, displayable reasoning summaries, usage, retries, and provider error events. The optional observer sees each successfully applied event and may stop collection by returning an error. EventError is always terminal, including malformed error events with a nil Err; observers see it before collection returns the provider 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 ToolActivationDiagnostic added in v0.0.388 

type ToolActivationDiagnostic struct {
	Name      string
	Namespace string
	ChildName string
	Reason    string
}

ToolActivationDiagnostic records a recent model-driven activation.

type ToolActivity added in v0.0.367 

type ToolActivity struct {
	ID        string          `json:"id,omitempty"`
	Name      string          `json:"name"`
	Info      string          `json:"info,omitempty"`
	Arguments json.RawMessage `json:"arguments,omitempty"`
	Status    string          `json:"status"` // "completed" or "failed"
}

ToolActivity is a display-only record of a provider-managed tool invocation. It is persisted with assistant history but ignored by provider request builders.

type ToolCall added in v0.0.10 

type ToolCall struct {
	ID   string
	Name string // Canonical executable name after engine routing.
	// Namespace and ChildName preserve an explicit native provider identity.
	// They are never reconstructed by splitting Name.
	Namespace  string `json:",omitempty"`
	ChildName  string `json:",omitempty"`
	Arguments  json.RawMessage
	Caller     string `json:",omitempty"` // PTC caller provenance; copied to function_call_output.
	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 ToolDiscoveryCall added in v0.0.388 

type ToolDiscoveryCall struct {
	ID        string          `json:"id"`
	Arguments json.RawMessage `json:"arguments"`
}

ToolDiscoveryCall records a provider-native request for local catalogue search.

type ToolDiscoveryDiagnoser added in v0.0.388 

type ToolDiscoveryDiagnoser interface {
	Diagnostics(sessionID string) ToolDiscoveryDiagnostics
}

ToolDiscoveryDiagnoser is implemented by planners that expose inspect data.

type ToolDiscoveryDiagnostics added in v0.0.388 

type ToolDiscoveryDiagnostics struct {
	ConfiguredMode     string
	ResolvedMode       string
	ConfiguredStrategy string
	Strategy           string
	Reason             string
	StrategyReason     string
	FallbackCount      int
	FallbackReason     string
	CatalogueHash      string
	CatalogueGen       uint64
	PinnedCount        int
	ActiveMCPCount     int
	DeferredCount      int
	PinnedTokens       int
	ActiveMCPTokens    int
	DeferredTokens     int
	DynamicActive      int
	DynamicLimit       int
	EvictionCount      int
	Recent             []ToolActivationDiagnostic
	RecentEvictions    []ToolEvictionDiagnostic
	Servers            []ToolDiscoveryServerDiagnostic
	ResetReason        string
}

ToolDiscoveryDiagnostics is a provider-neutral inspect projection.

type ToolDiscoveryOutput added in v0.0.388 

type ToolDiscoveryOutput struct {
	CallID        string           `json:"call_id"`
	CatalogueHash string           `json:"catalogue_hash"`
	CatalogueGen  uint64           `json:"catalogue_generation"`
	Tools         []DiscoveredTool `json:"tools"`
}

ToolDiscoveryOutput pairs trusted schemas with one native discovery call.

type ToolDiscoveryServerDiagnostic added in v0.0.388 

type ToolDiscoveryServerDiagnostic struct {
	Name         string
	ResolvedMode string
	Total        int
	Pinned       int
	Active       int
	Deferred     int
}

ToolDiscoveryServerDiagnostic reports the effective surface for one MCP server.

type ToolDiscoverySurfaceInspector added in v0.0.391 

type ToolDiscoverySurfaceInspector interface {
	ActiveToolSpecs(sessionID string) []ToolSpec
}

ToolDiscoverySurfaceInspector exposes the MCP schemas currently active for a durable session. Deferred catalogue entries that have not been loaded are not included.

type ToolEvictionDiagnostic added in v0.0.392 

type ToolEvictionDiagnostic struct {
	Name     string
	Reason   string
	Executed bool
}

ToolEvictionDiagnostic records a dynamic tool removed from the visible working set.

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 CLI bridge providers to receive synchronous tool 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 (for example, local CLI providers 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"`
	Width     int    `json:"width,omitempty"`
	Height    int    `json:"height,omitempty"`
}

ToolImageData represents base64-encoded image data in user input or tool output.

type ToolNamespaceIdentity added in v0.0.388 

type ToolNamespaceIdentity struct {
	Name        string `json:"name"`
	ChildName   string `json:"child_name"`
	Description string `json:"description,omitempty"`
}

ToolNamespaceIdentity carries an explicit provider-neutral namespace route for a callable tool. Name and ChildName are model-visible native identities; ToolSpec.Name remains the canonical flattened executable name used by the registry and function-only providers.

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"` // Persisted attributed changes only
	FilesystemObservations []FilesystemObservationSummary `json:"filesystem_observations,omitempty"`
	OutputClaimDiagnostics []OutputClaimDiagnostic        `json:"output_claim_diagnostics,omitempty"`
	GuardianReviews        []GuardianReview               `json:"guardian_reviews,omitempty"` // Display-only Guardian audit metadata; never provider content
	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) AllSpecsIncludingDeferred added in v0.0.388 

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

AllSpecsIncludingDeferred returns every executable tool spec for diagnostics and discovery planning, regardless of provider visibility.

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) IsVisible added in v0.0.388 

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

IsVisible reports whether a registered tool is included by AllSpecs.

func (*ToolRegistry) Register added in v0.0.10 

func (r *ToolRegistry) Register(tool Tool)

Register makes a tool executable and provider-visible.

func (*ToolRegistry) RegisterDeferred added in v0.0.388 

func (r *ToolRegistry) RegisterDeferred(tool Tool)

RegisterDeferred makes a tool executable without exposing its schema through AllSpecs.

func (*ToolRegistry) SetVisibility added in v0.0.388 

func (r *ToolRegistry) SetVisibility(name string, visible bool) bool

SetVisibility changes provider visibility without affecting execution lookup.

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
	GuardianReviews []GuardianReview  `json:"guardian_reviews,omitempty"` // Display-only Guardian audit metadata
	IsError         bool              // True if this result represents a tool execution error
	Caller          string            `json:",omitempty"` // PTC caller provenance.
	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{}
	// Namespace is optional provider-neutral identity metadata. Portable and
	// function-only providers continue to use Name; native namespace-capable
	// adapters may expose ChildName under the explicit namespace.
	Namespace *ToolNamespaceIdentity `json:",omitempty"`
	// 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
	AllowedCallers []string               // Immutable caller allow-list (for example, "programmatic").
	OutputSchema   map[string]interface{} // Optional structured output schema for PTC callers.
}

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 registered tool specs for a request, filtering out search tools when searchEnabled is false. When search is enabled, Engine normalizes the full list: native-capable providers have external web_search and read_url removed, while other providers retain or receive them.

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 ToolSurfacePlanner added in v0.0.388 

type ToolSurfacePlanner interface {
	BeginRun(ctx context.Context, provider Provider, req *Request, runID string) (resetReason string, err error)
	PrepareTurn(ctx context.Context, provider Provider, req *Request, runID string, attempt, maxTurns int) (resetReason string, err error)
	EndRun(runID string)
	ResetSession(sessionID string)
	ToolExecuted(sessionID, runID, name string)
	CanActivateDeferredTool(name string) bool
	AllowsPlannerTool(runID, name string) bool
	ResolveProviderToolCall(runID string, call ToolCall) (ToolCall, error)
}

ToolSurfacePlanner owns provider visibility for dynamically discoverable tools. Implementations must not change a surface during an in-flight provider stream.

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
}

UserFacingProviderError keeps detailed subprocess diagnostics available to debug logging while presenting a concise error to users.

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 and reasoning-effort metadata from the shared OpenCode catalog.

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.