wails

package
v0.31.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: 11 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrFileDialogUnavailable = errors.New("wails: file dialog runtime not attached")

ErrFileDialogUnavailable is returned by Hub.OpenFileDialog when no runtime is attached or the attached runtime does not implement FileDialogRuntime. Consumers can errors.Is against this to detect the fallback path.

Functions

func New

func New() engine.Plugin

New creates a new Wails IO plugin.

Types

type Adapter

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

Adapter implements ui.UIAdapter on top of the Wails runtime.

The outbound path (SendOutput, SendStatus, SendStreamChunk, SendStreamEnd) is fully wired. Approval and ask-user flows use the same channel plumbing as the browser adapter. No code here is Wails-specific — everything funnels through the Hub abstraction.

In config-driven mode, the adapter also handles generic inbound events: any envelope whose Type matches the acceptList is unmarshaled to map[string]any and emitted on the bus.

func NewAdapter

func NewAdapter(hub *Hub, sessionID string, bus engine.EventBus, acceptList []string) *Adapter

NewAdapter creates a Wails UI adapter backed by the given hub.

bus and acceptList enable generic inbound event bridging for config-driven mode. Pass nil/nil for legacy mode.

func (*Adapter) OnApprovalResponse

func (a *Adapter) OnApprovalResponse(handler func(ui.ApprovalResponseMessage))

OnApprovalResponse registers a callback for approval responses.

func (*Adapter) OnCancel

func (a *Adapter) OnCancel(handler func())

OnCancel registers a callback for cancel requests.

func (*Adapter) OnInput

func (a *Adapter) OnInput(handler func(ui.InputMessage))

OnInput registers a callback for user input from the webview.

func (*Adapter) OnResume

func (a *Adapter) OnResume(handler func())

OnResume registers a callback for resume requests.

func (*Adapter) RequestApproval

func (a *Adapter) RequestApproval(msg ui.ApprovalRequestMessage) (ui.ApprovalResponseMessage, error)

RequestApproval emits an approval request and blocks until the user responds.

func (*Adapter) RequestHumanInput

func (a *Adapter) RequestHumanInput(msg ui.HITLRequestMessage) (ui.HITLResponseMessage, error)

RequestHumanInput sends a hitl request to the webview and blocks until the user responds.

func (*Adapter) SendCancelComplete

func (a *Adapter) SendCancelComplete(turnID string, resumable bool) error

SendCancelComplete notifies the webview that a cancellation has completed.

func (*Adapter) SendCodeExecStdout

func (a *Adapter) SendCodeExecStdout(msg ui.CodeExecStdoutMessage) error

SendCodeExecStdout streams a chunk of run_code script stdout to the webview.

func (*Adapter) SendFileChanged

func (a *Adapter) SendFileChanged(path string, action string) error

SendFileChanged notifies the webview that a session file was created or updated.

func (*Adapter) SendOutput

func (a *Adapter) SendOutput(msg ui.OutputMessage) error

SendOutput emits a complete output message to the attached webview.

func (*Adapter) SendPlanDisplay

func (a *Adapter) SendPlanDisplay(msg ui.PlanDisplayMessage) error

SendPlanDisplay emits a plan overview to the webview.

func (*Adapter) SendPlanUpdate

func (a *Adapter) SendPlanUpdate(msg ui.PlanDisplayMessage) error

SendPlanUpdate emits an updated plan with current step statuses to the webview.

func (*Adapter) SendStatus

func (a *Adapter) SendStatus(msg ui.StatusMessage) error

SendStatus emits a status update to the webview.

func (*Adapter) SendStreamChunk

func (a *Adapter) SendStreamChunk(msg ui.StreamChunkMessage) error

SendStreamChunk emits a streaming chunk to the webview.

func (*Adapter) SendStreamEnd

func (a *Adapter) SendStreamEnd(msg ui.StreamEndMessage) error

SendStreamEnd signals end of a stream to the webview.

func (*Adapter) SendStreamHold

func (a *Adapter) SendStreamHold(msg ui.StreamHoldMessage) error

