@agent-native/dispatch 0.41.1-nightly-20261104110058 → 0.42.0

package/src/lib/workspace-app-layout.store.spec.tsx

@@ -0,0 +1,261 @@
+// @vitest-environment happy-dom
+import { CHAT_FIRST_APP_LAYOUT_STORAGE_KEY } from "@agent-native/core/client/agent-chat";
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const appState = vi.hoisted(() => ({
+  read: vi.fn(),
+  write: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/client/application-state", () => ({
+  readClientAppState: appState.read,
+  writeClientAppState: appState.write,
+}));
+
+import {
+  resetWorkspaceAppLayoutStoreForTests,
+  useWorkspaceAppLayout,
+  WORKSPACE_APP_LAYOUT_STATE_KEY,
+} from "./workspace-app-layout";
+
+function Surface({ name, appId }: { name: string; appId: string }) {
+  const { layout, persistenceError, togglePinned } = useWorkspaceAppLayout();
+  return (
+    <button
+      type="button"
+      data-surface={name}
+      data-pinned={layout.pinnedIds.join(",")}
+      data-error={persistenceError?.scope ?? ""}
+      onClick={() => togglePinned(appId)}
+    />
+  );
+}
+
+describe("useWorkspaceAppLayout", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    resetWorkspaceAppLayoutStoreForTests();
+    localStorage.clear();
+    appState.read.mockReset().mockResolvedValue(null);
+    appState.write.mockReset().mockResolvedValue(null);
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+  });
+
+  const surface = (name: string) =>
+    container.querySelector<HTMLButtonElement>(`[data-surface="${name}"]`)!;
+
+  it("shares one layout so a pin on one surface never drops another's", async () => {
+    await act(async () => {
+      root.render(
+        <>
+          <Surface name="home" appId="mail" />
+          <Surface name="rail" appId="plan" />
+        </>,
+      );
+    });
+
+    await act(async () => surface("home").click());
+    await act(async () => surface("rail").click());
+
+    expect(surface("home").dataset.pinned).toBe("plan,mail");
+    expect(surface("rail").dataset.pinned).toBe("plan,mail");
+    expect(appState.write).toHaveBeenLastCalledWith(
+      WORKSPACE_APP_LAYOUT_STATE_KEY,
+      { pinnedIds: ["plan", "mail"], orderedIds: [] },
+    );
+    expect(
+      JSON.parse(localStorage.getItem(CHAT_FIRST_APP_LAYOUT_STORAGE_KEY)!),
+    ).toEqual({ pinnedIds: ["plan", "mail"], orderedIds: [] });
+  });
+
+  it("replays a pin made before workspace state loads onto the saved pins", async () => {
+    let resolveRead: (value: unknown) => void = () => {};
+    appState.read.mockReturnValue(
+      new Promise((resolve) => {
+        resolveRead = resolve;
+      }),
+    );
+    await act(async () => {
+      root.render(
+        <>
+          <Surface name="home" appId="mail" />
+          <Surface name="rail" appId="plan" />
+        </>,
+      );
+    });
+    expect(appState.read).toHaveBeenCalledOnce();
+
+    await act(async () => surface("home").click());
+    expect(appState.write).not.toHaveBeenCalled();
+    await act(async () => {
+      resolveRead({ pinnedIds: ["calendar", "notes"], orderedIds: [] });
+    });
+
+    const replayed = {
+      pinnedIds: ["mail", "calendar", "notes"],
+      orderedIds: [],
+    };
+    expect(surface("rail").dataset.pinned).toBe("mail,calendar,notes");
+    expect(appState.write).toHaveBeenCalledOnce();
+    expect(appState.write).toHaveBeenCalledWith(
+      WORKSPACE_APP_LAYOUT_STATE_KEY,
+      replayed,
+    );
+    expect(
+      JSON.parse(localStorage.getItem(CHAT_FIRST_APP_LAYOUT_STORAGE_KEY)!),
+    ).toEqual(replayed);
+  });
+
+  it("keeps a pin's intent when the workspace already had it pinned", async () => {
+    // A new device shows no pins; the workspace pinned mail elsewhere.
+    let resolveRead: (value: unknown) => void = () => {};
+    appState.read.mockReturnValue(
+      new Promise((resolve) => {
+        resolveRead = resolve;
+      }),
+    );
+    await act(async () => {
+      root.render(<Surface name="home" appId="mail" />);
+    });
+
+    await act(async () => surface("home").click());
+    await act(async () => {
+      resolveRead({ pinnedIds: ["mail", "notes"], orderedIds: [] });
+    });
+
+    expect(surface("home").dataset.pinned).toBe("mail,notes");
+    expect(appState.write).toHaveBeenCalledWith(
+      WORKSPACE_APP_LAYOUT_STATE_KEY,
+      { pinnedIds: ["mail", "notes"], orderedIds: [] },
+    );
+  });
+
+  it("renders an empty layout on the server even with device pins", () => {
+    localStorage.setItem(
+      CHAT_FIRST_APP_LAYOUT_STORAGE_KEY,
+      JSON.stringify({ pinnedIds: ["mail"], orderedIds: [] }),
+    );
+
+    expect(renderToString(<Surface name="home" appId="mail" />)).toContain(
+      'data-pinned=""',
+    );
+  });
+
+  it("adopts workspace pins when nothing changed locally", async () => {
+    appState.read.mockResolvedValue({
+      pinnedIds: ["Calendar"],
+      orderedIds: [],
+    });
+    await act(async () => {
+      root.render(<Surface name="home" appId="mail" />);
+    });
+
+    expect(surface("home").dataset.pinned).toBe("calendar");
+    expect(appState.write).not.toHaveBeenCalled();
+    expect(
+      JSON.parse(localStorage.getItem(CHAT_FIRST_APP_LAYOUT_STORAGE_KEY)!),
+    ).toEqual({ pinnedIds: ["calendar"], orderedIds: [] });
+    await act(async () => surface("home").click());
+    expect(surface("home").dataset.pinned).toBe("mail,calendar");
+  });
+
+  it("never writes workspace state it could not read, and replays once it can", async () => {
+    appState.read
+      .mockRejectedValueOnce(new Error("offline"))
+      .mockRejectedValueOnce(new Error("offline"))
+      .mockResolvedValueOnce({ pinnedIds: ["calendar"], orderedIds: [] });
+    await act(async () => {
+      root.render(
+        <>
+          <Surface name="home" appId="mail" />
+          <Surface name="rail" appId="plan" />
+        </>,
+      );
+    });
+    // A failed read with nothing unsaved is not reported.
+    expect(surface("home").dataset.error).toBe("");
+
+    await act(async () => surface("home").click());
+    expect(surface("home").dataset.pinned).toBe("mail");
+    expect(surface("home").dataset.error).toBe("workspace");
+    expect(appState.write).not.toHaveBeenCalled();
+    expect(
+      JSON.parse(localStorage.getItem(CHAT_FIRST_APP_LAYOUT_STORAGE_KEY)!),
+    ).toEqual({ pinnedIds: ["mail"], orderedIds: [] });
+
+    // The next change retries the read and replays both onto the saved pins.
+    await act(async () => surface("rail").click());
+    const replayed = {
+      pinnedIds: ["plan", "mail", "calendar"],
+      orderedIds: [],
+    };
+    expect(appState.read).toHaveBeenCalledTimes(3);
+    expect(surface("rail").dataset.pinned).toBe("plan,mail,calendar");
+    expect(appState.write).toHaveBeenCalledOnce();
+    expect(appState.write).toHaveBeenCalledWith(
+      WORKSPACE_APP_LAYOUT_STATE_KEY,
+      replayed,
+    );
+    expect(surface("rail").dataset.error).toBe("");
+  });
+
+  it("retries an unreadable workspace layout when a surface mounts again", async () => {
+    appState.read
+      .mockRejectedValueOnce(new Error("offline"))
+      .mockResolvedValueOnce({ pinnedIds: ["calendar"], orderedIds: [] });
+    await act(async () => {
+      root.render(<Surface name="home" appId="mail" />);
+    });
+    expect(surface("home").dataset.error).toBe("");
+
+    act(() => root.unmount());
+    root = createRoot(container);
+    await act(async () => {
+      root.render(<Surface name="home" appId="mail" />);
+    });
+
+    expect(surface("home").dataset.pinned).toBe("calendar");
+    expect(surface("home").dataset.error).toBe("");
+    expect(appState.write).not.toHaveBeenCalled();
+  });
+
+  it("keeps device pins over a malformed workspace layout, then replaces it", async () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const device = { pinnedIds: ["mail"], orderedIds: [] };
+    localStorage.setItem(
+      CHAT_FIRST_APP_LAYOUT_STORAGE_KEY,
+      JSON.stringify(device),
+    );
+    appState.read.mockResolvedValue({ pinnedIds: "mail" });
+
+    await act(async () => {
+      root.render(<Surface name="home" appId="plan" />);
+    });
+
+    expect(surface("home").dataset.pinned).toBe("mail");
+    expect(
+      JSON.parse(localStorage.getItem(CHAT_FIRST_APP_LAYOUT_STORAGE_KEY)!),
+    ).toEqual(device);
+    expect(appState.write).not.toHaveBeenCalled();
+
+    await act(async () => surface("home").click());
+    expect(appState.write).toHaveBeenLastCalledWith(
+      WORKSPACE_APP_LAYOUT_STATE_KEY,
+      { pinnedIds: ["plan", "mail"], orderedIds: [] },
+    );
+  });
+});

