detect

Documentation

Overview

Package detect probes the host environment for available LLM credentials and CLI binaries, producing a Report consumed by the studio (UI hints) and the runtime resolver (auto backend selection).

Index

• Constants
• Variables
• func CommonBinaryCandidates(name string) []string
• func PreferenceFromEnv() []string
• func Resolve(prefOrder []string, backends []BackendStatus) string
• func SuggestedModel(backend string, providers []ProviderStatus) string
• type BackendStatus
• type CachedDetector
  • func NewCachedDetector(ttl time.Duration) *CachedDetector
  • func (c *CachedDetector) Get(ctx context.Context) Report
  • func (c *CachedDetector) Invalidate()
• type ProviderStatus
• type Report
  • func Detect(ctx context.Context) Report

Constants

const (
	BackendClaudeCode = "claude_code"
	BackendCodex      = "codex"
	BackendClaw       = "claw"
)

Backend names. Values must stay in sync with the delegate.Backend* constants — kept as plain strings here so the dsl/ir compiler can import detect without pulling in delegate (and its transitive deps).

const (
	AuthOAuth  = "oauth"
	AuthAPIKey = "api_key"
	AuthNone   = "none"
)

Auth kinds.

Variables

var DefaultPreferenceOrder = []string{BackendClaudeCode, BackendClaw}

DefaultPreferenceOrder is the compiled-in fallback order. codex is intentionally absent — explicit opt-in only.

Functions

func CommonBinaryCandidates

func CommonBinaryCandidates(name string) []string

CommonBinaryCandidates is a thin re-export of clilocate.CommonBinaryCandidates so external callers (notably iterion-desktop's CLI probe at cmd/iterion-desktop/external_cli.go, which cannot reach pkg/internal/...) get the same fallback list.

func PreferenceFromEnv

func PreferenceFromEnv() []string

PreferenceFromEnv parses ITERION_BACKEND_PREFERENCE (CSV). Returns DefaultPreferenceOrder when the env var is unset / empty.

func Resolve

func Resolve(prefOrder []string, backends []BackendStatus) string

Resolve picks the first backend in prefOrder that has Available=true in the given backends list. Returns "" when nothing matches.

func SuggestedModel

func SuggestedModel(backend string, providers []ProviderStatus) string

SuggestedModel returns the suggested model spec for a given backend, based on the providers currently available. Returns "" when the backend is CLI-managed (claude_code / codex) or no provider matches.

Types

type BackendStatus

type BackendStatus struct {
	Name      string   `json:"name"`
	Available bool     `json:"available"`
	Auth      string   `json:"auth"`
	Sources   []string `json:"sources"`
	Hints     []string `json:"hints,omitempty"`
}

BackendStatus describes a single delegate backend.

type CachedDetector

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

CachedDetector wraps Detect with a TTL cache. Used by the HTTP server (30s TTL) and by the runtime executor (longer TTL on first call).

func NewCachedDetector

func NewCachedDetector(ttl time.Duration) *CachedDetector

NewCachedDetector returns a detector with the given TTL. A zero ttl disables expiry (useful for tests).

func (*CachedDetector) Get

func (c *CachedDetector) Get(ctx context.Context) Report

Get returns the cached report, refreshing if past TTL.

func (*CachedDetector) Invalidate

func (c *CachedDetector) Invalidate()

Invalidate forces a refresh on the next Get.

type ProviderStatus

type ProviderStatus struct {
	Name      string `json:"name"`
	Available bool   `json:"available"`
	// Source is the credential that will actually be used at runtime.
	// For providers with a single auth path, this is "ENV_VAR_NAME". For
	// providers that admit multiple paths (e.g. OpenAI: API key + ChatGPT
	// OAuth), it is the winner; the others are surfaced via
	// OverriddenSources so the UI can render them struck-through.
	Source         string `json:"source"`
	SuggestedModel string `json:"suggested_model,omitempty"`
	// OverriddenSources lists detected credentials for this provider
	// that are present but will NOT be used because Source takes
	// precedence. Each entry is a free-form human-readable label
	// (e.g. "OPENAI_API_KEY (overridden by ChatGPT-OAuth)").
	OverriddenSources []string `json:"overridden_sources,omitempty"`
}

ProviderStatus describes a claw-driven provider.

type Report

type Report struct {
	// PreferenceOrder is the effective order used when resolving "auto".
	// Default ["claude_code", "claw"]; codex is intentionally absent so it
	// is never auto-selected (matches the C030 discouraged stance).
	PreferenceOrder []string `json:"preference_order"`
	// ResolvedDefault is the first available backend in PreferenceOrder,
	// or "" when none are available.
	ResolvedDefault string `json:"resolved_default"`
	// Backends lists status for the three delegate backends.
	Backends []BackendStatus `json:"backends"`
	// Providers lists claw provider availability (anthropic, openai, …).
	Providers []ProviderStatus `json:"providers"`
}

Report is the snapshot returned by Detect. The shape is mirrored in studio/src/api/backends.ts.

func Detect

func Detect(ctx context.Context) Report

Detect runs the probes synchronously. ctx is honored for timed probes: most are local stat / env reads, but the claude_code fallback may shell out to `claude auth status --json` (3 s timeout) when no credentials file is present. Results are cached by CachedDetector, so the subprocess runs at most once per TTL window.