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/protocol/src/agent-deep-link.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildAgentDeepLink,
+  buildAgentDeepLinkRoute,
+  parseAgentDeepLink,
+} from "./agent-deep-link.js";
+
+describe("agent deep links", () => {
+  it("round-trips an existing agent target", () => {
+    const target = { serverId: "server/main", agentId: "agent 123" };
+
+    const link = buildAgentDeepLink(target);
+
+    expect(link).toBe("paseo://h/server%2Fmain/agent/agent%20123");
+    expect(buildAgentDeepLinkRoute(target)).toBe("/h/server%2Fmain/agent/agent%20123");
+    expect(parseAgentDeepLink(link)).toEqual(target);
+  });
+
+  it("rejects links outside the exact agent route", () => {
+    expect(parseAgentDeepLink("https://h/server/agent/agent-1")).toBeNull();
+    expect(parseAgentDeepLink("paseo://app/h/server/agent/agent-1")).toBeNull();
+    expect(parseAgentDeepLink("paseo://h/server/agent/agent-1?message=hello")).toBeNull();
+    expect(parseAgentDeepLink("paseo://h/server/agent/agent-1/extra")).toBeNull();
+  });
+});

packages/protocol/src/agent-deep-link.ts

@@ -0,0 +1,56 @@
+export interface AgentDeepLinkTarget {
+  serverId: string;
+  agentId: string;
+}
+
+function normalizeSegment(value: string): string {
+  return value.trim();
+}
+
+export function buildAgentDeepLink(target: AgentDeepLinkTarget): string {
+  const serverId = normalizeSegment(target.serverId);
+  const agentId = normalizeSegment(target.agentId);
+  if (!serverId || !agentId) {
+    throw new Error("Agent deep links require a server ID and agent ID.");
+  }
+  return `paseo://h/${encodeURIComponent(serverId)}/agent/${encodeURIComponent(agentId)}`;
+}
+
+export function buildAgentDeepLinkRoute(target: AgentDeepLinkTarget): string {
+  const link = new URL(buildAgentDeepLink(target));
+  return `/h${link.pathname}`;
+}
+
+export function parseAgentDeepLink(input: string): AgentDeepLinkTarget | null {
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    return null;
+  }
+
+  if (
+    url.protocol !== "paseo:" ||
+    url.hostname !== "h" ||
+    url.username ||
+    url.password ||
+    url.port ||
+    url.search ||
+    url.hash
+  ) {
+    return null;
+  }
+
+  const segments = url.pathname.split("/").filter(Boolean);
+  if (segments.length !== 3 || segments[1] !== "agent") {
+    return null;
+  }
+
+  try {
+    const serverId = normalizeSegment(decodeURIComponent(segments[0] ?? ""));
+    const agentId = normalizeSegment(decodeURIComponent(segments[2] ?? ""));
+    return serverId && agentId ? { serverId, agentId } : null;
+  } catch {
+    return null;
+  }
+}