app

package
v0.8.19 Latest Latest
Warning

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

 Go to latest Published: Oct 9, 2026 License: MIT Imports: 38 Imported by: 0

Documentation

Overview

Package app composes Relayer's configuration, PTY sessions, and terminal UI. Keeping this wiring separate lets both the canonical cmd/relayer entrypoint and the documented root compatibility entrypoint stay tiny.

Index

Constants

View Source 
const NoVersionProbeEnv = "RELAYER_NO_VERSION_CHECK"

NoVersionProbeEnv turns the probe off for every user of a machine, the way RELAYER_NO_UPDATE_CHECK turns off the desktop's release check. It is an environment variable and not a configuration key on purpose: the probe runs a child process on the host, which is a machine-level concern — an endpoint agent that flags process spawns, a network home directory, an air-gapped host — while config.yaml is per-project, strict-schema, and travels through version control. An administrator sets this once for the machine; nobody has to edit every project's file to get it.

Variables

View Source 
var ErrAuditVerificationFailed = errors.New("audit verification detected issues")
View Source 
var ErrCleanupUncertain = errors.New("desktop runtime cleanup not confirmed")

ErrCleanupUncertain marks a failed runtime start whose rollback could not prove that every partially started session was removed. Desktop controllers must quarantine the lifecycle and must not launch a candidate or rollback run while this sentinel is present.

View Source 
var ErrEmptyManualDecision = errors.New("a manual decision cannot be empty")

ApplyDecision resolves the canonical pending occurrence again immediately before encoding and delivery. This CAS boundary prevents a stale policy or UI result from acknowledging a newer prompt from the same session. ErrEmptyManualDecision reports a manual decision carrying no answer.

View Source 
var ErrPreflightBlocked = errors.New("relayer diagnostics detected a blocker")

ErrPreflightBlocked is returned only after a complete, display-safe doctor report has been written. Entrypoints use it to select a non-zero exit status without appending a second error message to the report.

View Source 
var ErrVersionProbeNotApplicable = errors.New("the version probe does not apply to this agent")

ErrVersionProbeNotApplicable is what an inspector returns for an agent it must not probe. The caller displays nothing, rather than a warning about a version nobody looked at.

Functions

func DefaultVersionInspector added in v0.8.18 

func DefaultVersionInspector(ctx context.Context, spec agent.Spec) (string, error)

DefaultVersionInspector runs "<argv[0]> --version" — the adapter's own executable, with none of the configured arguments — and reads the version from stdout.

func RegisterServeHandler added in v0.5.0 

func RegisterServeHandler(handler func(arguments []string, output io.Writer, diagnostics io.Writer) error)

RegisterServeHandler registers an external handler for the "serve" subcommand.

func Run 

func Run(arguments []string, diagnostics io.Writer) error

Run parses the public CLI, initializes the process owner and starts Bubble Tea. It never returns while sessions are still owned by the manager.

func RunPreflight 

func RunPreflight(ctx context.Context, options PreflightOptions) (preflight.Report, error)

RunPreflight builds the effective Relayer plan and inspects it without creating a configuration, opening an audit sink, constructing a terminal backend or starting an agent. Expected operational failures are represented by static checks rather than raw errors so presentation layers cannot leak configuration paths or user-controlled values.

func RunWithOutput 

func RunWithOutput(arguments []string, output io.Writer, diagnostics io.Writer) error

RunWithOutput is the canonical public CLI entry. Version output is kept separate from diagnostics and is handled before configuration, audit, or backend initialization.

Types

type AgentVersionInfo added in v0.8.18 

type AgentVersionInfo struct {
	InstalledVersion string
	Unverified       bool
	Reason           string
}

AgentVersionInfo stores the inspection result for an agent process.

func CheckAgentVersion added in v0.8.18 

func CheckAgentVersion(ctx context.Context, spec agent.Spec, resolvedAdapter string, simulated bool, inspector VersionInspector) AgentVersionInfo

CheckAgentVersion inspects and evaluates the version of one agent.

resolvedAdapter is the adapter the run resolved, not the one the configuration named: "command: [claude]" with no adapter resolves to the Claude adapter, and testing spec.Adapter left that agent without a warning. A simulated agent, a non-vendor adapter, and an agent whose argv[0] is not the adapter's own executable produce no information at all: nothing is run, and nothing is displayed.

type DesktopMetadata 

