desktop

package
v0.30.0 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package desktop provides the reusable shell framework for Nexus desktop applications. It manages Wails lifecycle, per-agent engine creation, scoped event bridging, and shell services (file dialogs, notifications, OS integration).

Usage from a cmd/<app>/main.go:

desktop.Run(&desktop.Shell{
    Title:  "My App",
    Width:  900,
    Height: 720,
    Assets: assets,
    Agents: []desktop.Agent{{
        ID:         "my-agent",
        Name:       "My Agent",
        ConfigYAML: configYAML,
        Factories:  map[string]func() engine.Plugin{ ... },
    }},
})

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Run

func Run(shell *Shell) error

Run is the entry point for a desktop shell application. It configures and starts the Wails app with the given shell. This function blocks until the app exits.

Types

type Agent

type Agent struct {
	ID          string                          // unique key: "staffing-match", "hello-world"
	Name        string                          // display: "Staffing Match"
	Description string                          // short blurb for the agent selector
	Icon        string                          // Font Awesome class (e.g. "fa-solid fa-handshake")
	ConfigYAML  []byte                          // embedded Nexus config for this agent's engine
	Factories   map[string]func() engine.Plugin // custom plugin factories
	Settings    []SettingsField                 // user-configurable fields rendered in settings UI
}

Agent represents a single Nexus configuration hosted by the shell. Domain logic flows through the bus via the agent's plugins — the Agent struct is pure registration data.

type AgentInfo

type AgentInfo struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Icon        string `json:"icon"`
	Status      string `json:"status"`
}

AgentInfo is the serializable projection of Agent for the frontend.

type AgentStatus

type AgentStatus string

AgentStatus represents the lifecycle state of an agent's engine.

const (
	AgentStatusIdle    AgentStatus = "idle"
	AgentStatusBooting AgentStatus = "booting"
	AgentStatusRunning AgentStatus = "running"
	AgentStatusError   AgentStatus = "error"
)

type FieldType

type FieldType int

FieldType describes the kind of UI control a settings field renders as.

const (
	FieldString FieldType = iota // single-line text input
	FieldPath                    // text input + Browse button (calls Shell.PickFolder)
	FieldText                    // multiline textarea (user-editable prompts)
	FieldNumber                  // number input with optional min/max
	FieldBool                    // toggle switch
	FieldSelect                  // dropdown
)

type FieldValidation

type FieldValidation struct {
	Regex   string   `json:"regex,omitempty"`
	Min     *float64 `json:"min,omitempty"`
	Max     *float64 `json:"max,omitempty"`
	Message string   `json:"message,omitempty"` // validation error message
}

FieldValidation holds optional constraints for a settings field.

type FileInfo

type FileInfo struct {
	Name     string    `json:"name"`
	Path     string    `json:"path"`
	Size     int64     `json:"size"`
	Modified time.Time `json:"modified"`
	IsDir    bool      `json:"is_dir"`
}

FileInfo describes a single file entry returned by ListFiles.

type IngestEntry

type IngestEntry struct {
	ID            string     `json:"id"`
	Path          string     `json:"path"`
	Namespace     string     `json:"namespace"`
	Status        string     `json:"status"` // active | completed | failed
	StartedAt     time.Time  `json:"started_at"`
	CompletedAt   *time.Time `json:"completed_at,omitempty"`
	Chunks        int        `json:"chunks"`
	SkippedCached int        `json:"skipped_cached"`
	Error         string     `json:"error,omitempty"`
}

IngestEntry is the serializable view of a single ingestion sent to the frontend. The same shape covers both in-flight and finished entries — CompletedAt / Chunks / Error are zero values while Status == "active".

type IngestState

type IngestState struct {
	Active []IngestEntry `json:"active"`
	Recent []IngestEntry `json:"recent"`
}

IngestState is the per-agent projection returned by GetIngestState and pushed on every change via the {agentID}:ingest.updated Wails event.

type RewindResultInfo

type RewindResultInfo struct {
	ArchiveName    string `json:"archive_name"`
	TruncatedSeq   uint64 `json:"truncated_seq"`
	EventsKept     int    `json:"events_kept"`
	EventsArchived int    `json:"events_archived"`
}

RewindResultInfo is the JSON-friendly result returned to the frontend after a successful rewind.

type SelectOption

type SelectOption struct {
	Value   string `json:"value"`
	Display string `json:"display"`
}

SelectOption is one choice in a FieldSelect dropdown.

type SessionMeta

type SessionMeta struct {
	ID        string    `json:"id"`
	AgentID   string    `json:"agent_id"`
	Title     string    `json:"title"`
	Status    string    `json:"status"` // "running", "completed", "failed"
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
	Preview   any       `json:"preview,omitempty"`
}

SessionMeta is the shell-level metadata for a single engine session. The engine's own SessionWorkspace (under ~/.nexus/sessions/<id>/) is the source of truth for session content; this struct tracks the shell-layer projection: which agent owns it, the user-facing title, status, and optional preview data contributed by the agent plugin.

type SettingsField

type SettingsField struct {
	Key         string           // machine key: "data_dir", "greeting"
	Display     string           // human label: "Data Folder"
	Description string           // help text shown below the field
	Type        FieldType        // determines the UI control
	Secret      bool             // stored in OS keychain, masked in UI
	Default     any              // default value if the user hasn't configured one
	Required    bool             // agent refuses to boot without this
	Validation  *FieldValidation // optional constraints
	ConfigPath  string           // template variable in config YAML, e.g. "${data_dir}"
	Options     []SelectOption   // for FieldSelect only
}

SettingsField declares a single configurable value that an agent (or the shell itself) exposes to the user through the settings UI.

type SettingsFieldInfo

type SettingsFieldInfo struct {
	Key         string           `json:"key"`
	Display     string           `json:"display"`
	Description string           `json:"description,omitempty"`
	Type        string           `json:"type"`
	Secret      bool             `json:"secret,omitempty"`
	Required    bool             `json:"required,omitempty"`
	Default     any              `json:"default,omitempty"`
	Validation  *FieldValidation `json:"validation,omitempty"`
	Options     []SelectOption   `json:"options,omitempty"`
}

SettingsFieldInfo is the JSON-serializable projection of SettingsField sent to the frontend for dynamic UI rendering.

type SettingsSchema

type SettingsSchema struct {
	Shell  []SettingsFieldInfo            `json:"shell"`
	Agents map[string][]SettingsFieldInfo `json:"agents"`
}

SettingsSchema is the top-level schema sent to the frontend. It contains shell-level fields and per-agent fields.

type SettingsStore

type SettingsStore interface {
	// Get returns a plaintext setting value. Scope is an agent ID or
	// "shell". Returns (nil, false) if unset.
	Get(scope, key string) (any, bool)

	// Set writes a plaintext setting value.
	Set(scope, key string, value any) error

	// GetSecret reads a secret from the OS keychain.
	GetSecret(scope, key string) (string, error)

	// SetSecret writes a secret to the OS keychain and records a
	// sentinel in the JSON file so the UI knows a value exists.
	SetSecret(scope, key string, value string) error

	// DeleteSecret removes a secret from the OS keychain and removes
	// the sentinel from the JSON file.
	DeleteSecret(scope, key string) error

	// Delete removes a plaintext setting.
	Delete(scope, key string) error

	// Save flushes the JSON file to disk.
	Save() error

	// Resolve looks up a value with scope fallback: checks the given
	// scope first, then falls back to "shell" scope. For secret fields,
	// reads from keychain. Returns ("", false) if not found anywhere.
	Resolve(scope, key string, secret bool) (string, bool)
}

SettingsStore manages persistence of user settings. Non-secret values live in a JSON file; secrets live in the OS keychain.

type Shell

type Shell struct {
	Title  string
	Width  int
	Height int
	Agents []Agent
	Assets embed.FS // custom frontend assets; zero value uses the default base template

	// DataDir controls where the shell persists settings, the session
	// metadata index, and engine session workspaces. Set this when an
	// embedder wants to keep its data isolated from other Nexus desktop
	// apps (e.g. "~/.nexus/myapp"). The leading "~" is expanded.
	//
	// When DataDir is empty (the cmd/desktop default), the shell uses the
	// legacy split layout: settings + session index at ~/.nexus/desktop/,
	// engine sessions at ~/.nexus/sessions/. When DataDir is set, both
	// move under it (settings at <DataDir>/settings.json, sessions at
	// <DataDir>/sessions/). Embedders that want the new unified layout
	// must also set "core.sessions.root: <DataDir>/sessions" in each
	// agent's YAML so engines write to the same root the shell expects.
	DataDir string
	// contains filtered or unexported fields
}

Shell is the top-level desktop shell orchestrator. It manages per-agent engine lifecycles and provides Wails-bound shell services.

func (*Shell) CopyFileToInputDir

func (s *Shell) CopyFileToInputDir(agentID, sourcePath string) (string, error)

CopyFileToInputDir copies a file from sourcePath into the agent's input_dir. Used by the frontend for drag-and-drop file imports. Returns the destination path.

func (*Shell) DeleteSession

func (s *Shell) DeleteSession(agentID, sessionID string) error

DeleteSession removes a session from the index and deletes its engine session directory from disk.

func (*Shell) DeleteSetting

func (s *Shell) DeleteSetting(scope, key string, secret bool) error

DeleteSetting removes a plaintext setting or secret.

func (*Shell) EnsureAgentRunning

func (s *Shell) EnsureAgentRunning(agentID string) error

EnsureAgentRunning creates and boots the engine for the given agent if it is not already running.

func (*Shell) GetIngestState

func (s *Shell) GetIngestState(agentID string) IngestState

GetIngestState returns the current ingestion projection (active + recent) for an agent. Frontends use this on initial load and then subscribe to {agentID}:ingest.updated for incremental pushes.

func (*Shell) GetSessionEvent

func (s *Shell) GetSessionEvent(agentID, sessionID string, seq uint64) (TimelineEventDetail, error)

GetSessionEvent returns the full envelope (including payload) for the requested seq. Used by the timeline panel's payload preview.

func (*Shell) GetSettings

func (s *Shell) GetSettings() map[string]map[string]any

GetSettings returns all current setting values. Secret fields show "__keychain__" instead of the actual value.

func (*Shell) GetSettingsSchema

func (s *Shell) GetSettingsSchema() SettingsSchema

GetSettingsSchema returns the full settings schema for the frontend to render dynamically. Includes shell-level and per-agent fields.

func (*Shell) HasMissingRequired

func (s *Shell) HasMissingRequired() map[string][]string

HasMissingRequired checks whether any agent has required settings that are not yet configured. Returns a map of agentID → missing keys.

func (*Shell) InspectSession

func (s *Shell) InspectSession(agentID, sessionID string) ([]TimelineEvent, error)

InspectSession returns the journal as a slice of lightweight timeline events, oldest-first. Payloads are omitted; use GetSessionEvent to fetch one. Returns an empty slice (not an error) when the session has no journal directory yet.

func (*Shell) ListAgents

func (s *Shell) ListAgents() []AgentInfo

ListAgents returns info about all registered agents, including their current lifecycle status.

func (*Shell) ListFiles

func (s *Shell) ListFiles(agentID, filter string) ([]FileInfo, error)

ListFiles returns the contents of the agent's configured input_dir. filter is a glob pattern (e.g. "*.pdf"); empty string returns all.

func (*Shell) ListSessionArchives

func (s *Shell) ListSessionArchives(agentID, sessionID string) ([]string, error)

ListSessionArchives returns the names of every rewind archive for the named session, oldest-first.

func (*Shell) ListSessions

func (s *Shell) ListSessions(agentID string) []SessionMeta

ListSessions returns session metadata for the given agent, sorted most-recent first.

func (*Shell) NewSession

func (s *Shell) NewSession(agentID string) error

NewSession stops the current engine for the agent (if running) and boots a fresh one with a new session.

func (*Shell) Notify

func (s *Shell) Notify(title, body string) error

Notify sends an OS notification.

func (*Shell) OpenExternal

func (s *Shell) OpenExternal(target string) error

OpenExternal opens a file or URL using the system default handler. For http/https URLs it uses the Wails runtime; for file paths it shells out to the OS open command.

func (*Shell) OutputDir

func (s *Shell) OutputDir(agentID string) (string, error)

OutputDir returns the agent's configured output_dir, creating it if it does not exist.

func (*Shell) PickFile

func (s *Shell) PickFile(agentID, title, filter string) (string, error)

PickFile presents a native file open dialog rooted in the agent's configured input_dir (or shared_data_dir as fallback).

func (*Shell) PickFolder

func (s *Shell) PickFolder(agentID, title string) (string, error)

PickFolder presents a native folder selection dialog.

func (*Shell) RecallSession

func (s *Shell) RecallSession(agentID, sessionID string) error

RecallSession stops the current engine and boots a new one that resumes the given session ID. The engine replays conversation history via io.history.replay.

func (*Shell) RestoreSession

func (s *Shell) RestoreSession(agentID, sessionID, archiveName string) error

RestoreSession swaps the live journal for a previously archived snapshot. The current live journal is itself archived first. Same liveness rule as RewindSession: refuses to operate on the active session.

func (*Shell) RevealInFinder

func (s *Shell) RevealInFinder(path string) error

RevealInFinder opens the system file manager with the given path selected (macOS) or its parent directory open (Linux/Windows).

func (*Shell) RewindSession

func (s *Shell) RewindSession(agentID, sessionID string, toSeq uint64) (RewindResultInfo, error)

RewindSession archives the named session's journal and truncates it to toSeq inclusive. The session must not be the agent's currently running session — concurrent writes against a journal being rewound produce undefined state. Returns the archive name plus rewind stats.

func (*Shell) StopAgent

func (s *Shell) StopAgent(agentID string) error

StopAgent stops the engine for the given agent and resets its status to idle so it can be restarted.

func (*Shell) UpdateSecret

func (s *Shell) UpdateSecret(scope, key, value string) error

UpdateSecret writes a secret value to the OS keychain.

func (*Shell) UpdateSetting

func (s *Shell) UpdateSetting(scope, key string, value any) error

UpdateSetting writes a plaintext setting value. Scope is an agent ID or "shell".

func (*Shell) WatchInputDir

func (s *Shell) WatchInputDir(agentID string)

WatchInputDir starts the file watcher on the given agent's input directory. Called by the frontend when the file browser panel opens or when the active agent changes.

func (*Shell) WriteFileToInputDir

func (s *Shell) WriteFileToInputDir(agentID, name, base64Data string) (string, error)

WriteFileToInputDir writes base64-encoded file data into the agent's input_dir. Used as a fallback for drag-and-drop when the webview does not expose the native file path.

type TimelineEvent

type TimelineEvent struct {
	Seq        uint64 `json:"seq"`
	Ts         string `json:"ts"`
	Type       string `json:"type"`
	Source     string `json:"source,omitempty"`
	EventID    string `json:"event_id,omitempty"`
	ParentSeq  uint64 `json:"parent_seq,omitempty"`
	SideEffect bool   `json:"side_effect,omitempty"`
	Vetoed     bool   `json:"vetoed,omitempty"`
}

TimelineEvent is a lightweight projection of a journal envelope used by the desktop timeline panel. Payloads are intentionally omitted from the listing call so the frontend can stream tens of thousands of events without paying the marshal cost; full payloads are fetched on-demand via GetSessionEvent.

type TimelineEventDetail

type TimelineEventDetail struct {
	TimelineEvent
	Payload any `json:"payload,omitempty"`
}

TimelineEventDetail extends TimelineEvent with the full payload, used when the operator clicks an event row to inspect its contents.

Jump to

Keyboard shortcuts

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