Skip to content

Open-source AI browser agent for Chrome and Firefox (monorepo) 🧠

companion: handle shutdown and MLX environment failures

Barack Sokullub535cdc23463
diff --git a/webbrain-systray/internal/app/app.go b/webbrain-systray/internal/app/app.go
index b9e70dac1..7f5225967 100644
--- a/webbrain-systray/internal/app/app.go
+++ b/webbrain-systray/internal/app/app.go
@@ -584,7 +584,7 @@ func (a *App) restartOn(s settings.Settings, port int, strict bool) error {
local := a.Proxy.Local()
before := a.Proxy.Port()
panelOpen := a.listeners() > 0
- a.Proxy.Stop()
+ a.Proxy.StopForRestart()
err := a.Proxy.Start(a.proxyOptionsOn(s, local, port, strict))
a.mu.Lock()
a.notice = ""
diff --git a/webbrain-systray/internal/core/proxy.go b/webbrain-systray/internal/core/proxy.go
index 17a01015a..30c9b815d 100644
--- a/webbrain-systray/internal/core/proxy.go
+++ b/webbrain-systray/internal/core/proxy.go
@@ -83,6 +83,13 @@ func New() *Proxy { return &Proxy{} }
func (p *Proxy) Port() int {
p.mu.Lock()
defer p.mu.Unlock()
+ if p.done != nil {
+ select {
+ case <-p.done:
+ return 0
+ default:
+ }
+ }
return p.port
}
@@ -267,8 +274,16 @@ func (p *Proxy) Start(opts Options) error {
return errors.New("proxy did not start listening in time")
}
-// Stop shuts the service down and waits for it to exit.
-func (p *Proxy) Stop() {
+// Stop shuts the service down, waiting up to ten seconds during application
+// shutdown. A timed-out service still owns its port until it actually exits.
+func (p *Proxy) Stop() { p.stop(10 * time.Second) }
+
+// StopForRestart waits for the old in-process service to exit before replacing
+// it. Starting another instance while it is alive would fail and leave the
+// companion without a usable proxy.
+func (p *Proxy) StopForRestart() { p.stop(0) }
+
+func (p *Proxy) stop(grace time.Duration) {
p.opMu.Lock()
defer p.opMu.Unlock()
p.mu.Lock()
@@ -278,13 +293,20 @@ func (p *Proxy) Stop() {
return
}
cancel()
- select {
- case <-done:
- case <-time.After(10 * time.Second):
- logx.Printf("proxy did not stop within 10s")
+ if grace == 0 {
+ <-done
+ } else {
+ select {
+ case <-done:
+ case <-time.After(grace):
+ logx.Printf("proxy did not stop within %s", grace)
+ return
+ }
}
p.mu.Lock()
- p.port = 0
+ if p.done == done {
+ p.port = 0
+ }
p.mu.Unlock()
}
diff --git a/webbrain-systray/internal/core/proxy_test.go b/webbrain-systray/internal/core/proxy_test.go
index 22e57c34a..22396a176 100644
--- a/webbrain-systray/internal/core/proxy_test.go
+++ b/webbrain-systray/internal/core/proxy_test.go
@@ -1,6 +1,9 @@
package core
-import "testing"
+import (
+ "testing"
+ "time"
+)
func TestPickPortMaximum(t *testing.T) {
const host = "127.0.0.1"
@@ -16,3 +19,40 @@ func TestPickPortMaximum(t *testing.T) {
t.Fatalf("PickPort returned %d, want %d", got, port)
}
}
+
+func TestTimedOutStopKeepsProxyStateUntilExit(t *testing.T) {
+ done := make(chan struct{})
+ p := &Proxy{port: 8327, done: done, cancel: func() {}}
+ p.stop(20 * time.Millisecond)
+ if !p.Running() || p.Port() != 8327 {
+ t.Fatalf("timed-out stop lost live proxy state: running=%v port=%d", p.Running(), p.Port())
+ }
+ close(done)
+ if p.Running() || p.Port() != 0 {
+ t.Fatalf("exited proxy still appears live: running=%v port=%d", p.Running(), p.Port())
+ }
+}
+
+func TestRestartWaitsForPreviousProxyToExit(t *testing.T) {
+ done := make(chan struct{})
+ p := &Proxy{port: 8327, done: done, cancel: func() {}}
+ stopped := make(chan struct{})
+ go func() {
+ p.StopForRestart()
+ close(stopped)
+ }()
+ select {
+ case <-stopped:
+ t.Fatal("restart proceeded while old proxy was still alive")
+ case <-time.After(25 * time.Millisecond):
+ }
+ close(done)
+ select {
+ case <-stopped:
+ case <-time.After(time.Second):
+ t.Fatal("restart did not proceed after old proxy exited")
+ }
+ if p.Port() != 0 {
+ t.Fatal("stopped proxy retained its port")
+ }
+}
diff --git a/webbrain-systray/internal/localmodel/manager.go b/webbrain-systray/internal/localmodel/manager.go
index 1fd3a9a94..046cb6a24 100644
--- a/webbrain-systray/internal/localmodel/manager.go
+++ b/webbrain-systray/internal/localmodel/manager.go
@@ -167,6 +167,11 @@ type uvInstallation struct {
SHA256 string `json:"sha256"`
}
+type mlxInstallation struct {
+ Requirements string `json:"requirements"`
+ Files []runtimeFile `json:"files"`
+}
+
var runtimeVerifier download.Verifier
func fileSHA256(path string) (string, error) {
@@ -303,11 +308,94 @@ func installedUVManifest(arch string) ([]byte, error) {
}
func mlxEnvironmentInstalled() bool {
- if !fileOK(filepath.Join(mlxVenv(), "bin", "python"), 0) {
+ dir := mlxVenv()
+ data, err := os.ReadFile(filepath.Join(dir, ".installed"))
+ if err != nil {
return false
}
- data, err := os.ReadFile(filepath.Join(mlxVenv(), ".installed"))
- return err == nil && string(data) == strings.Join(mlxRequirements, "\n")+"\n"
+ var installed mlxInstallation
+ if json.Unmarshal(data, &installed) != nil || installed.Requirements != strings.Join(mlxRequirements, "\n") || len(installed.Files) < 6 {
+ return false
+ }
+ pythonVerified := false
+ for _, f := range installed.Files {
+ rel := filepath.FromSlash(f.Path)
+ if !filepath.IsLocal(rel) || f.Size <= 0 || len(f.SHA256) != 64 {
+ return false
+ }
+ path := filepath.Join(dir, rel)
+ if f.Path == "bin/python" {
+ info, err := os.Stat(path)
+ if err != nil || !info.Mode().IsRegular() || (runtime.GOOS != "windows" && info.Mode().Perm()&0o111 == 0) {
+ return false
+ }
+ pythonVerified = true
+ }
+ if !runtimeVerifier.Valid(path, f.Size, f.SHA256) {
+ return false
+ }
+ }
+ return pythonVerified
+}
+
+const mlxImportScript = `import importlib, json
+names = ("mlx.core", "mlx_lm", "mlx_vlm", "mlx_vlm.models.prism_hadamard_qwen35", "transformers")
+modules = [importlib.import_module(name) for name in names]
+from mlx_vlm.models.prism_hadamard_qwen35 import Model
+paths = [module.__file__ for module in modules]
+if any(path is None for path in paths):
+ raise RuntimeError("MLX dependency has no file path")
+print("WBC_MLX_FILES=" + json.dumps(paths))`
+
+func mlxImportFiles(ctx context.Context, py string) ([]string, error) {
+ cmd := osutil.CommandContext(ctx, py, "-c", mlxImportScript)
+ cmd.Env = append(os.Environ(), "HF_HUB_OFFLINE=1")
+ cmd.Stderr = logx.Writer("[mlx]")
+ out, err := cmd.Output()
+ if err != nil {
+ return nil, fmt.Errorf("import MLX dependencies: %w (see log)", err)
+ }
+ const prefix = "WBC_MLX_FILES="
+ i := strings.LastIndex(string(out), prefix)
+ if i < 0 {
+ return nil, errors.New("MLX dependency check returned no module paths")
+ }
+ var paths []string
+ if err := json.Unmarshal([]byte(strings.TrimSpace(string(out[i+len(prefix):]))), &paths); err != nil {
+ return nil, fmt.Errorf("parse MLX dependency paths: %w", err)
+ }
+ if len(paths) != 5 {
+ return nil, errors.New("MLX dependency check returned an incomplete module list")
+ }
+ return paths, nil
+}
+
+func installedMLXManifest(modulePaths []string) ([]byte, error) {
+ dir := mlxVenv()
+ paths := append([]string{filepath.Join(dir, "bin", "python")}, modulePaths...)
+ installed := mlxInstallation{Requirements: strings.Join(mlxRequirements, "\n")}
+ for _, path := range paths {
+ rel, err := filepath.Rel(dir, path)
+ if err != nil || !filepath.IsLocal(rel) {
+ return nil, fmt.Errorf("MLX dependency is outside its environment: %s", path)
+ }
+ info, err := os.Stat(path)
+ if err != nil {
+ return nil, err
+ }
+ if !info.Mode().IsRegular() || info.Size() == 0 {
+ return nil, fmt.Errorf("MLX dependency is not a file: %s", path)
+ }
+ if rel == filepath.Join("bin", "python") && runtime.GOOS != "windows" && info.Mode().Perm()&0o111 == 0 {
+ return nil, errors.New("MLX Python is not executable")
+ }
+ sha, err := fileSHA256(path)
+ if err != nil {
+ return nil, err
+ }
+ installed.Files = append(installed.Files, runtimeFile{filepath.ToSlash(rel), info.Size(), sha})
+ }
+ return json.Marshal(installed)
}
func (m *Manager) ggufInstalled(p Plan) bool {
@@ -624,7 +712,14 @@ func (m *Manager) installMLX(ctx context.Context, info sysinfo.Info) error {
_ = os.Remove(src)
}
if mlxEnvironmentInstalled() {
- return nil
+ if _, err := mlxImportFiles(ctx, filepath.Join(mlxVenv(), "bin", "python")); err == nil {
+ return nil
+ } else {
+ if ctx.Err() != nil {
+ return ctx.Err()
+ }
+ logx.Printf("MLX environment needs repair: %v", err)
+ }
}
env := append(os.Environ(),
"UV_CACHE_DIR="+filepath.Join(paths.Runtimes(), "uv-cache"),
@@ -654,12 +749,15 @@ func (m *Manager) installMLX(ctx context.Context, info sysinfo.Info) error {
return err
}
m.setPhase(PhaseInstalling, "Checking the native Bonsai loader", nil)
- check := osutil.CommandContext(ctx, py, "-c", "from mlx_vlm.models.prism_hadamard_qwen35 import Model")
- check.Stdout, check.Stderr = logx.Writer("[mlx]"), logx.Writer("[mlx]")
- if err := check.Run(); err != nil {
- return errors.New("mlx-vlm installed but its Bonsai 2 loader is missing (see log)")
+ modulePaths, err := mlxImportFiles(ctx, py)
+ if err != nil {
+ return err
+ }
+ manifest, err := installedMLXManifest(modulePaths)
+ if err != nil {
+ return fmt.Errorf("verify MLX environment: %w", err)
}
- return os.WriteFile(filepath.Join(mlxVenv(), ".installed"), []byte(strings.Join(mlxRequirements, "\n")+"\n"), 0o644)
+ return os.WriteFile(filepath.Join(mlxVenv(), ".installed"), manifest, 0o644)
}
// trustMacBinaries clears quarantine and ad-hoc signs downloaded executables
@@ -754,6 +852,13 @@ func (m *Manager) Start() (startErr error) {
return errors.New("the MLX pack is not installed")
}
py := filepath.Join(mlxVenv(), "bin", "python")
+ checkCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+ _, checkErr := mlxImportFiles(checkCtx, py)
+ cancel()
+ if checkErr != nil {
+ _ = os.Remove(filepath.Join(mlxVenv(), ".installed"))
+ return fmt.Errorf("MLX environment is damaged; reinstall it: %w", checkErr)
+ }
upstream = mlxDir()
cmd = osutil.Command(py, "-m", "mlx_vlm.server", "--model", mlxDir(), "--host", "127.0.0.1",
"--port", fmt.Sprint(port), "--enable-thinking")
@@ -870,7 +975,7 @@ func (m *Manager) registrationFailed(err error) {
func (m *Manager) waitForExit(cmd *exec.Cmd, exited chan struct{}) {
defer close(exited)
err := cmd.Wait()
- _ = m.register(nil)
+ unregisterErr := m.register(nil)
m.mu.Lock()
why := m.stopErr
if !m.stopping {
@@ -881,6 +986,9 @@ func (m *Manager) waitForExit(cmd *exec.Cmd, exited chan struct{}) {
logx.Printf("%s", msg)
why = errors.New(msg + " (see log)")
}
+ if unregisterErr != nil {
+ why = errors.Join(why, fmt.Errorf("unregister stopped local model: %w", unregisterErr))
+ }
m.cmd, m.port, m.startedAt, m.stopErr = nil, 0, nil, nil
m.phase, m.step, m.err, m.progress = PhaseIdle, "", "", nil
if why != nil {
@@ -890,14 +998,14 @@ func (m *Manager) waitForExit(cmd *exec.Cmd, exited chan struct{}) {
m.changed()
}
-// Stop terminates the local server.
-func (m *Manager) Stop() {
+// Stop unregisters and terminates the local server. A failed unregister is
+// reported even if the process has already exited.
+func (m *Manager) Stop() error {
m.mu.Lock()
if starting := m.starting; starting != nil {
m.mu.Unlock()
<-starting
- m.Stop()
- return
+ return m.Stop()
}
cmd, exited := m.cmd, m.exited
m.stopping = true
@@ -905,9 +1013,15 @@ func (m *Manager) Stop() {
m.phase = PhaseStopping
}
m.mu.Unlock()
- _ = m.register(nil)
+ unregisterErr := m.register(nil)
+ if unregisterErr != nil {
+ logx.Printf("unregister local model while stopping: %v", unregisterErr)
+ }
if cmd == nil || cmd.Process == nil {
- return
+ if unregisterErr != nil {
+ m.setPhase(PhaseError, "", fmt.Errorf("unregister stopped local model: %w", unregisterErr))
+ }
+ return unregisterErr
}
m.changed()
terminate(cmd)
@@ -917,6 +1031,13 @@ func (m *Manager) Stop() {
_ = cmd.Process.Kill()
<-exited
}
+ m.mu.Lock()
+ phase, detail := m.phase, m.err
+ m.mu.Unlock()
+ if phase == PhaseError {
+ return errors.New(detail)
+ }
+ return nil
}
// Running reports whether the local server is up.
@@ -934,7 +1055,9 @@ func (m *Manager) Remove(format string) error {
if _, err := m.store.Update(func(s *settings.Settings) { s.Local.AutoStart = false }); err != nil {
return err
}
- m.Stop()
+ if err := m.Stop(); err != nil {
+ return err
+ }
var removeErrs []error
remove := func(path string) {
if err := os.RemoveAll(path); err != nil {
@@ -973,7 +1096,9 @@ func (m *Manager) Remove(format string) error {
// Restart applies new settings (vision mode, context) to a running server.
func (m *Manager) Restart() error {
running := m.Running()
- m.Stop()
+ if err := m.Stop(); err != nil {
+ return err
+ }
if running {
return m.Start()
}
diff --git a/webbrain-systray/internal/localmodel/manager_test.go b/webbrain-systray/internal/localmodel/manager_test.go
index c75dd1adb..67a6ed356 100644
--- a/webbrain-systray/internal/localmodel/manager_test.go
+++ b/webbrain-systray/internal/localmodel/manager_test.go
@@ -4,6 +4,7 @@ import (
"crypto/sha256"
"encoding/hex"
"errors"
+ "fmt"
"os"
"path/filepath"
"runtime"
@@ -320,11 +321,73 @@ func TestMLXEnvironmentRejectsStaleDependencies(t *testing.T) {
if mlxEnvironmentInstalled() {
t.Fatal("stale MLX dependency marker was accepted")
}
- if err := os.WriteFile(marker, []byte(strings.Join(mlxRequirements, "\n")+"\n"), 0o600); err != nil {
+ modulePaths := make([]string, 5)
+ for i := range modulePaths {
+ modulePaths[i] = filepath.Join(mlxVenv(), "lib", "python3.11", "site-packages", fmt.Sprintf("module-%d.py", i))
+ if err := os.MkdirAll(filepath.Dir(modulePaths[i]), 0o700); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(modulePaths[i], []byte("module"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ }
+ manifest, err := installedMLXManifest(modulePaths)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(marker, manifest, 0o600); err != nil {
t.Fatal(err)
}
if !mlxEnvironmentInstalled() {
- t.Fatal("current MLX dependency marker was rejected")
+ t.Fatal("verified MLX environment was rejected")
+ }
+ if err := os.Remove(modulePaths[2]); err != nil {
+ t.Fatal(err)
+ }
+ if mlxEnvironmentInstalled() {
+ t.Fatal("MLX environment missing an installed package was accepted")
+ }
+ if err := os.WriteFile(modulePaths[2], []byte("module"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ if runtime.GOOS != "windows" {
+ if err := os.Chmod(filepath.Join(bin, "python"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ if mlxEnvironmentInstalled() {
+ t.Fatal("MLX environment with a non-executable Python was accepted")
+ }
+ }
+}
+
+func TestStopReportsFailedLocalModelUnregister(t *testing.T) {
+ executable, err := os.Executable()
+ if err != nil {
+ t.Fatal(err)
+ }
+ cmd := osutil.Command(executable, "-test.run=^TestLocalModelWaitHelper$")
+ cmd.Env = append(os.Environ(), "WBC_WAIT_HELPER=1")
+ if err := cmd.Start(); err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { _ = cmd.Process.Kill() })
+ var calls atomic.Int32
+ m := NewManager(nil, func([]core.LocalUpstream) error {
+ calls.Add(1)
+ return errors.New("proxy config is read-only")
+ }, nil)
+ m.cmd, m.exited, m.phase = cmd, make(chan struct{}), PhaseRunning
+ go m.waitForExit(cmd, m.exited)
+ if err := m.Stop(); err == nil || !strings.Contains(err.Error(), "proxy config is read-only") {
+ t.Fatalf("Stop hid unregister failure: %v", err)
+ }
+ if calls.Load() < 2 {
+ t.Fatalf("expected unregister retry after process exit, got %d calls", calls.Load())
+ }
+ m.mu.Lock()
+ defer m.mu.Unlock()
+ if m.phase != PhaseError || !strings.Contains(m.err, "proxy config is read-only") {
+ t.Fatalf("failed unregister reported phase=%q error=%q", m.phase, m.err)
}
}