type DesktopMetadata struct {
	RunID            string        `json:"runID"`
	ConfigPath       string        `json:"configPath"`
	ConfigRevision   string        `json:"-"`
	Backend          string        `json:"backend"`
	PolicyAction     string        `json:"policyAction"`
	PolicyDryRun     bool          `json:"policyDryRun"`
	AuditEnabled     bool          `json:"auditEnabled"`
	AuditMode        string        `json:"auditMode"`
	AuditPath        string        `json:"auditPath,omitempty"`
	TelemetryEnabled bool          `json:"telemetryEnabled"`
	TelemetryProm    string        `json:"telemetryPrometheus,omitempty"`
	Configuration    bool          `json:"configurationCreated"`
	Notifications    notify.Config `json:"-"`
}

DesktopMetadata contains non-sensitive run settings suitable for a GUI.

type DesktopOptions 

type DesktopOptions struct {
	ConfigPath       string
	InitialSize      terminal.Size
	Diagnostics      io.Writer
	VersionInspector VersionInspector
}

DesktopOptions configures the headless runtime used by desktop frontends. It deliberately does not inherit the deprecated pane flags from the CLI.

type DesktopPlan 

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

DesktopPlan is an immutable, Go-only preflight result. Preparing a plan may read configuration and resolve executables, but it never opens audit files, terminal backends or child processes.

func PrepareDesktopRuntime 

func PrepareDesktopRuntime(options DesktopOptions) (*DesktopPlan, error)

PrepareDesktopRuntime performs every validation that can safely happen before an existing desktop run is stopped.

type DesktopRuntime 

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

DesktopRuntime owns one complete Relayer run without assuming a terminal UI. Consumers remain responsible for reducing Events and for never exposing free-form sensitive event fields.

func NewDesktopRuntime 

func NewDesktopRuntime(parent context.Context, options DesktopOptions) (*DesktopRuntime, error)

NewDesktopRuntime preserves the historical one-call API.

func StartDesktopRuntime 

func StartDesktopRuntime(parent context.Context, plan *DesktopPlan, runID string) (_ *DesktopRuntime, returnErr error)

StartDesktopRuntime starts an immutable preflight plan under the externally reserved identity shared by GUI events, tmux ownership and audit records.

func (*DesktopRuntime) AnsiOutput 

func (r *DesktopRuntime) AnsiOutput(sessionID string) (string, error)

func (*DesktopRuntime) ApplyDecision 

func (r *DesktopRuntime) ApplyDecision(
	ctx context.Context,
	sessionID string,
	event adapters.Event,
	decision adapters.Decision,
	manualInput string,
) error

func (*DesktopRuntime) BeginRestart 

func (r *DesktopRuntime) BeginRestart(ctx context.Context) error

BeginRestart is the stricter desktop transition used before another run is allowed to start. Unlike a normal application shutdown it explicitly stops every session, including tmux sessions configured to persist on exit. A non-nil result means cleanup is uncertain and callers must not start a replacement run.

func (*DesktopRuntime) BeginShutdown 

func (r *DesktopRuntime) BeginShutdown(ctx context.Context) error

BeginShutdown stops backend I/O while deliberately keeping the audit recorder open. Desktop frontends use this phase to unblock and join all in-flight decision goroutines before Close writes the final run records.

func (*DesktopRuntime) Close 

func (r *DesktopRuntime) Close(ctx context.Context) error

Close stops supervision, closes every owned backend and then closes audit. It is idempotent and preserves the first complete shutdown result.

func (*DesktopRuntime) Evaluate 

func (r *DesktopRuntime) Evaluate(event adapters.Event) policy.Evaluation

func (*DesktopRuntime) Events 

func (r *DesktopRuntime) Events() <-chan session.Event

func (*DesktopRuntime) MarkProcessExited added in v0.8.5 

func (r *DesktopRuntime) MarkProcessExited(agentID string) bool

MarkProcessExited records that an agent process terminated on its own. It reports whether the exit belongs to the agent's current process: false means a replacement is already running and the caller must not show it stopped.

func (*DesktopRuntime) Metadata 

func (r *DesktopRuntime) Metadata() DesktopMetadata

func (*DesktopRuntime) Output 

func (r *DesktopRuntime) Output(sessionID string) (string, error)

func (*DesktopRuntime) PendingEvent 

func (r *DesktopRuntime) PendingEvent(ctx context.Context, sessionID string) (*adapters.Event, error)

func (*DesktopRuntime) RecordAudit 

