customization

type Clock ¶

type Clock struct {
	Now time.Time
}

Clock is the raw source-owned time fact. A submitted value is preserved until the source refreshes it; templates and future commands observe the same value.

type Command ¶

type Command struct {
	Path string
	Args []string
	// PassthroughEnv names additional parent environment variables explicitly
	// allowed into the command's otherwise fixed environment.
	PassthroughEnv []string
	LaunchDir      string
	// RefreshInterval optionally refreshes an otherwise idle command. Values below
	// one second are disabled; input changes still use the command debounce.
	RefreshInterval time.Duration
	// contains filtered or unexported fields
}

Command is a validated local status command. Path is an absolute executable and Args are passed literally. LaunchDir remains private command-runner state and is never projected into Input.

func (c Command) Valid() bool

func (c Command) ValidatePassthroughEnv() error

type CommandDiagnostics ¶

type CommandDiagnostics struct {
	Header string
	Footer string
	Error  string
}

CommandDiagnostics is the safe, coarse status of the latest completed command. Its fields are closed vocabularies: Header/Footer are default, custom, or stale; Error is none, unsupported, timeout, output_limit, invalid_statusml, exit, or failed.

type CommandDiagnosticsSource ¶

type CommandDiagnosticsSource interface {
	CommandDiagnostics() CommandDiagnostics
}

CommandDiagnosticsSource is optionally implemented by command-backed sources. Template and default sources intentionally expose no command diagnostics.

type Context ¶

type Context struct {
	Used      ContextAtom
	Window    ContextAtom
	Percent   int
	Known     bool
	Estimated bool
}

Context describes current context-window consumption. Known reports whether Used reflects a known occupancy; Estimated reports whether that occupancy is an estimate. Percent is Used.Raw as an integer percentage of Window.Raw, or zero when the window or occupancy is unknown. The visual bar is renderer-owned because its glyphs and semantic style depend on the active theme and available surface width.

type ContextAtom ¶

type ContextAtom struct {
	Raw   int64
	Human string
}

ContextAtom carries an exact token count and its standard compact display notation. It is separate from UsageAtom to make the context-window contract explicit at call sites.

type Delegation ¶

type Delegation struct {
	Total          DelegationStateCounts
	DirectSubagent DelegationStateCounts
	TeamMember     DelegationStateCounts
	ParallelBranch DelegationStateCounts
	Subagents      DelegationSummary
	Parallel       DelegationSummary
	Team           LiveTeam
}

Delegation groups the uniform state counts by flat leaf unit. Total is the component-wise sum of direct subagent, team member, and parallel branch.

func (d Delegation) Valid() bool

type DelegationStateCounts ¶

type DelegationStateCounts struct {
	Running          int
	AwaitingApproval int
	Completed        int
	Failed           int
	Cancelled        int
	Stopped          int
}

DelegationStateCounts classifies delegated leaf work into mutually exclusive terminal and live states.

type DelegationSummary ¶

type DelegationSummary struct {
	Running  int
	Finished int
}

DelegationSummary is the display-oriented running/finished projection of one leaf family. Finished deliberately collapses the detailed terminal states; raw DelegationStateCounts remains available for command handlers.

type Document ¶

type Document struct {
	Header Surface
	Footer Surface
}

Document is a parsed StatusML document. Header and Footer are independently optional through their Present fields.

func Render(markup string, palette Palette) Document

type Input ¶

type Input struct {
	Version    uint8
	Server     ServerTarget
	Session    Session
	Model      Model
	Usage      Usage
	Context    Context
	Workspace  Workspace
	Terminal   Terminal
	MainAgent  MainAgent
	Delegation Delegation
	Clock      Clock
}

Input is the canonical, raw snapshot supplied to status handlers. It is intentionally a small allowlist: it carries display-safe session facts, never prompts, transcript/tool content, credentials, authentication metadata, diagnostics, or raw command output.

Commands receive this exact data as JSON. Template rendering receives a private, StatusML-escaped projection so template interpolation cannot create markup or terminal controls. The raw input remains available to commands for ordinary display-safe status data.

Renderer policy—clipping, safety/activity lanes, and context-bar glyph/style selection—does not belong here. Header and footer available widths are facts computed after those renderer reservations.

type LinkPalette ¶

type LinkPalette interface {
	StatusLinkColor() string
	StatusLinkUnderline() bool
}

LinkPalette is an optional theme extension for StatusML links. The UI renderer uses the separately validated destination when emitting terminal output.

type LiveTeam ¶

type LiveTeam struct {
	ID      string
	Working int
	Total   int
}

LiveTeam is present only while a team is active. Completed teams intentionally disappear from the footer, unlike parallel and direct-subagent summaries.

type MainAgent ¶

type MainAgent struct {
	State    string
	Activity string
	Approval string
}

MainAgent carries the main agent's display-safe activity. State is one of "connecting", "idle", "thinking", "running_tool", "awaiting_approval", "completed", "failed", or "cancelled". Activity is a bounded display label. Approval is "none" or "awaiting" and reflects whether a human verdict is pending.

type Model ¶

type Model struct {
	ProviderID    string
	ID            string
	ProviderLabel string
	FriendlyName  string
	Route         string
	ContextWindow ContextAtom
}

Model carries the provider-independent model facts selected for the session. ProviderID and ID are opaque routing identifiers. ProviderLabel is the resolved provider/model identity for display (or the raw model ID when the provider is unknown); FriendlyName is the inventory name, falling back to ID. Route is an observed downstream route, not part of the model identity. ContextWindow is the resolved model context capacity, not current session consumption.

