shadow-claw 1.27.0 → 1.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shadow-claw",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "type": "module",
   "license": "AGPL-3.0",
   "description": "Browser-native personal AI assistant.",
@@ -55,6 +55,7 @@
   },
   "homepage": "https://github.com/xt-ml/shadow-claw#readme",
   "scripts": {
+    "version": "node bin/version.mjs",
     "prepack": "npm run build:prod",
     "assert:version": "node bin/assert-version-bump.mjs",
     "build:clean": "node bin/rimraf.mjs dist && node bin/rimraf.mjs dist-electron",

package/src/components/settings/shadow-claw-control-plane/shadow-claw-control-plane.test.ts

@@ -60,6 +60,12 @@ describe("shadow-claw-control-plane", () => {
     expect(getControlPlaneTargetAddressSpace("https://172.20.0.1:8888")).toBe(
       "private",
     );
+    expect(getControlPlaneTargetAddressSpace("https://hostname:8888")).toBe(
+      "private",
+    );
+    expect(
+      getControlPlaneTargetAddressSpace("https://hostname.local:8888"),
+    ).toBe("private");
     expect(
       getControlPlaneTargetAddressSpace("https://my-server.example.com"),
     ).toBeUndefined();

package/src/components/settings/shadow-claw-control-plane/shadow-claw-control-plane.ts

@@ -37,9 +37,13 @@ export function getControlPlaneTargetAddressSpace(
     if (isLoopback) {
       return "loopback";
     }
-    const isPrivate = /^(10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.)/.test(
-      hostname,
-    );
+    const isPrivate =
+      /^(10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.)/.test(hostname) ||
+      !hostname.includes(".") ||
+      hostname.endsWith(".local") ||
+      hostname.endsWith(".lan") ||
+      hostname.endsWith(".home") ||
+      hostname.endsWith(".internal");
     if (isPrivate) {
       return "private";
     }
@@ -309,7 +313,7 @@ export class ShadowClawControlPlane extends ShadowClawElement {
 
       const {
         isControlPlaneEnabled,
-        createDefaultControlPlaneClient,
+        ensureControlPlaneConnected,
         shouldConnectControlPlane,
       } = await import("../../../core/utils/initControlPlane.js");
 
@@ -317,8 +321,10 @@ export class ShadowClawControlPlane extends ShadowClawElement {
         (await isControlPlaneEnabled(this.db)) &&
         shouldConnectControlPlane()
       ) {
-        createDefaultControlPlaneClient({
+        await ensureControlPlaneConnected({
           orchestrator: this.orchestrator || undefined,
+          db: this.db,
+          force: true,
           transport,
         });
       }
@@ -371,7 +377,7 @@ export class ShadowClawControlPlane extends ShadowClawElement {
 
       const {
         isControlPlaneEnabled,
-        createDefaultControlPlaneClient,
+        ensureControlPlaneConnected,
         shouldConnectControlPlane,
       } = await import("../../../core/utils/initControlPlane.js");
 
@@ -379,8 +385,10 @@ export class ShadowClawControlPlane extends ShadowClawElement {
         (await isControlPlaneEnabled(this.db)) &&
         shouldConnectControlPlane()
       ) {
-        createDefaultControlPlaneClient({
+        await ensureControlPlaneConnected({
           orchestrator: this.orchestrator || undefined,
+          db: this.db,
+          force: true,
         });
       }
 
@@ -424,15 +432,17 @@ export class ShadowClawControlPlane extends ShadowClawElement {
       }
 
       const {
-        createDefaultControlPlaneClient,
+        ensureControlPlaneConnected,
         stopControlPlaneClient,
         shouldConnectControlPlane,
       } = await import("../../../core/utils/initControlPlane.js");
 
       if (enabled) {
         if (shouldConnectControlPlane()) {
-          createDefaultControlPlaneClient({
+          await ensureControlPlaneConnected({
             orchestrator: this.orchestrator || undefined,
+            db: this.db,
+            force: true,
           });
         }
         showSuccess("Control plane client enabled and connected", 3000);

package/src/components/settings/shadow-claw-task-server/shadow-claw-task-server.test.ts

@@ -21,11 +21,15 @@ jest.unstable_mockModule(
   }),
 );
 
+const mockEnsureAllConnections = jest
+  .fn()
+  .mockResolvedValue(undefined as never);
 jest.unstable_mockModule("../../../stores/orchestrator.js", () => ({
   orchestratorStore: {
     orchestrator: {
       taskServerUrl: "/test-schedule",
       taskServerEnabled: true,
+      ensureAllConnections: mockEnsureAllConnections,
     },
     ready: true,
   },
@@ -81,6 +85,7 @@ describe("shadow-claw-task-server", () => {
       "https://new-server.com",
     );
     expect(showSuccess).toHaveBeenCalled();
+    expect(mockEnsureAllConnections).toHaveBeenCalled();
   });
 
   it("should save task server enabled toggle", async () => {
@@ -95,5 +100,14 @@ describe("shadow-claw-task-server", () => {
       expect.anything(),
       false,
     );
+
+    mockEnsureAllConnections.mockClear();
+    await el.saveTaskServerEnabled(true);
+    expect(mockSetTaskServerEnabled).toHaveBeenCalledWith(
+      orchestratorStore.orchestrator,
+      expect.anything(),
+      true,
+    );
+    expect(mockEnsureAllConnections).toHaveBeenCalled();
   });
 });

package/src/components/settings/shadow-claw-task-server/shadow-claw-task-server.ts

@@ -108,6 +108,12 @@ export class ShadowClawTaskServer extends ShadowClawElement {
 
     try {
       await setTaskServerEnabled(this.orchestrator, this.db, enabled);
+      if (
+        enabled &&
+        typeof this.orchestrator.ensureAllConnections === "function"
+      ) {
+        void this.orchestrator.ensureAllConnections();
+      }
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);
       showError("Error saving Task Server setting: " + errorMsg, 6000);
@@ -135,6 +141,12 @@ export class ShadowClawTaskServer extends ShadowClawElement {
 
     try {
       await setTaskServerUrl(this.orchestrator, this.db, url || "/schedule");
+      if (
+        this.orchestrator.taskServerEnabled &&
+        typeof this.orchestrator.ensureAllConnections === "function"
+      ) {
+        void this.orchestrator.ensureAllConnections();
+      }
       showSuccess("Task Server URL saved", 3000);
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);

package/src/components/shadow-claw/shadow-claw.ts

@@ -88,6 +88,7 @@ export class ShadowClaw extends ShadowClawElement {
   };
 
   vmStatusCleanup: (() => void) | null = null;
+  appLifecycleCleanup: (() => void) | null = null;
 
   constructor() {
     super();
@@ -251,6 +252,11 @@ export class ShadowClaw extends ShadowClawElement {
       this.vmStatusCleanup = null;
     }
 
+    if (this.appLifecycleCleanup) {
+      this.appLifecycleCleanup();
+      this.appLifecycleCleanup = null;
+    }
+
     if (this.terminalPlacementFrame !== null) {
       cancelAnimationFrame(this.terminalPlacementFrame);
       this.terminalPlacementFrame = null;

package/src/components/shadow-claw/utils/bindEventListeners.test.ts

@@ -27,6 +27,8 @@ describe("bindEventListeners", () => {
   let mockUpdateHeaderMainToggle: jest.Mock<any>;
   let mockUpdateHostTheme: jest.Mock<any>;
   let mockUpdateThemeIcons: jest.Mock<any>;
+  let mockSetupAppLifecycle: jest.Mock<any>;
+  let mockLifecycleCleanup: jest.Mock<any>;
 
   beforeEach(async () => {
     jest.resetModules();
@@ -54,6 +56,11 @@ describe("bindEventListeners", () => {
     jest.unstable_mockModule("./supportsNavigationApi.js", () => ({
       supportsNavigationApi: jest.fn(),
     }));
+    mockLifecycleCleanup = jest.fn();
+    mockSetupAppLifecycle = jest.fn(() => mockLifecycleCleanup);
+    jest.unstable_mockModule("./setupAppLifecycle.js", () => ({
+      setupAppLifecycle: mockSetupAppLifecycle,
+    }));
     jest.unstable_mockModule(
       "./syncPageHeaderMainVisibilityOverride.js",
       () => ({
@@ -940,4 +947,54 @@ describe("bindEventListeners", () => {
       );
     });
   });
+
+  describe("app lifecycle", () => {
+    it("should set up app lifecycle listener when orchestrator is present", () => {
+      shadowClaw.orchestrator = { ensureAllConnections: jest.fn() };
+
+      bindEventListeners(
+        win,
+        doc,
+        shadow,
+        shadowClaw,
+        db,
+        oStore,
+        fStore,
+        tStore,
+        url,
+      );
+
+      expect(mockSetupAppLifecycle).toHaveBeenCalledWith(
+        win,
+        doc,
+        shadowClaw.orchestrator,
+      );
+      expect(shadowClaw.appLifecycleCleanup).toBe(mockLifecycleCleanup);
+    });
+
+    it("should clean up previous app lifecycle listener before setting up new one", () => {
+      const prevCleanup = jest.fn();
+      shadowClaw.appLifecycleCleanup = prevCleanup;
+      shadowClaw.orchestrator = { ensureAllConnections: jest.fn() };
+
+      bindEventListeners(
+        win,
+        doc,
+        shadow,
+        shadowClaw,
+        db,
+        oStore,
+        fStore,
+        tStore,
+        url,
+      );
+
+      expect(prevCleanup).toHaveBeenCalled();
+      expect(mockSetupAppLifecycle).toHaveBeenCalledWith(
+        win,
+        doc,
+        shadowClaw.orchestrator,
+      );
+    });
+  });
 });

package/src/components/shadow-claw/utils/bindEventListeners.ts

@@ -10,6 +10,7 @@ import {
 } from "./setPagesSidebarHidden.js";
 import { showPage } from "./showPage.js";
 import { supportsNavigationApi } from "./supportsNavigationApi.js";
+import { setupAppLifecycle } from "./setupAppLifecycle.js";
 import { syncPageHeaderMainVisibilityOverride } from "./syncPageHeaderMainVisibilityOverride.js";
 
 import { toggleActivityLogVisibility } from "./toggleActivityLogVisibility.js";
@@ -298,4 +299,17 @@ export function bindEventListeners(
   const currentTheme = tStore.resolved;
   updateThemeIcons(shadow, currentTheme);
   updateHostTheme(currentTheme, shadowClaw.classList);
+
+  if (shadowClaw.appLifecycleCleanup) {
+    shadowClaw.appLifecycleCleanup();
+    shadowClaw.appLifecycleCleanup = null;
+  }
+
+  if (shadowClaw.orchestrator) {
+    shadowClaw.appLifecycleCleanup = setupAppLifecycle(
+      win,
+      doc,
+      shadowClaw.orchestrator,
+    );
+  }
 }

package/src/components/shadow-claw/utils/setupAppLifecycle.test.ts

@@ -0,0 +1,201 @@
+import { jest } from "@jest/globals";
+import { setupAppLifecycle } from "./setupAppLifecycle.js";
+
+describe("setupAppLifecycle", () => {
+  let win: any;
+  let doc: any;
+  let orchestrator: any;
+  let winListeners: Record<string, Function>;
+  let docListeners: Record<string, Function>;
+
+  beforeEach(() => {
+    jest.useFakeTimers();
+    winListeners = {};
+    docListeners = {};
+
+    win = {
+      addEventListener: jest.fn((event: string, handler: Function) => {
+        winListeners[event] = handler;
+      }),
+      removeEventListener: jest.fn((event: string) => {
+        delete winListeners[event];
+      }),
+    };
+
+    doc = {
+      visibilityState: "visible",
+      addEventListener: jest.fn((event: string, handler: Function) => {
+        docListeners[event] = handler;
+      }),
+      removeEventListener: jest.fn((event: string) => {
+        delete docListeners[event];
+      }),
+    };
+
+    orchestrator = {
+      ensureAllConnections: jest.fn().mockResolvedValue(undefined as never),
+    };
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it("registers event listeners on win and doc", () => {
+    const cleanup = setupAppLifecycle(win, doc, orchestrator);
+
+    expect(doc.addEventListener).toHaveBeenCalledWith(
+      "visibilitychange",
+      expect.any(Function),
+    );
+    expect(win.addEventListener).toHaveBeenCalledWith(
+      "pageshow",
+      expect.any(Function),
+    );
+    expect(win.addEventListener).toHaveBeenCalledWith(
+      "focus",
+      expect.any(Function),
+    );
+    expect(win.addEventListener).toHaveBeenCalledWith(
+      "online",
+      expect.any(Function),
+    );
+
+    cleanup();
+
+    expect(doc.removeEventListener).toHaveBeenCalledWith(
+      "visibilitychange",
+      expect.any(Function),
+    );
+    expect(win.removeEventListener).toHaveBeenCalledWith(
+      "pageshow",
+      expect.any(Function),
+    );
+    expect(win.removeEventListener).toHaveBeenCalledWith(
+      "focus",
+      expect.any(Function),
+    );
+    expect(win.removeEventListener).toHaveBeenCalledWith(
+      "online",
+      expect.any(Function),
+    );
+  });
+
+  it("triggers ensureAllConnections({ force: true }) on wake up from sleep (> 1000ms hidden)", () => {
+    setupAppLifecycle(win, doc, orchestrator, {
+      debounceMs: 100,
+      minSleepDurationMs: 1000,
+    });
+
+    // App goes to sleep / hidden
+    doc.visibilityState = "hidden";
+    docListeners["visibilitychange"]();
+
+    // Advance time by 5 seconds while phone sleeps
+    jest.advanceTimersByTime(5000);
+
+    // App wakes up
+    doc.visibilityState = "visible";
+    docListeners["visibilitychange"]();
+
+    // Before debounce timer fires
+    expect(orchestrator.ensureAllConnections).not.toHaveBeenCalled();
+
+    // Advance past debounce
+    jest.advanceTimersByTime(100);
+
+    expect(orchestrator.ensureAllConnections).toHaveBeenCalledWith({
+      force: true,
+    });
+  });
+
+  it("triggers ensureAllConnections({ force: false }) on short tab switch (< 1000ms hidden)", () => {
+    setupAppLifecycle(win, doc, orchestrator, {
+      debounceMs: 100,
+      minSleepDurationMs: 1000,
+    });
+
+    doc.visibilityState = "hidden";
+    docListeners["visibilitychange"]();
+
+    // Only hidden for 200ms
+    jest.advanceTimersByTime(200);
+
+    doc.visibilityState = "visible";
+    docListeners["visibilitychange"]();
+
+    jest.advanceTimersByTime(100);
+
+    expect(orchestrator.ensureAllConnections).toHaveBeenCalledWith({
+      force: false,
+    });
+  });
+
+  it("coalesces rapid resume events (visibilitychange, pageshow, focus, online)", () => {
+    setupAppLifecycle(win, doc, orchestrator, {
+      debounceMs: 250,
+      minSleepDurationMs: 1000,
+    });
+
+    doc.visibilityState = "hidden";
+    docListeners["visibilitychange"]();
+    jest.advanceTimersByTime(2000);
+
+    // Device wakes up
+    doc.visibilityState = "visible";
+    docListeners["visibilitychange"]();
+
+    // Chrome fires pageshow, focus, online right after
+    jest.advanceTimersByTime(20);
+    winListeners["pageshow"]?.({ persisted: true });
+
+    jest.advanceTimersByTime(20);
+    winListeners["focus"]?.();
+
+    jest.advanceTimersByTime(20);
+    winListeners["online"]?.();
+
+    // Total 60ms elapsed, still within 250ms debounce
+    expect(orchestrator.ensureAllConnections).not.toHaveBeenCalled();
+
+    // Advance remaining debounce time
+    jest.advanceTimersByTime(250);
+
+    // Should only be called ONCE
+    expect(orchestrator.ensureAllConnections).toHaveBeenCalledTimes(1);
+    expect(orchestrator.ensureAllConnections).toHaveBeenCalledWith({
+      force: true,
+    });
+  });
+
+  it("cancels pending reconnect if app goes hidden again during debounce", () => {
+    setupAppLifecycle(win, doc, orchestrator, { debounceMs: 250 });
+
+    doc.visibilityState = "visible";
+    docListeners["visibilitychange"]();
+
+    // Debounce is pending
+    expect(orchestrator.ensureAllConnections).not.toHaveBeenCalled();
+
+    // User immediately switches away / phone locks before debounce expires
+    doc.visibilityState = "hidden";
+    docListeners["visibilitychange"]();
+
+    // Advance past debounce
+    jest.advanceTimersByTime(500);
+
+    expect(orchestrator.ensureAllConnections).not.toHaveBeenCalled();
+  });
+
+  it("cleanup cancels any pending debounce timer", () => {
+    const cleanup = setupAppLifecycle(win, doc, orchestrator, {
+      debounceMs: 250,
+    });
+
+    winListeners["online"]();
+    cleanup();
+
+    jest.advanceTimersByTime(500);
+    expect(orchestrator.ensureAllConnections).not.toHaveBeenCalled();
+  });
+});

package/src/components/shadow-claw/utils/setupAppLifecycle.ts

@@ -0,0 +1,101 @@
+/**
+ * ShadowClaw — App Lifecycle & Connection Health Management
+ *
+ * Listens for mobile sleep / wake, tab switching, and network changes:
+ * - visibilitychange: detects when the app/tab is backgrounded or brought back to foreground.
+ *   If the app was backgrounded for longer than minSleepDurationMs (default: 1000ms),
+ *   it indicates the device went to sleep or user switched away, requiring forced reconnection.
+ * - pageshow: handles bfcache restoration and page reveal.
+ * - focus: handles window/tab focus.
+ * - online: handles network connectivity resumption.
+ *
+ * Coalesces rapid succession of resume events via a debounce window (default: 250ms).
+ */
+
+export interface AppLifecycleOptions {
+  debounceMs?: number;
+  minSleepDurationMs?: number;
+}
+
+export interface MinimalOrchestrator {
+  ensureAllConnections(options?: { force?: boolean }): Promise<void>;
+}
+
+export function setupAppLifecycle(
+  win: Window,
+  doc: Document,
+  orchestrator: MinimalOrchestrator,
+  options: AppLifecycleOptions = {},
+): () => void {
+  const debounceMs = options.debounceMs ?? 250;
+  const minSleepDurationMs = options.minSleepDurationMs ?? 1000;
+
+  let lastHiddenTime = 0;
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  let pendingForce = false;
+
+  const triggerReconnect = (force: boolean) => {
+    if (force) {
+      pendingForce = true;
+    }
+
+    if (debounceTimer !== null) {
+      clearTimeout(debounceTimer);
+    }
+
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      const shouldForce = pendingForce;
+      pendingForce = false;
+      void orchestrator.ensureAllConnections({ force: shouldForce });
+    }, debounceMs);
+  };
+
+  const cancelPendingReconnect = () => {
+    if (debounceTimer !== null) {
+      clearTimeout(debounceTimer);
+      debounceTimer = null;
+    }
+    pendingForce = false;
+  };
+
+  const onVisibilityChange = () => {
+    if (doc.visibilityState === "hidden") {
+      lastHiddenTime = Date.now();
+      cancelPendingReconnect();
+    } else if (doc.visibilityState === "visible") {
+      const now = Date.now();
+      const wasAsleep =
+        lastHiddenTime > 0 && now - lastHiddenTime >= minSleepDurationMs;
+      triggerReconnect(wasAsleep);
+    }
+  };
+
+  const onPageShow = (event?: PageTransitionEvent) => {
+    const isPersisted = Boolean(event && event.persisted);
+    triggerReconnect(isPersisted || doc.visibilityState === "visible");
+  };
+
+  const onFocus = () => {
+    if (doc.visibilityState === "visible") {
+      triggerReconnect(false);
+    }
+  };
+
+  const onOnline = () => {
+    triggerReconnect(true);
+  };
+
+  doc.addEventListener("visibilitychange", onVisibilityChange);
+  win.addEventListener("pageshow", onPageShow);
+  win.addEventListener("focus", onFocus);
+  win.addEventListener("online", onOnline);
+
+  return () => {
+    cancelPendingReconnect();
+    doc.removeEventListener("visibilitychange", onVisibilityChange);
+    win.removeEventListener("pageshow", onPageShow);
+    win.removeEventListener("focus", onFocus);
+    win.removeEventListener("online", onOnline);
+  };
+}