func (r *DesktopRuntime) RecordAudit(entry audit.Entry) error

RecordAudit is a synchronous, fail-closed persistence boundary for desktop decisions. Callers must not perform a backend write when it returns an error.

func (*DesktopRuntime) Recordings added in v0.7.0 

func (r *DesktopRuntime) Recordings() *record.Store

Recordings exposes the transcript store, or nil when recording is disabled. Callers must tolerate nil rather than assume a store exists.

func (*DesktopRuntime) Resize 

func (r *DesktopRuntime) Resize(ctx context.Context, sessionID string, size terminal.Size) error

func (*DesktopRuntime) RestartAgent added in v0.4.0 

func (r *DesktopRuntime) RestartAgent(ctx context.Context, agentID string) error

RestartAgent transactionally stops then starts one agent. An unconfirmed stop blocks the start; a failed start leaves the agent down in an explicit state rather than half-replaced.

func (*DesktopRuntime) SendLine 

func (r *DesktopRuntime) SendLine(ctx context.Context, sessionID, line string) error

SendLine submits ordinary single-line text through the backend's atomic processor boundary. It never falls back to raw Send or decision resolution.

func (*DesktopRuntime) SendRaw added in v0.6.0 

func (r *DesktopRuntime) SendRaw(ctx context.Context, sessionID string, data []byte) error

SendRaw transmits raw terminal bytes (such as keystrokes, escape sequences, or control characters) directly to the session backend for interactive terminal streaming.

func (*DesktopRuntime) Sessions 

func (r *DesktopRuntime) Sessions() []DesktopSession

func (*DesktopRuntime) Snapshot 

func (r *DesktopRuntime) Snapshot(ctx context.Context, sessionID string) (terminal.Snapshot, error)

func (*DesktopRuntime) StartAgent added in v0.4.0 

func (r *DesktopRuntime) StartAgent(ctx context.Context, agentID string) error

StartAgent launches a fresh process for one stopped agent under its unchanged identity, reusing the immutable preflight specification. The audit record is written before the process launches.

func (*DesktopRuntime) StartupLogs 

func (r *DesktopRuntime) StartupLogs() []string

func (*DesktopRuntime) Stop 

func (r *DesktopRuntime) Stop(ctx context.Context, sessionID string) error

func (*DesktopRuntime) StopAgent added in v0.4.0 

func (r *DesktopRuntime) StopAgent(ctx context.Context, agentID string) error

StopAgent strictly terminates one agent's process while its siblings keep running. The transition is audited with the human operator as its actor. It holds the quiescence lock so an operator stop can never interleave with a strict whole-run stop or close.

func (*DesktopRuntime) SupportedDecisions 

func (r *DesktopRuntime) SupportedDecisions(event adapters.Event) []adapters.Decision

SupportedDecisions reports the semantic answers the interface may offer for this exact event. An interface that guesses instead would show an Allow button on a prompt whose adapter has no verified bytes for accepting it.

func (*DesktopRuntime) TelemetrySnapshot added in v0.3.0 

func (r *DesktopRuntime) TelemetrySnapshot() telemetry.Snapshot

TelemetrySnapshot returns a point-in-time capture of the runtime telemetry metrics.

type DesktopSession 

type DesktopSession struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Command string `json:"command"`
	Backend string `json:"backend"`
	Adapter string `json:"adapter"`
	Shell   bool   `json:"shell"`

	// Simulated marks one of the synthetic Bash agents substituted for an empty
	// agent list. They are indistinguishable from a real agent on screen, which
	// in a supervision tool means an operator can believe they are watching a
	// coding agent while watching a scripted mock.
	Simulated bool `json:"simulated"`

	InstalledVersion  string `json:"installedVersion,omitempty"`
	UnverifiedVersion bool   `json:"unverifiedVersion,omitempty"`
	UnverifiedReason  string `json:"unverifiedReason,omitempty"`
}

DesktopSession is display-safe startup metadata. Shell bodies, environment values and prompt matches never cross this boundary.

type PreflightOptions 

type PreflightOptions struct {
	ConfigPath string
}

PreflightOptions selects the existing configuration inspected by the read-only doctor shared by command-line and desktop frontends.

type VersionInspector added in v0.8.18 

type VersionInspector func(ctx context.Context, spec agent.Spec) (string, error)

VersionInspector executes a version check for a given agent spec. It returns the detected raw version or an error if inspection failed.

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.