SendStreamHold announces that an output gate suspended the stream, or released it again.

func (*Adapter) SendStreamRetract

func (a *Adapter) SendStreamRetract(msg ui.StreamRetractMessage) error

SendStreamRetract tells clients to disown the text rendered for a turn whose stream a gate blocked.

func (*Adapter) SendThinking

func (a *Adapter) SendThinking(msg ui.ThinkingMessage) error

SendThinking emits an intermediate reasoning step to the webview.

func (*Adapter) SendWorkerStatus

func (a *Adapter) SendWorkerStatus(msg ui.WorkerStatusMessage) error

SendWorkerStatus emits a subagent lifecycle event to the webview. One envelope per bus event in the subagent.started/iteration/complete sequence; the frontend correlates by SpawnID and renders each worker as a single live element (avoiding scroll churn).

func (*Adapter) Sessions

func (a *Adapter) Sessions() []ui.SessionInfo

Sessions returns info about the (single) attached Wails webview.

func (*Adapter) Start

func (a *Adapter) Start(_ context.Context) error

Start is a no-op; the Wails runtime is owned by the host process.

func (*Adapter) Stop

func (a *Adapter) Stop(_ context.Context) error

Stop is a no-op for the same reason.

type FileDialogFilter

type FileDialogFilter struct {
	DisplayName string
	Pattern     string
}

FileDialogFilter mirrors Wails's frontend.FileFilter.

type FileDialogOptions

type FileDialogOptions struct {
	Title            string
	DefaultDirectory string
	Filters          []FileDialogFilter
}

FileDialogOptions mirrors the subset of Wails's OpenDialogOptions we currently expose on the event bus. Kept as a plain struct in the wails package (not pkg/events) so the Runtime interface never leaks event-bus types into embedder code.

type FileDialogRuntime

type FileDialogRuntime interface {
	// OpenFileDialog presents a native single-file open dialog and
	// returns the chosen absolute path, the empty string if the user
	// cancelled, or a non-nil error if the dialog itself failed.
	OpenFileDialog(opts FileDialogOptions) (string, error)
}

FileDialogRuntime is the optional OS-integration surface for file dialogs. An embedder implements this in addition to Runtime to enable the io.file.open.request handler; otherwise that handler responds with Error="no file dialog runtime attached" and callers get a clean cancellation path.

type Hub

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

Hub is the single-client transport wrapper for the Wails plugin.

Unlike the browser plugin's Hub, there is no fanout, no subscription tracking, and no client lifecycle — a Wails app has exactly one attached webview for its lifetime. Hub exists only to give the adapter a uniform surface to call into.

func NewHub

func NewHub(logger *slog.Logger) *Hub

NewHub creates a new Wails hub. The Runtime may be nil at construction time; the embedder installs it via SetRuntime before engine.Boot.

func (*Hub) BroadcastEnvelope

func (h *Hub) BroadcastEnvelope(env ui.Envelope) error

BroadcastEnvelope marshals an envelope and emits it to the webview on the "nexus" channel.

func (*Hub) Close

func (h *Hub) Close()

Close is a no-op on the Wails hub — the webview lifetime is owned by the Wails process, not the plugin.

func (*Hub) OnMessage

func (h *Hub) OnMessage(fn func(env ui.Envelope))

OnMessage registers a callback for inbound webview messages.

func (*Hub) OpenFileDialog

func (h *Hub) OpenFileDialog(opts FileDialogOptions) (string, error)

OpenFileDialog forwards to the attached runtime's FileDialogRuntime implementation if one exists. Returns a sentinel error when no runtime is attached or when the runtime does not implement the optional FileDialogRuntime interface. Callers should treat the error as "native file dialog unavailable" and surface it to the user or fall back.

func (*Hub) Sessions

func (h *Hub) Sessions() []ui.SessionInfo

Sessions returns a single synthetic session entry for the attached webview.

func (*Hub) SetRuntime

func (h *Hub) SetRuntime(rt Runtime)

SetRuntime attaches the Wails runtime implementation. Called by the embedder (Wails main.go) from OnStartup, before engine.Boot.