type Palette ¶

type Palette interface {
	StatusColor(Token) string
}

Palette resolves a StatusML semantic token through the active theme. It returns descriptive style data, never terminal control sequences.

type PassthroughEnvError ¶

type PassthroughEnvError struct {
	ReservedName string
}

PassthroughEnvError reports an invalid passthrough environment name. ReservedName is empty when the value does not match the supported environment-name grammar.

func (e *PassthroughEnvError) Error() string

type Result ¶

type Result struct {
	Header Surface
	Footer Surface
}

Result holds independently selected semantic surfaces. It never contains terminal rendering or control sequences.

type ServerTarget ¶

type ServerTarget struct {
	// DisplayTarget is the credential-free connection target shown in chrome.
	DisplayTarget  string
	ConnectionMode string
}

ServerTarget identifies the display target and connection mode, without any authentication or endpoint credential data. ConnectionMode is one of "embedded" (the local in-process server) or "connect" (an explicitly dialed server); an empty value means the mode is not yet known.

type Session ¶

type Session struct {
	Title           string
	Handle          string
	Mode            string
	ReasoningEffort string
}

Session carries optional user-facing session facts. Title is empty when no custom or generated title exists. Handle is the short displayed session prefix used by ordinary mecatui presentation. Mode is the active permission mode. ReasoningEffort is either empty (unset or unsupported) or one of "low", "medium", "high", "xhigh", or "max".

type Source ¶

type Source interface {
	Submit(Input)
	Changed() <-chan struct{}
	Latest() Result
	Close(context.Context) error
}

Source produces the latest semantic status-line surfaces from raw display facts. It is UI-agnostic: Changed is a wake-up edge, never a queue.

func NewCommandSource(command Command) Source

func NewDefaultSource(refreshInterval time.Duration) Source

func NewTemplateSource(templates TemplateSet, interval time.Duration) Source

type Span ¶

type Span struct {
	Text      string
	Token     Token
	Color     string
	Href      string
	Underline bool
}

Span is one terminal-safe text run resolved through a Palette. Href is a separately validated link destination and is never included in Text.

type Surface ¶

type Surface struct {
	Present bool
	Spans   []Span
}

Surface is an optional header or footer. Present distinguishes an absent surface from a present empty one. The renderer determines alignment by surface: headers are left-aligned and footers are right-aligned.

type SurfaceTemplates ¶

type SurfaceTemplates struct{ Full, Compact, Minimal string }

SurfaceTemplates contains the three independently selected variants for one surface. Empty variants fall back to the corresponding shipped variant.

type TemplateSet ¶

type TemplateSet struct{ Header, Footer SurfaceTemplates }

TemplateSet provides independent header and footer variant sets.

type Terminal ¶

type Terminal struct {
	Rows            int
	Cols            int
	HeaderAvailCols int
	FooterAvailCols int
	Emoji           bool
}

Terminal provides measured dimensions and independently reserved columns for status surfaces. Cols is the full terminal width. HeaderAvailCols and FooterAvailCols are the widths remaining after the renderer reserves mandatory header safety/navigation and footer activity lanes, respectively. Emoji reports whether the terminal is likely to render emoji presentation (for example ⚡️) at its expected width; it is a conservative, environment-based guess fixed for the process.

type TitleRenderer ¶

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

TitleRenderer renders a plain-text title from the display-safe status input. It deliberately has no StatusML parsing or command-source integration.

func NewTitleRenderer(source string) (*TitleRenderer, error)

func (r *TitleRenderer) Render(input Input) (string, error)

type Token ¶

type Token string

Token is a closed semantic style vocabulary for StatusML text.

const (
	TokenText      Token = "text"
	TokenMuted     Token = "muted"
	TokenPrimary   Token = "primary"
	TokenSecondary Token = "secondary"
	TokenAccent    Token = "accent"
	TokenSuccess   Token = "success"
	TokenWarning   Token = "warning"
	TokenError     Token = "error"
	TokenInfo      Token = "info"
	// TokenDanger renders as the filled, theme-independent alarm pill (the yolo
	// mode marker) rather than a foreground colour.
	TokenDanger Token = "danger"
)

type Usage ¶

type Usage struct {
	Input            UsageAtom
	Output           UsageAtom
	CacheRead        UsageAtom
	CacheWrite       UsageAtom
	CacheReadPercent int
}

Usage is the cumulative session usage summary. CacheRead is input served from the prompt cache (a subset of Input); CacheWrite is input written to the prompt cache. CacheReadPercent is the integer percentage CacheRead.Raw/Input.Raw, or zero when the input count is zero.

type UsageAtom ¶

type UsageAtom struct {
	Raw   int64
	Human string
}

UsageAtom carries an exact non-negative token count and the same count rendered with the standard compact display notation (for example, "1.1M"). Raw is for arithmetic or command handlers; Human is a display-ready atom.

type Workspace ¶

type Workspace struct {
	Location string
	Name     string
	Path     string
}

Workspace is the active session workspace's display-safe provenance. Location is "local", "remote", or "unknown". Name is provider-supplied display metadata, not a filesystem basename. Path is supplied to status templates through their StatusML-escaped projection and to a direct local status command after the privileged local-context RPC has returned an eligible local root. It is otherwise empty and is not part of universal client projections.