Open existing agents from links and the CLI (#2324)

* feat(desktop): open existing agents from links

Register a stable agent deep link and route it through the existing Desktop window. Add a matching CLI command that resolves the local server and activates the requested agent without creating or messaging it.

* fix(desktop): recover agent link delivery

packages/desktop/src/agent-navigation.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { AgentNavigationInbox, parseAgentDeepLinkFromArgv } from "./agent-navigation.js";
+
+describe("desktop agent navigation", () => {
+  it("finds an agent deep link among Electron launch arguments", () => {
+    expect(
+      parseAgentDeepLinkFromArgv([
+        "/Applications/Paseo.app/Contents/MacOS/Paseo",
+        "--no-sandbox",
+        "paseo://h/server-1/agent/agent-2",
+      ]),
+    ).toEqual({ serverId: "server-1", agentId: "agent-2" });
+  });
+
+  it("holds navigation until the existing renderer is ready", () => {
+    const inbox = new AgentNavigationInbox();
+    const target = { serverId: "server-1", agentId: "agent-2" };
+
+    expect(inbox.deliverOrQueue(7, target)).toBeNull();
+    expect(inbox.windowReady(7)).toEqual(target);
+    expect(inbox.deliverOrQueue(7, target)).toEqual(target);
+  });
+
+  it("returns only the newest navigation queued during startup", () => {
+    const inbox = new AgentNavigationInbox();
+
+    inbox.deliverOrQueue(7, { serverId: "server-1", agentId: "agent-1" });
+    inbox.deliverOrQueue(7, { serverId: "server-1", agentId: "agent-2" });
+
+    expect(inbox.windowReady(7)).toEqual({ serverId: "server-1", agentId: "agent-2" });
+    expect(inbox.windowReady(7)).toBeNull();
+  });
+});

packages/desktop/src/agent-navigation.ts

@@ -0,0 +1,40 @@
+import { parseAgentDeepLink, type AgentDeepLinkTarget } from "@getpaseo/protocol/agent-deep-link";
+
+export function parseAgentDeepLinkFromArgv(argv: string[]): AgentDeepLinkTarget | null {
+  for (const arg of argv) {
+    const target = parseAgentDeepLink(arg);
+    if (target) {
+      return target;
+    }
+  }
+  return null;
+}
+
+export class AgentNavigationInbox {
+  private readonly readyWindows = new Set<number>();
+  private readonly pendingByWindow = new Map<number, AgentDeepLinkTarget>();
+
+  windowLoading(webContentsId: number): void {
+    this.readyWindows.delete(webContentsId);
+  }
+
+  windowReady(webContentsId: number): AgentDeepLinkTarget | null {
+    this.readyWindows.add(webContentsId);
+    const pending = this.pendingByWindow.get(webContentsId) ?? null;
+    this.pendingByWindow.delete(webContentsId);
+    return pending;
+  }
+
+  deliverOrQueue(webContentsId: number, target: AgentDeepLinkTarget): AgentDeepLinkTarget | null {
+    if (this.readyWindows.has(webContentsId)) {
+      return target;
+    }
+    this.pendingByWindow.set(webContentsId, target);
+    return null;
+  }
+
+  removeWindow(webContentsId: number): void {
+    this.readyWindows.delete(webContentsId);
+    this.pendingByWindow.delete(webContentsId);
+  }
+}

packages/desktop/src/daemon/desktop-packaging.test.ts

@@ -89,6 +89,13 @@ describe("desktop packaging", () => {
     expect(config).toContain("!node_modules/@getpaseo/server/dist/server/web-ui/**");
   });
 
+  it("registers Paseo agent links with the operating system", () => {
+    const config = readFileSync(join(packageRoot, "electron-builder.yml"), "utf8");
+
+    expect(config).toContain("name: Paseo agent link");
+    expect(config).toContain("- paseo");
+  });
+
   // electron-builder packs production dependencies declared in package.json into
   // app.asar. Runtime code in runtime-paths.ts and bin/paseo dynamically resolves
   // these workspace packages by string, so static analysis (TypeScript, Knip) cannot

packages/desktop/src/desktop-startup.test.ts

@@ -5,7 +5,7 @@ describe("desktop startup", () => {
   it("runs CLI passthrough before GUI login-shell env inheritance", async () => {
     const calls: string[] = [];
     await runDesktopStartup({
-      hasPendingOpenProjectPath: false,
+      hasPendingGuiLaunchRequest: false,
       runCliPassthroughIfRequested: vi.fn(async () => {
         calls.push("cli");
         return true;
@@ -22,7 +22,7 @@ describe("desktop startup", () => {
   it("keeps login-shell env inheritance on normal GUI startup", async () => {
     const calls: string[] = [];
     await runDesktopStartup({
-      hasPendingOpenProjectPath: false,
+      hasPendingGuiLaunchRequest: false,
       runCliPassthroughIfRequested: vi.fn(async () => {
         calls.push("cli");
         return false;
@@ -39,7 +39,7 @@ describe("desktop startup", () => {
   it("starts skills auto-update after GUI startup", async () => {
     const calls: string[] = [];
     await runDesktopStartup({
-      hasPendingOpenProjectPath: false,
+      hasPendingGuiLaunchRequest: false,
       runCliPassthroughIfRequested: vi.fn(async () => {
         calls.push("cli");
         return false;
@@ -59,7 +59,7 @@ describe("desktop startup", () => {
     const calls: string[] = [];
 
     await runDesktopStartup({
-      hasPendingOpenProjectPath: true,
+      hasPendingGuiLaunchRequest: true,
       runCliPassthroughIfRequested,
       inheritLoginShellEnv: vi.fn(() => calls.push("env")),
       bootstrapGui: vi.fn(async () => {

packages/desktop/src/desktop-startup.ts

@@ -1,5 +1,5 @@
 export interface DesktopStartupDependencies {
-  hasPendingOpenProjectPath: boolean;
+  hasPendingGuiLaunchRequest: boolean;
   runCliPassthroughIfRequested: () => Promise<boolean>;
   inheritLoginShellEnv: () => void;
   bootstrapGui: () => Promise<void>;
@@ -7,7 +7,7 @@ export interface DesktopStartupDependencies {
 }
 
 export async function runDesktopStartup(deps: DesktopStartupDependencies): Promise<void> {
-  if (!deps.hasPendingOpenProjectPath && (await deps.runCliPassthroughIfRequested())) {
+  if (!deps.hasPendingGuiLaunchRequest && (await deps.runCliPassthroughIfRequested())) {
     return;
   }
 

packages/desktop/src/main.ts

@@ -90,6 +90,12 @@ import { autoUpdateInstalledSkills } from "./integrations/skills/index.js";
 import { registerBrowserAutomationIpc } from "./features/browser-automation/ipc.js";
 import { BrowserKeyboard } from "./features/browser-keyboard/index.js";
 import { installAppUpdateOnQuit } from "./features/auto-updater.js";
+import {
+  buildAgentDeepLinkRoute,
+  parseAgentDeepLink,
+  type AgentDeepLinkTarget,
+} from "@getpaseo/protocol/agent-deep-link";
+import { AgentNavigationInbox, parseAgentDeepLinkFromArgv } from "./agent-navigation.js";
 
 const DEV_SERVER_URL = process.env.EXPO_DEV_URL ?? "http://localhost:8081";
 const APP_SCHEME = "paseo";
@@ -98,6 +104,16 @@ const DISABLE_SINGLE_INSTANCE_LOCK = process.env.PASEO_DISABLE_SINGLE_INSTANCE_L
 const APP_NAME = process.env.PASEO_TEST_APP_NAME?.trim() || "Paseo";
 const UPDATE_QUIT_DEADLINE_MS = 5_000;
 const pendingBrowserWindowOpenRequests = new PendingBrowserWindowOpenRequests();
+const agentNavigationInbox = new AgentNavigationInbox();
+
+// A second-instance launch can arrive before the packaged protocol handler,
+// IPC handlers, and first window exist. Wait for full bootstrap, not just
+// app.whenReady(), before delivering navigation to the renderer.
+let resolveBootstrapComplete: () => void;
+const bootstrapComplete = new Promise<void>((resolve) => {
+  resolveBootstrapComplete = resolve;
+});
+let bootstrapIsComplete = false;
 
 app.setName(APP_NAME);
 
@@ -316,6 +332,7 @@ let pendingOpenProjectPath = parseOpenProjectPathFromArgv({
   argv: process.argv,
   isDefaultApp: process.defaultApp,
 });
+let pendingAgentNavigation = parseAgentDeepLinkFromArgv(process.argv);
 
 // Each window pulls its own pending open-project path on mount, keyed by
 // webContents id, so deep-linked windows (second-instance launches, the
@@ -341,6 +358,10 @@ ipcMain.handle("paseo:get-pending-open-project", (event) => {
   return result;
 });
 
+ipcMain.handle("paseo:agent-navigation:ready", (event) => {
+  return agentNavigationInbox.windowReady(event.sender.id);
+});
+
 function normalizeBrowserCaptureRect(
   rect: unknown,
 ): { x: number; y: number; width: number; height: number } | null {
@@ -653,6 +674,7 @@ function getWorkAreasPrimaryFirst(): Electron.Rectangle[] {
 
 async function createWindow(
   options: {
+    initialRoute?: string | null;
     pendingOpenProjectPath?: string | null;
     restoreWindowState?: boolean;
   } = {},
@@ -694,8 +716,14 @@ async function createWindow(
 
   const webContentsId = mainWindow.webContents.id;
   pendingOpenProjectStore.set(webContentsId, options.pendingOpenProjectPath);
+  mainWindow.webContents.on("did-start-navigation", (_event, _url, isSameDocument, isMainFrame) => {
+    if (isMainFrame && !isSameDocument) {
+      agentNavigationInbox.windowLoading(webContentsId);
+    }
+  });
   mainWindow.on("closed", () => {
     pendingOpenProjectStore.delete(webContentsId);
+    agentNavigationInbox.removeWindow(webContentsId);
     unregisterPaseoBrowserHost(webContentsId);
     browserKeyboard.detachHost(webContentsId);
   });
@@ -759,11 +787,14 @@ async function createWindow(
   if (!app.isPackaged) {
     const { loadReactDevTools } = await import("./features/react-devtools.js");
     await loadReactDevTools();
-    await mainWindow.loadURL(DEV_SERVER_URL);
+    const initialUrl = options.initialRoute
+      ? new URL(options.initialRoute, `${DEV_SERVER_URL}/`).toString()
+      : DEV_SERVER_URL;
+    await mainWindow.loadURL(initialUrl);
     return mainWindow;
   }
 
-  await mainWindow.loadURL(`${APP_SCHEME}://app/`);
+  await mainWindow.loadURL(`${APP_SCHEME}://app${options.initialRoute ?? "/"}`);
   return mainWindow;
 }
 
@@ -771,14 +802,72 @@ async function createWindow(
 // App lifecycle
 // ---------------------------------------------------------------------------
 
-// Resolves once bootstrap() has registered the custom protocol handler and IPC
-// handlers and created the first window. second-instance window creation waits
-// on this rather than app.whenReady(): in packaged mode createWindow loads
-// `paseo://app/`, which fails if the protocol handler isn't registered yet, and
-// a second instance can arrive mid-cold-start.
-let resolveBootstrapComplete: () => void;
-const bootstrapComplete = new Promise<void>((resolve) => {
-  resolveBootstrapComplete = resolve;
+let agentNavigationWindowCreation: Promise<BrowserWindow> | null = null;
+
+function focusExistingWindowOnAgent(target: AgentDeepLinkTarget): void {
+  const windows = BrowserWindow.getAllWindows();
+  const mainWindow =
+    BrowserWindow.getFocusedWindow() ?? windows.find((window) => window.isVisible()) ?? windows[0];
+  if (!mainWindow || mainWindow.isDestroyed()) {
+    if (!agentNavigationWindowCreation) {
+      const creation = createWindow({
+        initialRoute: buildAgentDeepLinkRoute(target),
+        restoreWindowState: true,
+      });
+      agentNavigationWindowCreation = creation;
+      void creation
+        .catch((error) => log.error("[window] failed to create window for agent link", error))
+        .finally(() => {
+          if (agentNavigationWindowCreation === creation) {
+            agentNavigationWindowCreation = null;
+          }
+        });
+      return;
+    }
+
+    void agentNavigationWindowCreation
+      .then(() => focusExistingWindowOnAgent(target))
+      .catch((error) => log.error("[window] failed to deliver queued agent link", error));
+    return;
+  }
+
+  if (mainWindow.isMinimized()) {
+    mainWindow.restore();
+  }
+  mainWindow.show();
+  mainWindow.focus();
+
+  const deliverable = agentNavigationInbox.deliverOrQueue(mainWindow.webContents.id, target);
+  if (deliverable) {
+    mainWindow.webContents.send("paseo:event:open-agent", deliverable);
+  }
+}
+
+function receiveAgentDeepLink(input: string): void {
+  const target = parseAgentDeepLink(input);
+  if (!target) {
+    return;
+  }
+
+  if (bootstrapIsComplete) {
+    focusExistingWindowOnAgent(target);
+    return;
+  }
+
+  pendingAgentNavigation = target;
+  void bootstrapComplete.then(() => {
+    if (pendingAgentNavigation !== target) {
+      return undefined;
+    }
+    pendingAgentNavigation = null;
+    focusExistingWindowOnAgent(target);
+    return undefined;
+  });
+}
+
+app.on("open-url", (event, url) => {
+  event.preventDefault();
+  receiveAgentDeepLink(url);
 });
 
 function setupSingleInstanceLock(): boolean {
@@ -794,6 +883,12 @@ function setupSingleInstanceLock(): boolean {
   }
 
   app.on("second-instance", (_event, commandLine) => {
+    const agentTarget = parseAgentDeepLinkFromArgv(commandLine);
+    if (agentTarget) {
+      void bootstrapComplete.then(() => focusExistingWindowOnAgent(agentTarget));
+      return;
+    }
+
     log.info("[open-project] second-instance commandLine:", commandLine);
     const openProjectPath = parseOpenProjectPathFromArgv({
       argv: commandLine,
@@ -895,13 +990,26 @@ async function bootstrap(): Promise<void> {
   });
 
   // The first window of the session restores and persists saved geometry.
-  await createWindow({ pendingOpenProjectPath, restoreWindowState: true });
+  const initialAgentNavigation = pendingAgentNavigation;
+  pendingAgentNavigation = null;
+  await createWindow({
+    initialRoute: initialAgentNavigation ? buildAgentDeepLinkRoute(initialAgentNavigation) : null,
+    pendingOpenProjectPath,
+    restoreWindowState: true,
+  });
   pendingOpenProjectPath = null;
 
   // Protocol + IPC handlers and the first window now exist: release any
   // second-instance launches that arrived during cold start.
+  bootstrapIsComplete = true;
   resolveBootstrapComplete();
 
+  if (pendingAgentNavigation) {
+    const target = pendingAgentNavigation;
+    pendingAgentNavigation = null;
+    focusExistingWindowOnAgent(target);
+  }
+
   app.on("activate", async () => {
     if (BrowserWindow.getAllWindows().length === 0) {
       await createWindow({ restoreWindowState: true });
@@ -910,7 +1018,7 @@ async function bootstrap(): Promise<void> {
 }
 
 void runDesktopStartup({
-  hasPendingOpenProjectPath: Boolean(pendingOpenProjectPath),
+  hasPendingGuiLaunchRequest: Boolean(pendingOpenProjectPath || pendingAgentNavigation),
   runCliPassthroughIfRequested,
   inheritLoginShellEnv,
   bootstrapGui: bootstrap,

packages/desktop/src/preload.ts

@@ -23,6 +23,13 @@ contextBridge.exposeInMainWorld("paseoDesktop", {
     ipcRenderer.invoke("paseo:invoke", command, args),
   getPendingOpenProject: () =>
     ipcRenderer.invoke("paseo:get-pending-open-project") as Promise<string | null>,
+  agentNavigation: {
+    ready: () =>
+      ipcRenderer.invoke("paseo:agent-navigation:ready") as Promise<{
+        serverId: string;
+        agentId: string;
+      } | null>,
+  },
   events: {
     on: (event: string, handler: EventHandler): Promise<() => void> => {
       const listener = (_ipcEvent: Electron.IpcRendererEvent, payload: unknown) => {