type Plugin

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

Plugin is the Wails desktop-shell IO transport for Nexus.

Scope and lifetime are intentionally different from nexus.io.browser: Wails is process-scoped, owned by the host Wails main.go. The host installs a Runtime implementation via SetRuntime before calling engine.Boot, and tears down via engine.Stop from OnShutdown.

The plugin supports two modes:

  • Legacy (no subscribe/accept config): hardcoded chat-event subscriptions with typed handlers. Backward compatible with existing configs that don't set these keys.
  • Config-driven (subscribe/accept lists in YAML): generic passthrough bridging for arbitrary domain events. The developer controls exactly which events cross the bus-to-frontend boundary.

func (*Plugin) Capabilities

func (p *Plugin) Capabilities() []engine.Capability

func (*Plugin) ConfigSchema

func (p *Plugin) ConfigSchema() []byte

ConfigSchema implements engine.ConfigSchemaProvider.

func (*Plugin) Dependencies

func (p *Plugin) Dependencies() []string

func (*Plugin) Emissions

func (p *Plugin) Emissions() []string

func (*Plugin) Hub

func (p *Plugin) Hub() *Hub

Hub exposes the plugin's Hub so the embedder can call SetRuntime on it before engine.Boot. This is the seam the build plan calls out: "accept the Wails runtime context via a setter the embedder calls before Boot".

Usage from the Wails app's main.go:

p := wailsplugin.New().(*wailsplugin.Plugin)
eng.Registry.Register("nexus.io.wails", func() engine.Plugin { return p })
// inside OnStartup(ctx):
p.Hub().SetRuntime(myWailsRuntimeAdapter{ctx: ctx})
eng.Boot(ctx)

The hub is created lazily in Init because Init is where the logger becomes available; the embedder must therefore call Init (by booting the lifecycle) or register a pre-built plugin instance.

func (*Plugin) ID

func (p *Plugin) ID() string

func (*Plugin) Init

func (p *Plugin) Init(ctx engine.PluginContext) error

Init creates the hub (if the embedder has not already done so via Hub()) and the adapter, then wires event bridging.

When the plugin config contains "subscribe" and/or "accept" keys, the plugin operates in config-driven mode: only the listed events are bridged, using a generic passthrough handler. When those keys are absent, the plugin falls back to its legacy hardcoded chat-event handler set for backward compatibility.

func (*Plugin) Name

func (p *Plugin) Name() string

func (*Plugin) Ready

func (p *Plugin) Ready() error

Ready emits the session-start event. Unlike the browser plugin, there is no HTTP server to start here — the Wails host process already owns the webview, and the Runtime was installed by the embedder before Boot.

func (*Plugin) Requires

func (p *Plugin) Requires() []engine.Requirement

func (*Plugin) Shutdown

func (p *Plugin) Shutdown(_ context.Context) error

Shutdown unsubscribes from the bus. The webview itself is torn down by the Wails host process, not the plugin.

func (*Plugin) Subscriptions

func (p *Plugin) Subscriptions() []engine.EventSubscription

func (*Plugin) Version

func (p *Plugin) Version() string

type Runtime

type Runtime interface {
	// EmitEvent publishes a Wails runtime event to the single attached webview.
	EmitEvent(name string, optionalData ...any)
	// OnEvent registers a callback for inbound events from the webview.
	OnEvent(name string, callback func(optionalData ...any))
}

Runtime is the minimal surface the Wails embedder must provide.

The Nexus repo does not import github.com/wailsapp/wails/v2/pkg/runtime directly — the downstream Wails app wraps the relevant runtime calls (with the Wails context baked in) and hands in an implementation before calling engine.Boot.

Event pub/sub (EmitEvent / OnEvent) is always required. OS-integration methods like OpenFileDialog are additive: the plugin feature-gates them on an interface assertion at call time so a minimal embedder that only wants message passing does not have to implement them. Any embedder shipping a real desktop app should implement the full surface so wrapper features (file dialogs, etc.) work.

Jump to

Keyboard shortcuts

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