package/src/lib/workspace-app-layout.ts

@@ -8,7 +8,7 @@ import {
   readClientAppState,
   writeClientAppState,
 } from "@agent-native/core/client/application-state";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useEffect, useSyncExternalStore } from "react";
 
 export const WORKSPACE_APP_LAYOUT_STATE_KEY = "chat-first-app-layout";
 
@@ -59,7 +59,7 @@ export function orderWorkspaceApps<T extends { id: string }>(
 }
 
 export function workspaceAppMatchesQuery(
-  app: { name: string; description?: string },
+  app: { name: string; description?: string | undefined },
   query: string,
 ): boolean {
   const normalizedQuery = query.trim().toLowerCase();
@@ -69,63 +69,280 @@ export function workspaceAppMatchesQuery(
     .includes(normalizedQuery);
 }
 
-export function toggleWorkspaceAppPinned(
+/** Pins (newest first) or unpins `appId`; a no-op when it already matches. */
+export function setWorkspaceAppPinned(
   layout: ChatFirstAppLayoutPreference,
   appId: string,
+  pinned: boolean,
 ): ChatFirstAppLayoutPreference {
   const normalizedLayout = normalizeWorkspaceAppLayout(layout);
   const normalizedAppId = appId.trim().toLowerCase();
-  const pinnedIds = normalizedLayout.pinnedIds.includes(normalizedAppId)
-    ? normalizedLayout.pinnedIds.filter((id) => id !== normalizedAppId)
-    : [normalizedAppId, ...normalizedLayout.pinnedIds];
+  const isPinned = normalizedLayout.pinnedIds.includes(normalizedAppId);
+  if (isPinned === pinned) return normalizedLayout;
+  const pinnedIds = pinned
+    ? [normalizedAppId, ...normalizedLayout.pinnedIds]
+    : normalizedLayout.pinnedIds.filter((id) => id !== normalizedAppId);
   return { ...normalizedLayout, pinnedIds };
 }
 
-export function useWorkspaceAppLayout() {
-  const [layout, setLayout] = useState<ChatFirstAppLayoutPreference>(() =>
-    normalizeWorkspaceAppLayout(readChatFirstAppLayout()),
+export type WorkspaceAppsStatus = "loading" | "error" | "ready";
+
+/**
+ * The workspace app list is known once it has arrived, and a failed refresh
+ * keeps the last one. Until then nothing can be tiered: an empty list is not
+ * "no apps", and a hosted app cannot be told from a mounted one.
+ */
+export function workspaceAppsStatus(query: {
+  data: unknown;
+  isError: boolean;
+}): WorkspaceAppsStatus {
+  if (query.data !== undefined) return "ready";
+  return query.isError ? "error" : "loading";
+}
+
+/**
+ * Both app lists: ready once workspace apps arrived and the hosted list has
+ * settled (arrived or failed), so the tiers, and the header actions placed by
+ * them, do not reshuffle when hosted apps land a moment later.
+ */
+export function appListsStatus(
+  workspaceApps: { data: unknown; isError: boolean },
+  connectedApps: { data: unknown; isError: boolean },
+): WorkspaceAppsStatus {
+  const status = workspaceAppsStatus(workspaceApps);
+  if (status !== "ready") return status;
+  return connectedApps.data === undefined && !connectedApps.isError
+    ? "loading"
+    : "ready";
+}
+
+/** Whether any of `apps` is pinned, before a search narrows the list. */
+export function hasPinnedWorkspaceApp(
+  apps: readonly { id: string }[],
+  layout: ChatFirstAppLayoutPreference,
+): boolean {
+  const pinned = new Set(normalizeWorkspaceAppLayout(layout).pinnedIds);
+  return apps.some((app) => pinned.has(app.id.trim().toLowerCase()));
+}
+
+export interface WorkspaceAppTiers<T> {
+  pinned: T[];
+  apps: T[];
+  hosted: T[];
+}
+
+export function compareWorkspaceAppNames(
+  a: { name: string },
+  b: { name: string },
+): number {
+  return a.name.localeCompare(b.name);
+}
+
+/**
+ * Pinned apps leave their home tier and keep pin order (newest first). The
+ * Apps and Hosted apps (built-in catalog) tiers each sort A to Z.
+ */
+export function tierWorkspaceApps<
+  T extends { id: string; name: string; source?: string | undefined },
+>(
+  apps: readonly T[],
+  layout: ChatFirstAppLayoutPreference,
+): WorkspaceAppTiers<T> {
+  const appsById = new Map(
+    apps.map((app) => [app.id.trim().toLowerCase(), app]),
   );
-  const [persistenceError, setPersistenceError] =
-    useState<WorkspaceAppLayoutPersistenceError | null>(null);
-  const hydratedRef = useRef(false);
-  const localChangeRef = useRef(false);
+  const pinned = normalizeWorkspaceAppLayout(layout)
+    .pinnedIds.map((id) => appsById.get(id))
+    .filter((app): app is T => Boolean(app));
+  const pinnedSet = new Set(pinned);
+  const unpinned = apps.filter((app) => !pinnedSet.has(app));
+  return {
+    pinned,
+    apps: unpinned
+      .filter((app) => app.source !== "builtin")
+      .sort(compareWorkspaceAppNames),
+    hosted: unpinned
+      .filter((app) => app.source === "builtin")
+      .sort(compareWorkspaceAppNames),
+  };
+}
 
-  useEffect(() => {
-    if (hydratedRef.current) return;
-    hydratedRef.current = true;
-    void readClientAppState<unknown>(WORKSPACE_APP_LAYOUT_STATE_KEY)
-      .then((value) => {
-        if (value !== null && !localChangeRef.current) {
-          setLayout(normalizeWorkspaceAppLayout(value));
-        }
-      })
-      .catch(() => {
-        // Device-local preferences remain usable when workspace state is unavailable.
-      });
-  }, []);
-
-  const persistLayout = useCallback((next: ChatFirstAppLayoutPreference) => {
-    localChangeRef.current = true;
-    const normalizedNext = normalizeWorkspaceAppLayout(next);
-    setLayout(normalizedNext);
-    const deviceResult = writeChatFirstAppLayout(normalizedNext);
-    const deviceFailed = !deviceResult.ok;
-
-    void writeClientAppState(WORKSPACE_APP_LAYOUT_STATE_KEY, normalizedNext)
-      .then(() => {
-        setPersistenceError(deviceFailed ? "device" : null);
-      })
-      .catch(() => {
-        setPersistenceError(deviceFailed ? "both" : "workspace");
-      });
-  }, []);
-
-  const togglePinned = useCallback(
-    (appId: string) => {
-      persistLayout(toggleWorkspaceAppPinned(layout, appId));
+interface WorkspaceAppLayoutSnapshot {
+  layout: ChatFirstAppLayoutPreference;
+  /** `writeId` is new for each save, so a dismissed notice shows again. */
+  persistenceError: {
+    scope: WorkspaceAppLayoutPersistenceError;
+    writeId: number;
+  } | null;
+}
+
+type WorkspaceAppLayoutUpdate = (
+  layout: ChatFirstAppLayoutPreference,
+) => ChatFirstAppLayoutPreference;
+
+const SERVER_SNAPSHOT: WorkspaceAppLayoutSnapshot = {
+  layout: { pinnedIds: [], orderedIds: [] },
+  persistenceError: null,
+};
+
+// One store per page: every surface reads and writes the same pins, so a
+// write always starts from the latest layout instead of a surface's copy.
+let snapshot: WorkspaceAppLayoutSnapshot | null = null;
+// Workspace state is written only after it has been read: until then a write
+// would replace saved pins this page never saw. "failed" retries the read.
+let hydration: "idle" | "pending" | "failed" | "done" = "idle";
+// Changes made before workspace state was read. They replay onto the read
+// layout, then persist.
+let pendingUpdates: WorkspaceAppLayoutUpdate[] = [];
+let deviceSaved = true;
+let writeSequence = 0;
+const listeners = new Set<() => void>();
+
+function currentSnapshot(): WorkspaceAppLayoutSnapshot {
+  snapshot ??= {
+    layout: normalizeWorkspaceAppLayout(readChatFirstAppLayout()),
+    persistenceError: null,
+  };
+  return snapshot;
+}
+
+function setSnapshot(next: Partial<WorkspaceAppLayoutSnapshot>) {
+  snapshot = { ...currentSnapshot(), ...next };
+  for (const listener of listeners) listener();
+}
+
+function writeDeviceLayout(next: ChatFirstAppLayoutPreference) {
+  deviceSaved = writeChatFirstAppLayout(next).ok;
+}
+
+function settlePersistence(writeId: number, workspaceSaved: boolean) {
+  if (writeId !== writeSequence) return;
+  const scope: WorkspaceAppLayoutPersistenceError | null = workspaceSaved
+    ? deviceSaved
+      ? null
+      : "device"
+    : deviceSaved
+      ? "workspace"
+      : "both";
+  setSnapshot({ persistenceError: scope ? { scope, writeId } : null });
+}
+
+function persistWorkspaceAppLayout(next: ChatFirstAppLayoutPreference) {
+  writeDeviceLayout(next);
+  const writeId = ++writeSequence;
+  void writeClientAppState(WORKSPACE_APP_LAYOUT_STATE_KEY, next).then(
+    () => settlePersistence(writeId, true),
+    () => settlePersistence(writeId, false),
+  );
+}
+
+function finishHydration(saved: ChatFirstAppLayoutPreference | null) {
+  hydration = "done";
+  const updates = pendingUpdates;
+  pendingUpdates = [];
+  // Absent workspace state keeps the device layout, which already holds the
+  // queued updates.
+  const next = saved
+    ? updates.reduce(
+        (layout, update) => normalizeWorkspaceAppLayout(update(layout)),
+        saved,
+      )
+    : currentSnapshot().layout;
+  setSnapshot({ layout: next });
+  if (updates.length > 0) {
+    persistWorkspaceAppLayout(next);
+    return;
+  }
+  if (saved) writeDeviceLayout(next);
+  // Nothing was saved before this read, so the only error it can clear is
+  // the earlier read failure.
+  setSnapshot({ persistenceError: null });
+}
+
+function isSavedWorkspaceAppLayout(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Record<string, unknown>;
+  return (
+    Array.isArray(candidate.pinnedIds) && Array.isArray(candidate.orderedIds)
+  );
+}
+
+function hydrateWorkspaceAppLayout() {
+  if (hydration === "pending" || hydration === "done") return;
+  hydration = "pending";
+  void readClientAppState<unknown>(WORKSPACE_APP_LAYOUT_STATE_KEY).then(
+    (value) => {
+      if (value === null) return finishHydration(null);
+      // A malformed value is not "no pins": treat it as absent so the device
+      // pins survive, and the next save replaces it.
+      if (!isSavedWorkspaceAppLayout(value)) {
+        console.warn(
+          `[dispatch] ignoring malformed ${WORKSPACE_APP_LAYOUT_STATE_KEY}`,
+          value,
+        );
+        return finishHydration(null);
+      }
+      finishHydration(normalizeWorkspaceAppLayout(value));
+    },
+    () => {
+      hydration = "failed";
+      // Only unsaved pins make a failed read worth reporting.
+      if (pendingUpdates.length > 0) settlePersistence(++writeSequence, false);
     },
-    [layout, persistLayout],
   );
+}
+
+function subscribe(listener: () => void) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
 
-  return { layout, persistenceError, persistLayout, togglePinned };
+export function updateWorkspaceAppLayout(update: WorkspaceAppLayoutUpdate) {
+  const next = normalizeWorkspaceAppLayout(update(currentSnapshot().layout));
+  setSnapshot({ layout: next });
+  if (hydration === "done") {
+    persistWorkspaceAppLayout(next);
+    return;
+  }
+  pendingUpdates.push(update);
+  writeDeviceLayout(next);
+  if (hydration === "failed") settlePersistence(++writeSequence, false);
+  hydrateWorkspaceAppLayout();
+}
+
+// The click decides pin or unpin from what is on screen, so a change replayed
+// onto workspace pins read later keeps that intent.
+function togglePinned(appId: string) {
+  const pinned = !currentSnapshot().layout.pinnedIds.includes(
+    appId.trim().toLowerCase(),
+  );
+  updateWorkspaceAppLayout((layout) =>
+    setWorkspaceAppPinned(layout, appId, pinned),
+  );
+}
+
+/** Test-only: forget the page's layout so the next read starts from storage. */
+export function resetWorkspaceAppLayoutStoreForTests() {
+  snapshot = null;
+  hydration = "idle";
+  pendingUpdates = [];
+  deviceSaved = true;
+  writeSequence = 0;
+  listeners.clear();
+}
+
+export function useWorkspaceAppLayout({
+  hydrate = true,
+}: { hydrate?: boolean } = {}) {
+  const { layout, persistenceError } = useSyncExternalStore(
+    subscribe,
+    currentSnapshot,
+    () => SERVER_SNAPSHOT,
+  );
+  useEffect(() => {
+    if (hydrate) hydrateWorkspaceAppLayout();
+  }, [hydrate]);
+  return { layout, persistenceError, togglePinned };
 }

package/src/lib/workspace-app-lists.ts

@@ -0,0 +1,32 @@
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+import { filterBuiltInApps, type ConnectedAppSummary } from "./other-apps";
+import { appListsStatus } from "./workspace-app-layout";
+import type { WorkspaceAppSummary } from "./workspace-apps";
+
+/**
+ * The app lists behind Home and All apps. Hosted apps stay empty until both
+ * lists settle: a workspace that mounts its own copy of a hosted app is only
+ * known from the workspace list.
+ */
+export function useWorkspaceAppLists({
+  includeHiddenFromLaunchers = false,
+}: { includeHiddenFromLaunchers?: boolean } = {}) {
+  const appsQuery = useActionQuery<WorkspaceAppSummary[]>(
+    "list-workspace-apps",
+    { includeAgentCards: false, includeArchived: true },
+  );
+  const connectedAppsQuery = useActionQuery<ConnectedAppSummary[]>(
+    "list-connected-agents",
+    {},
+  );
+  const status = appListsStatus(appsQuery, connectedAppsQuery);
+  const workspaceApps = appsQuery.data ?? [];
+  const hostedApps =
+    status === "ready"
+      ? filterBuiltInApps(connectedAppsQuery.data ?? [], workspaceApps, {
+          includeHiddenFromLaunchers,
+        })
+      : [];
+  return { status, workspaceApps, hostedApps, appsQuery, connectedAppsQuery };
+}

package/src/lib/workspace-apps.ts

@@ -47,6 +47,7 @@ export interface WorkspaceAppSummary {
   archived?: boolean;
   workspaceSso?: boolean;
   source?: WorkspaceAppSource;
+  hiddenFromLaunchers?: boolean;
 }
 
 export type WorkspaceAppSource = "workspace" | "builtin" | "connected";
@@ -168,9 +169,13 @@ export function isDefaultWorkspaceAppHiddenId(appId: string): boolean {
 }
 
 export function isWorkspaceAppVisibleInDefaultLaunchers(
-  app: Pick<WorkspaceAppSummary, "id" | "isDispatch">,
+  app: Pick<WorkspaceAppSummary, "id" | "isDispatch" | "hiddenFromLaunchers">,
 ): boolean {
-  return !app.isDispatch && !isDefaultWorkspaceAppHiddenId(app.id);
+  return (
+    !app.isDispatch &&
+    !app.hiddenFromLaunchers &&
+    !isDefaultWorkspaceAppHiddenId(app.id)
+  );
 }
 
 const DEFAULT_WORKSPACE_APP_DESCRIPTIONS: Record<
@@ -506,6 +511,7 @@ export function mergeChatFirstWorkspaceApps(
     description?: string | null;
     url?: string | null;
     source?: WorkspaceAppSource;
+    hiddenFromLaunchers?: boolean;
   }[] = [],
 ): WorkspaceAppSummary[] {
   const enabledBuiltins = new Set(
@@ -554,6 +560,7 @@ export function mergeChatFirstWorkspaceApps(
           name: app.name.trim() || existing.name,
           description: app.description ?? existing.description,
           url: app.url?.trim() || existing.url,
+          ...(app.hiddenFromLaunchers ? { hiddenFromLaunchers: true } : {}),
         });
       }
       continue;
@@ -566,6 +573,7 @@ export function mergeChatFirstWorkspaceApps(
       url: app.url?.trim() || null,
       status: "ready",
       source: app.source ?? "connected",
+      ...(app.hiddenFromLaunchers ? { hiddenFromLaunchers: true } : {}),
     });
   }