provider

package
v0.14.0 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FormatHealth added in v0.7.0

func FormatHealth(sh SystemHealth) string

FormatHealth renders SystemHealth as a human-readable string.

func KillLocalAgent added in v0.7.0

func KillLocalAgent(a agent.Agent) error

KillLocalAgent sends SIGTERM to the agent's process tree, waits 3 seconds, then SIGKILL if still alive. Also kills the associated tmux session if one exists. Used by all local providers (Claude, Codex). Remote providers (e.g., Kubernetes) should implement their own Kill method.

func LiveOf added in v0.14.0

func LiveOf(ps []Provider, ttl time.Duration) []harness.LiveSessions

LiveOf is the harness.LiveSessions of every provider in ps that is a LiveSource, in order, each read with ttl: the state service's holders for the TUI and the dashboard.

Types

type Claude

type Claude struct {
	// ProjectsDir is where the session store reads transcripts
	// (SessionFile, Fingerprint); "": ~/.claude/projects.
	ProjectsDir string
	// RegistryDir is Claude Code's session registry that LiveSessions
	// reads; "": ~/.claude/sessions.
	RegistryDir string
	// contains filtered or unexported fields
}

Claude is a Provider implementation for the Claude Code CLI.

func (*Claude) CanEmbed

func (c *Claude) CanEmbed() bool

CanEmbed returns true because Claude's TUI works inside an embedded PTY.

func (*Claude) Discover

func (c *Claude) Discover() ([]agent.Agent, error)

Discover finds all running Claude Code processes, then enriches each agent with CWD, tmux session, session JSONL data, and estimated cost. SDK-spawned agents sharing the same directory and model are grouped into single entries.

func (*Claude) DiscoverWithSnapshot added in v0.8.1

func (c *Claude) DiscoverWithSnapshot(snap *discovery.Snapshot) ([]agent.Agent, error)

DiscoverWithSnapshot uses a shared ps/tmux snapshot instead of running its own subprocess calls.

func (*Claude) FindSessionFile

func (c *Claude) FindSessionFile(a agent.Agent) string

FindSessionFile resolves the session/trace file for a Claude agent. It first tries the session ID lookup, then falls back to finding the newest JSONL in the agent's working directory.

func (*Claude) Fingerprint added in v0.14.0

func (c *Claude) Fingerprint(id string) string

Fingerprint is the transcript's size and modification time, or "" when session id has none.

func (*Claude) LiveSessions added in v0.14.0

func (c *Claude) LiveSessions(ttl time.Duration) harness.LiveSessions

LiveSessions reads Claude Code's session registry under RegistryDir, or ~/.claude/sessions, caching a read for ttl (discovery.LiveCache). One reader per ttl, made on first use and kept: discovery reads the registry through the LiveTTL one (liveCache), so a refresh reads it and runs ps once.

func (*Claude) Name

func (c *Claude) Name() string

func (*Claude) OTELEnv

func (c *Claude) OTELEnv(endpoint string) string

OTELEnv returns env vars to enable Claude Code's OTEL tracing. Sets both generic and signal-specific endpoints with explicit paths to avoid OTEL SDK path-appending issues across different Node.js SDK versions. Uses http/protobuf protocol (port 4318).

func (*Claude) OTELServiceName added in v0.5.0

func (c *Claude) OTELServiceName() string

func (*Claude) ParseTail added in v0.14.0

func (c *Claude) ParseTail(path string, n int) ([]trace.Turn, error)

ParseTail returns at least the last n turns of the transcript at path, reading only the end of the file (ParseTraceTail).

func (*Claude) ParseTrace

func (c *Claude) ParseTrace(filePath string) ([]trace.Turn, error)

ParseTrace reads a Claude JSONL session file and parses it into trace turns.

func (*Claude) ParseTraceTail added in v0.14.0

func (c *Claude) ParseTraceTail(filePath string, n int) ([]trace.Turn, error)

ParseTraceTail returns at least the last n turns of a session (all of them if it has fewer), reading only as much of the end of the file as needed: session files grow to hundreds of MB. Turn numbers count from the start of the part read, not of the session.

func (*Claude) RecentDirs

func (c *Claude) RecentDirs(max int) []RecentDir

RecentDirs returns recently-used project directories from Claude's session history (~/.claude/projects/). Each subdirectory is a dir-key (the encoded working directory path). The newest .jsonl in each subdirectory determines LastUsed.

func (*Claude) Reread added in v0.14.0

func (c *Claude) Reread(s history.Session) (history.Session, error)

Reread is one session's record read again (history.Reread), so the session catalog can refresh one session without a full scan.

func (*Claude) ResumeCommand

func (c *Claude) ResumeCommand(a agent.Agent) *exec.Cmd

func (*Claude) SessionCwd added in v0.14.0

