Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

6.9 KB
Raw Blame
// Package onboarding implements Beacon's one-time interactive install wizard and
// retains the legacy attribution record used by unattended deployments.
//
// Everything here is best-effort. Onboarding never fails an install, never runs
// outside an interactive terminal, and never runs twice on the same machine.
package onboarding

import (
	"crypto/rand"
	"encoding/hex"
	"encoding/json"
	"os"
	"path/filepath"
)

// ProfilePath is the profile location relative to the user's home directory.
//
// This is a deliberate sibling of ~/.beacon/endpoint/ rather than a file inside it.
// lifecycle.Uninstall removes the endpoint config and every manifest-listed file, so a
// profile stored under ~/.beacon/endpoint/ would be destroyed by an uninstall and the
// user would be prompted again on their next install. The endpoint config is also
// mode-specific (--user vs --system) and rewritten wholesale by every install and
// repair, which would lose the record just as reliably.
const ProfilePath = ".beacon/profile.json"

// SchemaVersion is the profile format version. Bump it only for a breaking change;
// readers tolerate unknown fields, so additive changes do not need a bump.
const SchemaVersion = 1

// Outcome records how the one-time submission ended.
const (
	// OutcomeSubmitted means the endpoint accepted the signup.
	OutcomeSubmitted = "submitted"
	// OutcomePending means the submission failed in a way worth retrying (network
	// error, timeout, 5xx). The payload is kept so a later command can resend it.
	OutcomePending = "pending"
	// OutcomeRejected means the endpoint refused the submission (4xx, rate limit).
	// Terminal: there is nothing useful to retry.
	OutcomeRejected = "rejected"
	// OutcomeSkipped means the user opted out through a documented escape hatch.
	OutcomeSkipped = "skipped"
	// OutcomeAuthenticated means the interactive wizard used the signed-in Beacon
	// account instead of the legacy email/usage submission.
	OutcomeAuthenticated = "authenticated"
)

// Profile is the persisted per-machine Beacon profile.
type Profile struct {
	SchemaVersion int         `json:"schema_version"`
	InstallID     string      `json:"install_id"`
	Onboarding    Onboarding  `json:"onboarding"`
	Pending       *Submission `json:"pending_submission,omitempty"`
	// History records the answer to the local history prompt that `beacon endpoint traces` shows
	// once, so a "not now" is not asked again.
	History *History `json:"history,omitempty"`
}

// History is the answer to the local history prompt.
type History struct {
	DeclinedAt string `json:"declined_at,omitempty"`
}

// HistoryDeclined reports whether the user answered "not now" to the local history prompt.
func (p Profile) HistoryDeclined() bool {
	return p.History != nil && p.History.DeclinedAt != ""
}

// Onboarding records the outcome of the one-time prompt.
type Onboarding struct {
	CompletedAt   string `json:"completed_at,omitempty"`
	Outcome       string `json:"outcome,omitempty"`
	Email         string `json:"email,omitempty"`
	Usage         string `json:"usage,omitempty"`
	BeaconVersion string `json:"beacon_version,omitempty"`
	// Destination records where the user chose to send this machine's telemetry.
	// New interactive installs choose local or asymptote; own_infra remains valid for
	// profiles written by older versions and unattended/admin-managed deployments.
	Destination string `json:"destination,omitempty"`
	// PrivacyMode applies only to Beacon Cloud forwarding.
	PrivacyMode string `json:"privacy_mode,omitempty"`
	// CloudMCP and AgentSkills record the agent tools answer: "installed" when the person
	// kept the tool selected, "declined" when they turned it off, empty when never asked.
	// CloudMCP is asked only with the Beacon Cloud destination.
	CloudMCP    string `json:"cloud_mcp,omitempty"`
	AgentSkills string `json:"agent_skills,omitempty"`
}

// Answers to the agent tools question.
const (
	AgentToolInstalled = "installed"
	AgentToolDeclined  = "declined"
)

// AgentToolAnswer is how a kept or turned-off agent tool is recorded.
func AgentToolAnswer(kept bool) string {
	if kept {
		return AgentToolInstalled
	}
	return AgentToolDeclined
}

// Answers to the telemetry destination question.
const (
	DestinationLocal     = "local"
	DestinationOwnInfra  = "own_infra"
	DestinationAsymptote = "asymptote"
)

// Prompted reports whether this machine has already been through onboarding.
// It is the single gate that makes the prompt fire once and only once.
func (p Profile) Prompted() bool {
	return p.Onboarding.CompletedAt != ""
}

// Path returns the absolute profile path, honoring HOME so tests can redirect it.
func Path() string {
	home, err := os.UserHomeDir()
	if err != nil {
		return filepath.Join(".", ProfilePath)
	}
	return filepath.Join(home, ProfilePath)
}

// Load reads the profile.
//
// A missing file and a corrupt file are both reported as an empty profile with no
// error. Onboarding is a sales signal, not a correctness requirement: refusing to
// install because a JSON file got truncated would trade a real user's install for a
// lead we were never going to get anyway. An unreadable profile simply reads as
// "not yet prompted".
func Load() Profile {
	data, err := os.ReadFile(Path())
	if err != nil {
		return Profile{}
	}
	var p Profile
	if err := json.Unmarshal(data, &p); err != nil {
		return Profile{}
	}
	return p
}

// Save writes the profile, minting an install ID and stamping the schema version if
// they are not set yet. The file is 0600 because it holds the operator's email.
func Save(p Profile) error {
	if p.SchemaVersion == 0 {
		p.SchemaVersion = SchemaVersion
	}
	if p.InstallID == "" {
		id, err := NewInstallID()
		if err != nil {
			return err
		}
		p.InstallID = id
	}
	path := Path()
	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
		return err
	}
	data, err := json.MarshalIndent(p, "", "  ")
	if err != nil {
		return err
	}
	data = append(data, '\n')
	if err := os.WriteFile(path, data, 0o600); err != nil {
		return err
	}
	// WriteFile only applies the mode when it creates the file, so an existing
	// profile written before this code shipped would keep its old permissions.
	return os.Chmod(path, 0o600)
}

// NewInstallID returns a random 128-bit hex identifier.
//
// This is the dedupe key for the signup endpoint (so reinstalling updates one row
// instead of creating another) and the handle a user quotes to request deletion. It
// is unrelated to any hardware or account identifier and carries no user data.
func NewInstallID() (string, error) {
	buf := make([]byte, 16)
	if _, err := rand.Read(buf); err != nil {
		return "", err
	}
	return hex.EncodeToString(buf), nil
}

// EnsureInstallID returns the profile's install ID, minting and persisting one if the
// profile does not have it yet.
func EnsureInstallID(p *Profile) (string, error) {
	if p.InstallID != "" {
		return p.InstallID, nil
	}
	id, err := NewInstallID()
	if err != nil {
		return "", err
	}
	p.InstallID = id
	return id, nil
}