@agent-native/dispatch 0.8.6 → 0.8.8

package/src/server/lib/mcp-gateway.spec.ts

@@ -0,0 +1,295 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  discoverAgents: vi.fn(),
+  getUserSetting: vi.fn(),
+  getOrgSetting: vi.fn(),
+  createEmbedSessionTicket: vi.fn(),
+  buildEmbedStartPath: vi.fn((ticket: string) => {
+    return `/_agent-native/embed/start?ticket=${encodeURIComponent(ticket)}`;
+  }),
+  managerStart: vi.fn(),
+  managerStop: vi.fn(),
+  managerCallTool: vi.fn(),
+  managerConstructor: vi.fn(),
+  signA2AToken: vi.fn(),
+  getOrgA2ASecret: vi.fn(),
+  getOrgDomain: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/server/agent-discovery", () => ({
+  discoverAgents: mocks.discoverAgents,
+}));
+
+vi.mock("@agent-native/core/settings", () => ({
+  getUserSetting: mocks.getUserSetting,
+  getOrgSetting: mocks.getOrgSetting,
+  putUserSetting: vi.fn(),
+  putOrgSetting: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/server", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("@agent-native/core/server")>();
+  return {
+    ...actual,
+    createEmbedSessionTicket: mocks.createEmbedSessionTicket,
+    buildEmbedStartPath: mocks.buildEmbedStartPath,
+  };
+});
+
+vi.mock("@agent-native/core/a2a", () => ({
+  callAgent: vi.fn(),
+  signA2AToken: mocks.signA2AToken,
+}));
+
+vi.mock("@agent-native/core/org", () => ({
+  getOrgA2ASecret: mocks.getOrgA2ASecret,
+  getOrgDomain: mocks.getOrgDomain,
+}));
+
+vi.mock("@agent-native/core/mcp-client", () => ({
+  buildMcpToolName: (serverId: string, toolName: string) =>
+    `mcp__${serverId}__${toolName}`,
+  McpClientManager: class MockMcpClientManager {
+    constructor(config: unknown) {
+      mocks.managerConstructor(config);
+    }
+
+    start() {
+      return mocks.managerStart();
+    }
+
+    stop() {
+      return mocks.managerStop();
+    }
+
+    callTool(name: string, args: unknown) {
+      return mocks.managerCallTool(name, args);
+    }
+  },
+}));
+
+import {
+  createGrantedDispatchMcpEmbedSession,
+  listGrantedDispatchMcpApps,
+  openGrantedDispatchMcpApp,
+} from "./mcp-gateway.js";
+import { runWithRequestContext } from "@agent-native/core/server";
+
+const analyticsAgent = {
+  id: "analytics",
+  name: "Analytics",
+  description: "Dashboards and metrics",
+  url: "http://localhost:8086",
+  color: "#6366F1",
+};
+
+beforeEach(() => {
+  mocks.discoverAgents.mockResolvedValue([analyticsAgent]);
+  mocks.getUserSetting.mockResolvedValue(null);
+  mocks.getOrgSetting.mockResolvedValue(null);
+  mocks.createEmbedSessionTicket.mockResolvedValue({
+    ticket: "ticket-123",
+    ticketHash: "hash-123",
+    expiresAt: 12345,
+  });
+  mocks.managerStart.mockResolvedValue(undefined);
+  mocks.managerStop.mockResolvedValue(undefined);
+  mocks.managerCallTool.mockResolvedValue({
+    structuredContent: {
+      startUrl: "http://localhost:8086/_agent-native/embed/start?ticket=remote",
+    },
+  });
+  mocks.signA2AToken.mockResolvedValue("signed-token");
+  mocks.getOrgA2ASecret.mockResolvedValue(null);
+  mocks.getOrgDomain.mockResolvedValue(null);
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.clearAllMocks();
+});
+
+describe("Dispatch MCP gateway app discovery", () => {
+  it("includes Dispatch itself so agents can target extension routes", async () => {
+    const apps = await runWithRequestContext(
+      {
+        userEmail: "owner@example.test",
+        requestOrigin: "http://localhost:8092",
+      },
+      () => listGrantedDispatchMcpApps(),
+    );
+
+    expect(apps.map((app) => app.id)).toEqual(["dispatch", "analytics"]);
+    expect(apps[0]).toMatchObject({
+      id: "dispatch",
+      name: "Agent-Native Dispatch",
+      url: "http://localhost:8092",
+      granted: true,
+    });
+  });
+
+  it("honors selected app grants for the Dispatch self target", async () => {
+    mocks.getUserSetting.mockResolvedValue({
+      mode: "selected-apps",
+      selectedAppIds: ["dispatch"],
+    });
+
+    const apps = await runWithRequestContext(
+      {
+        userEmail: "owner@example.test",
+        requestOrigin: "http://localhost:8092",
+      },
+      () => listGrantedDispatchMcpApps(),
+    );
+
+    expect(apps.map((app) => app.id)).toEqual(["dispatch"]);
+  });
+});
+
+describe("openGrantedDispatchMcpApp", () => {
+  it("opens Dispatch extension routes through the Dispatch app id", async () => {
+    const result = await runWithRequestContext(
+      {
+        userEmail: "owner@example.test",
+        requestOrigin: "http://localhost:8092",
+      },
+      () =>
+        openGrantedDispatchMcpApp({
+          app: "dispatch",
+          path: "/extensions/ext-1/github-stars-over-time",
+          embed: true,
+          chrome: "minimal",
+        }),
+    );
+
+    expect(result).toEqual({
+      app: "dispatch",
+      path: "/extensions/ext-1/github-stars-over-time",
+      url: "http://localhost:8092/extensions/ext-1/github-stars-over-time",
+      embed: true,
+      chrome: "minimal",
+    });
+  });
+
+  it("rejects Dispatch-owned extension routes on sibling apps", async () => {
+    await expect(
+      runWithRequestContext(
+        {
+          userEmail: "owner@example.test",
+          requestOrigin: "http://localhost:8092",
+        },
+        () =>
+          openGrantedDispatchMcpApp({
+            app: "analytics",
+            path: "/extensions/ext-1/github-stars-over-time",
+          }),
+      ),
+    ).rejects.toThrow(/belongs to Dispatch/);
+  });
+
+  it("rejects traversal that normalizes into Dispatch-owned routes on sibling apps", async () => {
+    await expect(
+      runWithRequestContext(
+        {
+          userEmail: "owner@example.test",
+          requestOrigin: "http://localhost:8092",
+        },
+        () =>
+          openGrantedDispatchMcpApp({
+            app: "analytics",
+            path: "/../dispatch/extensions/ext-1",
+          }),
+      ),
+    ).rejects.toThrow(/safe app-relative route/);
+  });
+});
+
+describe("createGrantedDispatchMcpEmbedSession", () => {
+  it("mints Dispatch self embeds locally instead of recursively calling Dispatch MCP", async () => {
+    const result = await runWithRequestContext(
+      {
+        userEmail: "owner@example.test",
+        requestOrigin: "http://localhost:8092",
+      },
+      () =>
+        createGrantedDispatchMcpEmbedSession({
+          app: "dispatch",
+          path: "/extensions/ext-1/github-stars-over-time",
+          chrome: "minimal",
+        }),
+    );
+
+    expect(mocks.createEmbedSessionTicket).toHaveBeenCalledWith({
+      ownerEmail: "owner@example.test",
+      orgId: undefined,
+      targetPath: "/extensions/ext-1/github-stars-over-time",
+      scope: "minimal",
+    });
+    expect(mocks.managerConstructor).not.toHaveBeenCalled();
+    expect(result).toEqual({
+      app: "dispatch",
+      startUrl:
+        "http://localhost:8092/_agent-native/embed/start?ticket=ticket-123",
+      targetPath: "/extensions/ext-1/github-stars-over-time",
+      expiresAt: 12345,
+    });
+  });
+
+  it("rejects traversal into Dispatch-owned embed routes on sibling apps", async () => {
+    await expect(
+      runWithRequestContext(
+        {
+          userEmail: "owner@example.test",
+          requestOrigin: "http://localhost:8092",
+        },
+        () =>
+          createGrantedDispatchMcpEmbedSession({
+            app: "analytics",
+            path: "/../dispatch/extensions/ext-1",
+          }),
+      ),
+    ).rejects.toThrow(/safe app-relative route/);
+  });
+
+  it("routes same-origin mounted app embed URLs to the mounted app", async () => {
+    mocks.discoverAgents.mockResolvedValue([
+      {
+        ...analyticsAgent,
+        url: "http://localhost:8092/analytics",
+      },
+    ]);
+
+    const result = await runWithRequestContext(
+      {
+        userEmail: "owner@example.test",
+        requestOrigin: "http://localhost:8092",
+      },
+      () =>
+        createGrantedDispatchMcpEmbedSession({
+          url: "http://localhost:8092/analytics/dashboards?range=30d",
+        }),
+    );
+
+    expect(mocks.createEmbedSessionTicket).not.toHaveBeenCalled();
+    expect(mocks.managerConstructor).toHaveBeenCalledWith({
+      servers: {
+        target: expect.objectContaining({
+          url: "http://localhost:8092/analytics/_agent-native/mcp",
+        }),
+      },
+    });
+    expect(mocks.managerCallTool).toHaveBeenCalledWith(
+      "mcp__target__create_embed_session",
+      {
+        url: "http://localhost:8092/analytics/dashboards?range=30d",
+        chrome: "full",
+      },
+    );
+    expect(result).toEqual({
+      app: "analytics",
+      startUrl: "http://localhost:8086/_agent-native/embed/start?ticket=remote",
+    });
+  });
+});

package/src/server/lib/mcp-gateway.ts

@@ -3,7 +3,12 @@ import {
   buildMcpToolName,
   McpClientManager,
 } from "@agent-native/core/mcp-client";
-import { buildDeepLink } from "@agent-native/core/server";
+import {
+  buildDeepLink,
+  buildEmbedStartPath,
+  createEmbedSessionTicket,
+  getRequestContext,
+} from "@agent-native/core/server";
 import {
   discoverAgents,
   type DiscoveredAgent,
@@ -19,6 +24,12 @@ import {
   type DispatchMcpAppAccessSettings,
 } from "./mcp-access-store.js";
 
+const DISPATCH_APP_ID = "dispatch";
+const DISPATCH_NAME = "Agent-Native Dispatch";
+const DISPATCH_DESCRIPTION =
+  "Workspace control plane for extensions, agents, vault, integrations, approvals, and app routing.";
+const DISPATCH_COLOR = "#14B8A6";
+
 export interface DispatchMcpAccessibleApp {
   id: string;
   name: string;
@@ -32,6 +43,73 @@ function normalizeAppId(value: string): string {
   return value.trim().toLowerCase();
 }
 
+function normalizeBaseUrl(raw: string | undefined | null): string | null {
+  const value = raw?.trim();
+  if (!value) return null;
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    return url.toString().replace(/\/+$/, "");
+  } catch {
+    return null;
+  }
+}
+
+function normalizeBasePath(value: string | undefined): string {
+  const trimmed = value?.trim();
+  if (!trimmed || trimmed === "/") return "";
+  const normalized = trimmed.replace(/^\/+/, "").replace(/\/+$/, "");
+  return normalized ? `/${normalized}` : "";
+}
+
+function withConfiguredBasePath(baseUrl: string): string {
+  const basePath = normalizeBasePath(
+    process.env.VITE_APP_BASE_PATH || process.env.APP_BASE_PATH,
+  );
+  if (!basePath) return baseUrl;
+  try {
+    const url = new URL(baseUrl);
+    const path = normalizeBasePath(url.pathname);
+    if (path === basePath || path.startsWith(`${basePath}/`)) {
+      return baseUrl;
+    }
+    url.pathname = path && path !== "/" ? `${basePath}${path}` : `${basePath}/`;
+    return url.toString().replace(/\/+$/, "");
+  } catch {
+    return baseUrl;
+  }
+}
+
+function dispatchSelfBaseUrl(): string {
+  const requestOrigin = normalizeBaseUrl(getRequestContext()?.requestOrigin);
+  if (requestOrigin) return withConfiguredBasePath(requestOrigin);
+
+  const configured =
+    normalizeBaseUrl(process.env.WORKSPACE_GATEWAY_URL) ??
+    normalizeBaseUrl(process.env.APP_URL) ??
+    normalizeBaseUrl(process.env.URL) ??
+    normalizeBaseUrl(process.env.DEPLOY_URL) ??
+    normalizeBaseUrl(process.env.BETTER_AUTH_URL);
+  if (configured) return withConfiguredBasePath(configured);
+
+  return process.env.NODE_ENV === "production"
+    ? "https://dispatch.agent-native.com"
+    : "http://localhost:8092";
+}
+
+function dispatchSelfApp(
+  settings: DispatchMcpAppAccessSettings,
+): DispatchMcpAccessibleApp {
+  return {
+    id: DISPATCH_APP_ID,
+    name: DISPATCH_NAME,
+    description: DISPATCH_DESCRIPTION,
+    url: dispatchSelfBaseUrl(),
+    color: DISPATCH_COLOR,
+    granted: isAppAllowedByMcpAccess(DISPATCH_APP_ID, settings),
+  };
+}
+
 const CONTROL_CHARS = new RegExp("[\\u0000-\\u001f\\u007f]");
 
 function safeAppPath(raw: unknown): string | null {
@@ -41,6 +119,15 @@ function safeAppPath(raw: unknown): string | null {
   if (!value.startsWith("/")) return null;
   if (value.startsWith("//") || value.startsWith("/\\")) return null;
   if (/^\/[a-z][a-z0-9+.-]*:/i.test(value)) return null;
+  if (/%(?:2f|5c)/i.test(value)) return null;
+  const rawPath = value.split(/[?#]/, 1)[0] ?? value;
+  let parsed: URL;
+  try {
+    parsed = new URL(value, "http://agent-native.invalid");
+  } catch {
+    return null;
+  }
+  if (parsed.pathname !== rawPath) return null;
   return value;
 }
 
@@ -64,6 +151,51 @@ function appBaseUrl(app: DispatchMcpAccessibleApp): string {
   return app.url.replace(/\/+$/, "");
 }
 
+function appBasePath(app: DispatchMcpAccessibleApp): string {
+  const pathname = new URL(appBaseUrl(app)).pathname.replace(/\/+$/, "");
+  return pathname === "/" ? "" : pathname;
+}
+
+function appMatchesUrlPath(app: DispatchMcpAccessibleApp, url: URL): boolean {
+  if (url.origin !== appOrigin(app)) return false;
+  const basePath = appBasePath(app);
+  if (!basePath) return true;
+  return url.pathname === basePath || url.pathname.startsWith(`${basePath}/`);
+}
+
+function appPathSpecificity(app: DispatchMcpAccessibleApp): number {
+  return appBasePath(app).length;
+}
+
+function appRelativePath(app: DispatchMcpAccessibleApp, url: URL): string {
+  const basePath = appBasePath(app);
+  const path = basePath
+    ? url.pathname === basePath
+      ? "/"
+      : url.pathname.slice(basePath.length)
+    : url.pathname;
+  return `${path || "/"}${url.search}${url.hash}`;
+}
+
+function isDispatchControlPath(path: string | null): boolean {
+  if (!path) return false;
+  const route = path.split(/[?#]/, 1)[0] ?? path;
+  return (
+    route === "/extensions" ||
+    route.startsWith("/extensions/") ||
+    route === "/tools" ||
+    route.startsWith("/tools/")
+  );
+}
+
+function assertAppCanOpenPath(app: DispatchMcpAccessibleApp, path: string) {
+  if (app.id !== DISPATCH_APP_ID && isDispatchControlPath(path)) {
+    throw new Error(
+      `Path "${path}" belongs to Dispatch. Use app: "dispatch" for Dispatch extension and tool routes.`,
+    );
+  }
+}
+
 function toAccessibleApp(
   agent: DiscoveredAgent,
   settings: DispatchMcpAppAccessSettings,
@@ -88,7 +220,12 @@ export async function listDispatchMcpApps(): Promise<{
   ]);
   return {
     settings,
-    apps: agents.map((agent) => toAccessibleApp(agent, settings)),
+    apps: [
+      dispatchSelfApp(settings),
+      ...agents
+        .filter((agent) => normalizeAppId(agent.id) !== DISPATCH_APP_ID)
+        .map((agent) => toAccessibleApp(agent, settings)),
+    ],
   };
 }
 
@@ -165,9 +302,14 @@ export async function openGrantedDispatchMcpApp(input: {
   chrome?: "full" | "minimal";
 }> {
   const view = input.view?.trim() ?? "";
+  const hasPathInput = input.path != null;
   const path = safeAppPath(input.path);
+  if (hasPathInput && !path) {
+    throw new Error("path must be a safe app-relative route");
+  }
   if (!view && !path) throw new Error("open_app requires view or path");
   const target = await resolveGrantedDispatchMcpApp(input.app);
+  if (path) assertAppCanOpenPath(target, path);
   const relUrl = path
     ? appendParamsToPath(path, input.params)
     : buildDeepLink({
@@ -214,6 +356,7 @@ async function resolveDispatchEmbedTarget(input: {
   if (explicitApp && input.path) {
     const path = safeAppPath(input.path);
     if (!path) throw new Error("path must be a safe app-relative route");
+    assertAppCanOpenPath(explicitApp, path);
     return {
       app: explicitApp,
       path,
@@ -242,17 +385,47 @@ async function resolveDispatchEmbedTarget(input: {
   }
 
   const apps = explicitApp ? [explicitApp] : await listGrantedDispatchMcpApps();
-  const target = apps.find((app) => parsed.origin === appOrigin(app));
+  const target = apps
+    .filter((app) => appMatchesUrlPath(app, parsed))
+    .sort((a, b) => appPathSpecificity(b) - appPathSpecificity(a))[0];
   if (!target) {
     throw new Error(
       "Embed URL must belong to an app granted through Dispatch.",
     );
   }
-  const path = safeAppPath(`${parsed.pathname}${parsed.search}${parsed.hash}`);
+  const path = safeAppPath(appRelativePath(target, parsed));
   if (!path) throw new Error("Embed URL path is not safe.");
+  assertAppCanOpenPath(target, path);
   return { app: target, path, url: `${appBaseUrl(target)}${path}` };
 }
 
+async function createDispatchSelfEmbedSession(input: {
+  ownerEmail: string;
+  orgId?: string;
+  path: string;
+  baseUrl: string;
+  chrome?: "full" | "minimal";
+}): Promise<{
+  startUrl: string;
+  targetPath?: string;
+  expiresAt?: number;
+  app: string;
+}> {
+  const ticket = await createEmbedSessionTicket({
+    ownerEmail: input.ownerEmail,
+    orgId: input.orgId,
+    targetPath: input.path,
+    scope: input.chrome ?? null,
+  });
+  const startPath = buildEmbedStartPath(ticket.ticket);
+  return {
+    startUrl: new URL(startPath, input.baseUrl).toString(),
+    targetPath: input.path,
+    expiresAt: ticket.expiresAt,
+    app: DISPATCH_APP_ID,
+  };
+}
+
 export async function createGrantedDispatchMcpEmbedSession(input: {
   app?: string;
   url?: string;
@@ -269,6 +442,16 @@ export async function createGrantedDispatchMcpEmbedSession(input: {
   const target = await resolveDispatchEmbedTarget(input);
 
   const orgId = getRequestOrgId();
+  if (target.app.id === DISPATCH_APP_ID) {
+    return createDispatchSelfEmbedSession({
+      ownerEmail: userEmail,
+      orgId,
+      path: target.path,
+      baseUrl: appBaseUrl(target.app),
+      chrome: input.chrome,
+    });
+  }
+
   const [orgDomain, orgSecret] = orgId
     ? await Promise.all([
         getOrgDomain(orgId).catch(() => null),

package/src/server/lib/usage-metrics-store.ts

@@ -51,6 +51,7 @@ export interface AppAccessMetric {
   name: string;
   path: string;
   status: WorkspaceAppSummary["status"];
+  statusLabel?: string;
   isDispatch: boolean;
   accessModel: "workspace" | "solo";
   accessLabel: string;
@@ -587,6 +588,7 @@ export async function listDispatchUsageMetrics(input: {
       name: app.name,
       path: app.path,
       status: app.status,
+      statusLabel: app.statusLabel,
       isDispatch: app.isDispatch,
       accessModel,
       accessLabel,