func (c *Claude) SessionCwd(path string) (string, error)

SessionCwd is the first working directory the transcript records (history.SessionCwd, the session list's rule).

func (*Claude) SessionFile added in v0.14.0

func (c *Claude) SessionFile(id string) string

SessionFile is session id's transcript under the projects dir, or "".

func (*Claude) Sessions added in v0.14.0

func (c *Claude) Sessions(opts history.DiscoverOpts) ([]history.Session, error)

Sessions lists the transcripts under the projects dir (history.Discover); opts.Provider other than Claude's lists none.

func (*Claude) SpawnArgs

func (c *Claude) SpawnArgs() SpawnArgs

SpawnArgs returns the available models and modes for launching Claude.

func (*Claude) SpawnCommand

func (c *Claude) SpawnCommand(dir, model, mode string) *exec.Cmd

SpawnCommand builds the exec.Cmd to launch a new Claude session.

Flags:

  • --model <model> if model is set and not "default"
  • --dangerously-skip-permissions if mode == "bypass"
  • --permission-mode plan if mode == "plan"

func (*Claude) SubagentAttrKeys added in v0.5.0

func (c *Claude) SubagentAttrKeys() subagent.AttrKeys

SubagentAttrKeys returns the OTEL attribute names Claude uses for subagent identity.

func (*Claude) TranscriptsDir added in v0.14.0

func (c *Claude) TranscriptsDir() string

TranscriptsDir is ProjectsDir, or ~/.claude/projects (the relative .claude/projects when the home directory is unknown).

type Codex

type Codex struct{}

Codex is a Provider implementation for the OpenAI Codex CLI.

func (*Codex) CanEmbed

func (c *Codex) CanEmbed() bool

CanEmbed returns false — Codex's TUI hangs inside an embedded PTY even with --no-alt-screen. Use trace view + J to jump out instead.

func (*Codex) Discover

func (c *Codex) Discover() ([]agent.Agent, error)

Discover finds running Codex CLI processes and recent session files. Running processes are discovered via ps; recent sessions (last 24h) without a running process are shown as idle so they can be resumed.

func (*Codex) DiscoverWithSnapshot added in v0.8.1

func (c *Codex) DiscoverWithSnapshot(snap *discovery.Snapshot) ([]agent.Agent, error)

DiscoverWithSnapshot uses a shared ps/tmux snapshot.

func (*Codex) FindSessionFile

func (c *Codex) FindSessionFile(a agent.Agent) string

FindSessionFile resolves the session/trace file for a Codex agent. Returns "" if the agent has no WorkingDir or if the session file is stale (not modified in the last 24 hours).

func (*Codex) Name

func (c *Codex) Name() string

func (*Codex) OTELEnv

func (c *Codex) OTELEnv(endpoint string) string

OTELEnv returns env vars to enable Codex CLI's OTEL tracing. Codex exports both traces (session spans) and log events.

func (*Codex) OTELServiceName added in v0.5.0

func (c *Codex) OTELServiceName() string

func (*Codex) ParseTrace

func (c *Codex) ParseTrace(filePath string) ([]trace.Turn, error)

ParseTrace reads a Codex JSONL session file and parses it into trace turns.

func (*Codex) RecentDirs

func (c *Codex) RecentDirs(max int) []RecentDir

RecentDirs returns recently-used project directories from Codex's session history (~/.codex/sessions/). Scans recursively for .jsonl files from the last 30 days, reads session_meta for CWD, deduplicates by path, sorts by newest first, and caps at max.

func (*Codex) ResumeCommand

func (c *Codex) ResumeCommand(a agent.Agent) *exec.Cmd

func (*Codex) SpawnArgs

func (c *Codex) SpawnArgs() SpawnArgs

SpawnArgs returns the available models and modes for launching Codex.

func (*Codex) SpawnCommand

func (c *Codex) SpawnCommand(dir, model, mode string) *exec.Cmd

SpawnCommand builds the exec.Cmd to launch a new Codex session.

Flags:

  • --no-alt-screen always
  • --model <model> if model is set and not "default"
  • --full-auto if mode == "full-auto"
  • --sandbox workspace-write if mode is empty or "default"

func (*Codex) SubagentAttrKeys added in v0.5.0

func (c *Codex) SubagentAttrKeys() subagent.AttrKeys

SubagentAttrKeys returns zero AttrKeys — Codex doesn't support subagent tracking.

type HealthStatus added in v0.7.0

type HealthStatus struct {
	Configured bool
	CoordOK    bool
	CoordErr   string
	ComputeOK  bool
	ComputeErr string
	Workloads  []string
}

HealthStatus represents the readiness of an infrastructure backend. Used by health.go for system health reporting.

type K8s added in v0.7.0

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

K8s is a Provider implementation for Kubernetes-hosted AI agents. Infrastructure operations (Discover, Kill, Spawn, Health) have moved to environment.K8sEnvironment. This provider retains identity methods and ParseTrace (which reads Redis task history).

func NewK8s added in v0.7.0

func NewK8s(cfg K8sConfig) *K8s

NewK8s constructs a K8s provider with the given configuration.

func (*K8s) CanEmbed added in v0.7.0

func (k *K8s) CanEmbed() bool

CanEmbed returns false — K8s agents run in pods and cannot be embedded as a local PTY.

func (*K8s) Close added in v0.7.0

func (k *K8s) Close()

Close shuts down the shared Redis client if one was created.

func (*K8s) Discover added in v0.7.0

func (k *K8s) Discover() ([]agent.Agent, error)

Discover returns nil — discovery has moved to K8sEnvironment. Kept to satisfy the Provider interface until Task 1.6 wires environment-based discovery into the orchestrator.

func (*K8s) FindSessionFile added in v0.7.0

func (k *K8s) FindSessionFile(a agent.Agent) string

FindSessionFile returns a "k8s://<sessionID>" sentinel so the trace pane can pass it to ParseTrace, which uses it to query Redis task history.

func (*K8s) Name added in v0.7.0

func (k *K8s) Name() string

Name returns the provider identifier used in config and display.

func (*K8s) OTELEnv added in v0.7.0

func (k *K8s) OTELEnv(_ string) string

OTELEnv returns "" — K8s agents configure their own OTEL settings via pod environment variables managed outside aimux.

func (*K8s) OTELServiceName added in v0.7.0

func (k *K8s) OTELServiceName() string

OTELServiceName returns the service.name for K8s agents in OTEL telemetry.

func (*K8s) ParseTrace added in v0.7.0

func (k *K8s) ParseTrace(filePath string) ([]trace.Turn, error)

ParseTrace reads completed task history from Redis using the agentID encoded in filePath as "k8s://<agentID>".

func (*K8s) RecentDirs added in v0.7.0

func (k *K8s) RecentDirs(_ int) []RecentDir

RecentDirs returns nil — K8s agents do not work on local directories.

func (*K8s) ResumeCommand added in v0.7.0

func (k *K8s) ResumeCommand(_ agent.Agent) *exec.Cmd

ResumeCommand returns nil. K8s agents cannot be resumed as local processes.

func (*K8s) SpawnArgs added in v0.7.0

func (k *K8s) SpawnArgs() SpawnArgs

SpawnArgs describes the models and modes available when launching a K8s agent.

func (*K8s) SpawnCommand added in v0.7.0

func (k *K8s) SpawnCommand(_, _, _ string) *exec.Cmd

SpawnCommand returns nil — K8s agents are not spawned locally.

func (*K8s) SubagentAttrKeys added in v0.7.0

func (k *K8s) SubagentAttrKeys() subagent.AttrKeys

SubagentAttrKeys returns zero value — K8s agents do not emit subagent identity attributes in the format aimux's OTEL receiver understands.

type K8sConfig added in v0.7.0

type K8sConfig struct {
	RedisURL   string // e.g. "redis://:pass@localhost:6380"
	TeamID     string // e.g. "my-team"
	Namespace  string // K8s namespace, e.g. "agents"
	Kubeconfig string // path to kubeconfig; empty = in-cluster or KUBECONFIG env
}

K8sConfig holds connection settings for the Kubernetes provider. All fields may be populated from ~/.aimux/config.yaml under the "kubernetes" key.

type LiveSource added in v0.14.0

type LiveSource interface {
	LiveSessions(ttl time.Duration) harness.LiveSessions
}

LiveSource is the optional capability of a provider whose harness records which processes hold a session; ttl is the reader's cache time.

type Provider

type Provider interface {
	Name() string
	Discover() ([]agent.Agent, error)
	ResumeCommand(a agent.Agent) *exec.Cmd

	// CanEmbed returns true if the agent's TUI can run inside an
	// embedded PTY (split view). False means trace-only view with
	// jump-out for interaction.
	CanEmbed() bool

	// FindSessionFile resolves the session/trace file for an agent.
	// Each provider knows its own storage layout. Returns "" if none found.
	FindSessionFile(a agent.Agent) string

	// RecentDirs returns recently-used project directories from this
	// provider's session history, sorted by most recent first.
	RecentDirs(max int) []RecentDir

	// SpawnCommand builds the exec.Cmd to launch a new agent session
	// in the given directory with the specified model and mode.
	SpawnCommand(dir, model, mode string) *exec.Cmd

	// SpawnArgs returns the available models and modes for the launcher UI.
	SpawnArgs() SpawnArgs

	// ParseTrace reads a session/trace file and parses it into a
	// provider-specific structured trace. Each provider knows its own
	// log format (Claude JSONL, Codex JSONL).
	ParseTrace(filePath string) ([]trace.Turn, error)

	// OTELEnv returns the shell env var prefix needed to enable OTEL
	// tracing for this provider, pointing at the given endpoint.
	// Each provider knows its own OTEL activation mechanism.
	OTELEnv(endpoint string) string

	// OTELServiceName returns the service.name value this provider
	// emits in OTEL resource attributes (e.g. "claude-code").
	OTELServiceName() string

	// SubagentAttrKeys returns the OTEL attribute names this provider
	// uses for subagent identity. Return zero AttrKeys if the provider
	// doesn't support subagent tracking.
	SubagentAttrKeys() subagent.AttrKeys
}

Provider discovers and manages AI CLI agents of a specific type. Adding a new provider requires only implementing this interface and registering in app.go NewApp() — no other files need changes.

type ProviderHealth added in v0.7.0

type ProviderHealth struct {
	Name       string        // e.g. "claude", "k8s"
	Kind       string        // "local" or "infra"
	BinaryPath string        // resolved path to the binary (local only)
	BinaryOK   bool          // true if binary is found in PATH
	Version    string        // binary version string (local only)
	Agents     int           // number of currently active agents
	Infra      *HealthStatus // infra health details (infra only, nil for local)
}

ProviderHealth describes the health of a single provider.

type RecentDir

type RecentDir struct {
	Path     string
	LastUsed time.Time
}

RecentDir is a recently-used project directory from a provider's session history.

type Registry added in v0.14.0

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

Registry is the one place providers are built. Every frontend and command takes its providers from it, so the set and its order are defined once. Each provider is built once per Registry: Local, Enabled and ByName return the same instances.

func NewRegistry added in v0.14.0

func NewRegistry(home string, cfg config.Config) *Registry

NewRegistry builds the providers. home is the user's home directory that Claude Code's files sit under (~/.claude/projects, ~/.claude/sessions); "" leaves the provider's own defaults, which resolve the home directory when used. cfg decides which providers Enabled returns and whether the Kubernetes provider exists.

func (*Registry) ByName added in v0.14.0

func (r *Registry) ByName(name string) Provider

ByName is the provider called name, enabled or not, or nil when the registry has none (Kubernetes exists only when active).

func (*Registry) Enabled added in v0.14.0

func (r *Registry) Enabled() []Provider

Enabled is the TUI's set: the local providers, then Kubernetes when it is active, keeping only those cfg.IsProviderEnabled allows, in that order.

func (*Registry) Local added in v0.14.0

func (r *Registry) Local() []Provider

Local is the local CLI providers, Claude then Codex, whatever the config says: process discovery, trace parsers and recent dirs outside the TUI use every one of them.

type RemoteHealthConfig added in v0.13.0

type RemoteHealthConfig struct {
	Backend string // "openshell" or ""
	Gateway string // gateway endpoint URL
}

RemoteHealthConfig carries enough info to check OpenShell gateway health without importing the config package.

type Role

type Role int

Role identifies who produced a conversation segment.

const (
	RoleUser Role = iota
	RoleAssistant
	RoleTool
	RoleSystem
)

func (Role) String

func (r Role) String() string

type Segment

type Segment struct {
	Time    time.Time
	Role    Role
	Content string
	Tool    string // tool name if Role==RoleTool
	Detail  string // e.g., file path, command snippet
}

Segment is a single conversation turn, provider-agnostic.

type SpawnArgs

type SpawnArgs struct {
	Models []string // e.g., ["default", "opus", "sonnet", "haiku"]
	Modes  []string // e.g., ["default", "bypass", "plan"]
}

SpawnArgs describes the available options for launching a new agent.

type SystemHealth added in v0.7.0

type SystemHealth struct {
	Providers []ProviderHealth
}

SystemHealth holds the health of all providers and infra.

func GatherHealth added in v0.7.0

func GatherHealth(providers []Provider, agentCounts map[string]int) SystemHealth

GatherHealth collects health from all providers. Each local provider's binary is checked via exec.LookPath. Agent counts come from the most recent discovery results.

func GatherHealthWithRemote added in v0.13.0

func GatherHealthWithRemote(providers []Provider, agentCounts map[string]int, remote RemoteHealthConfig) SystemHealth

GatherHealthWithRemote extends GatherHealth with OpenShell gateway status.

type TailParser added in v0.14.0

type TailParser interface {
	ParseTail(path string, n int) ([]trace.Turn, error)
}

TailParser is the optional capability of parsing only the end of a transcript: at least the last n turns, numbered from the part read.

type TranscriptRoot added in v0.14.0

type TranscriptRoot interface {
	TranscriptsDir() string
}

TranscriptRoot is the optional capability of a provider whose sessions are transcript files under one directory (the search index reads it).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL