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 ¶
- func Run(shell *Shell) error
- type Agent
- type AgentInfo
- type AgentStatus
- type FieldType
- type FieldValidation
- type FileInfo
- type IngestEntry
- type IngestState
- type RewindResultInfo
- type SelectOption
- type SessionMeta
- type SettingsField
- type SettingsFieldInfo
- type SettingsSchema
- type SettingsStore
- type Shell
- func (s *Shell) CopyFileToInputDir(agentID, sourcePath string) (string, error)
- func (s *Shell) DeleteSession(agentID, sessionID string) error
- func (s *Shell) DeleteSetting(scope, key string, secret bool) error
- func (s *Shell) EnsureAgentRunning(agentID string) error
- func (s *Shell) GetIngestState(agentID string) IngestState
- func (s *Shell) GetSessionEvent(agentID, sessionID string, seq uint64) (TimelineEventDetail, error)
- func (s *Shell) GetSettings() map[string]map[string]any
- func (s *Shell) GetSettingsSchema() SettingsSchema
- func (s *Shell) HasMissingRequired() map[string][]string
- func (s *Shell) InspectSession(agentID, sessionID string) ([]TimelineEvent, error)
- func (s *Shell) ListAgents() []AgentInfo
- func (s *Shell) ListFiles(agentID, filter string) ([]FileInfo, error)
- func (s *Shell) ListSessionArchives(agentID, sessionID string) ([]string, error)
- func (s *Shell) ListSessions(agentID string) []SessionMeta
- func (s *Shell) NewSession(agentID string) error
- func (s *Shell) Notify(title, body string) error
- func (s *Shell) OpenExternal(target string) error
- func (s *Shell) OutputDir(agentID string) (string, error)
- func (s *Shell) PickFile(agentID, title, filter string) (string, error)
- func (s *Shell) PickFolder(agentID, title string) (string, error)
- func (s *Shell) RecallSession(agentID, sessionID string) error
- func (s *Shell) RestoreSession(agentID, sessionID, archiveName string) error
- func (s *Shell) RevealInFinder(path string) error
- func (s *Shell) RewindSession(agentID, sessionID string, toSeq uint64) (RewindResultInfo, error)
- func (s *Shell) StopAgent(agentID string) error
- func (s *Shell) UpdateSecret(scope, key, value string) error
- func (s *Shell) UpdateSetting(scope, key string, value any) error
- func (s *Shell) WatchInputDir(agentID string)
- func (s *Shell) WriteFileToInputDir(agentID, name, base64Data string) (string, error)
- type TimelineEvent
- type TimelineEventDetail
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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.
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 ¶
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 ¶
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 ¶
DeleteSession removes a session from the index and deletes its engine session directory from disk.
func (*Shell) DeleteSetting ¶
DeleteSetting removes a plaintext setting or secret.
func (*Shell) EnsureAgentRunning ¶
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 ¶
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 ¶
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 ¶
ListAgents returns info about all registered agents, including their current lifecycle status.
func (*Shell) ListFiles ¶
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 ¶
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 ¶
NewSession stops the current engine for the agent (if running) and boots a fresh one with a new session.
func (*Shell) OpenExternal ¶
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 ¶
OutputDir returns the agent's configured output_dir, creating it if it does not exist.
func (*Shell) PickFile ¶
PickFile presents a native file open dialog rooted in the agent's configured input_dir (or shared_data_dir as fallback).
func (*Shell) PickFolder ¶
PickFolder presents a native folder selection dialog.
func (*Shell) RecallSession ¶
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 ¶
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 ¶
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 ¶
StopAgent stops the engine for the given agent and resets its status to idle so it can be restarted.
func (*Shell) UpdateSecret ¶
UpdateSecret writes a secret value to the OS keychain.
func (*Shell) UpdateSetting ¶
UpdateSetting writes a plaintext setting value. Scope is an agent ID or "shell".
func (*Shell) WatchInputDir ¶
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.
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.