@agent-native/dispatch 0.40.30-nightly-20261021093329 → 0.40.31

package/src/lib/connect-apps.ts

@@ -14,28 +14,58 @@ export interface MarketplaceApp {
   source?: "first-party" | "community";
 }
 
+function isPrivateIpv4(hostname: string): boolean {
+  const octets = hostname.split(".").map(Number);
+  if (
+    octets.length !== 4 ||
+    octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)
+  ) {
+    return false;
+  }
+  const [first, second] = octets;
+  return (
+    first === 0 ||
+    first === 10 ||
+    first === 127 ||
+    (first === 100 && second >= 64 && second <= 127) ||
+    (first === 169 && second === 254) ||
+    (first === 172 && second >= 16 && second <= 31) ||
+    (first === 192 && second === 168)
+  );
+}
+
+function mappedIpv4(hostname: string): string | null {
+  const match = /^::ffff:(.*)$/i.exec(hostname);
+  if (!match) return null;
+  if (match[1].includes(".")) return match[1];
+  const words = match[1].split(":");
+  if (
+    words.length !== 2 ||
+    words.some((word) => !/^[\da-f]{1,4}$/i.test(word))
+  ) {
+    return null;
+  }
+  const high = Number.parseInt(words[0], 16);
+  const low = Number.parseInt(words[1], 16);
+  return `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`;
+}
+
 export function normalizeConnectUrl(value: string): URL | null {
   try {
     const url = new URL(value.trim());
     const hostname = url.hostname.toLowerCase();
     const ipv6 = hostname.replace(/^\[|\]$/g, "");
-    const privateIpv4 =
-      /^(10\.|127\.|169\.254\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(
-        hostname,
-      ) ||
-      hostname === "0.0.0.0" ||
-      /^100\.(?:6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(hostname);
+    const privateIpv4 = isPrivateIpv4(hostname);
+    const mappedAddress = mappedIpv4(ipv6);
     const privateIpv6 =
-      ipv6 === "::" ||
-      ipv6 === "::1" ||
-      /^(?:fc|fd)/.test(ipv6) ||
-      /^fe[89ab]/.test(ipv6) ||
-      /^::ffff:(?:10\.|127\.|169\.254\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(
-        ipv6,
-      );
+      ipv6.includes(":") &&
+      (ipv6 === "::" ||
+        ipv6 === "::1" ||
+        /^(?:fc|fd)/.test(ipv6) ||
+        /^fe[89ab]/.test(ipv6) ||
+        Boolean(mappedAddress && isPrivateIpv4(mappedAddress)));
     if (
-      (url.protocol !== "https:" &&
-        !(url.protocol === "http:" && hostname === "localhost")) ||
+      url.protocol !== "https:" ||
       (hostname !== "localhost" && (privateIpv4 || privateIpv6)) ||
       url.username ||
       url.password
@@ -103,73 +133,8 @@ export function buildIdentityConnectUrl(appUrl: string): string {
   return url.toString();
 }
 
-export async function fetchMarketplaceApps(
-  feedUrl = "https://www.agent-native.com/apps.json",
-): Promise<MarketplaceApp[]> {
-  const response = await fetch(feedUrl, {
-    headers: { accept: "application/json" },
-    signal: AbortSignal.timeout(5_000),
-  });
-  if (!response.ok)
-    throw new Error(`Marketplace feed returned ${response.status}`);
-  const length = Number(response.headers.get("content-length") ?? 0);
-  if (length > 1_000_000) throw new Error("Marketplace feed is too large");
-  const body = await response.text();
-  if (body.length > 1_000_000) throw new Error("Marketplace feed is too large");
-  const payload = JSON.parse(body) as { apps?: unknown };
-  if (!Array.isArray(payload.apps))
-    throw new Error("Marketplace feed is invalid");
-  const candidates = payload.apps.filter((entry): entry is MarketplaceApp => {
-    if (!entry || typeof entry !== "object") return false;
-    const app = entry as Record<string, unknown>;
-    const url =
-      typeof app.url === "string" ? normalizeConnectUrl(app.url) : null;
-    return (
-      typeof app.id === "string" &&
-      typeof app.name === "string" &&
-      typeof app.description === "string" &&
-      typeof app.url === "string" &&
-      Boolean(url) &&
-      Array.isArray(app.capabilities) &&
-      app.capabilities.every((capability) => typeof capability === "string")
-    );
-  });
-  const verified = await Promise.allSettled(
-    candidates.map(async (app) => {
-      const card = await fetchConnectAgentCard(app.url);
-      return card.connect ? { ...app, capabilities: ["connect"] } : null;
-    }),
-  );
-  return verified.flatMap((result) =>
-    result.status === "fulfilled" && result.value ? [result.value] : [],
-  );
-}
-
-export async function fetchConnectAgentCard(
-  appUrl: string,
-): Promise<ConnectAgentCard> {
-  const target = normalizeConnectUrl(appUrl);
-  if (!target) throw new Error("Enter a secure app URL.");
-  const response = await fetch(
-    appPathUrl(target.toString(), "/.well-known/agent-card.json").toString(),
-    {
-      headers: { accept: "application/json" },
-      signal: AbortSignal.timeout(5_000),
-    },
-  );
-  if (!response.ok) throw new Error(`Agent card returned ${response.status}`);
-  const length = Number(response.headers.get("content-length") ?? 0);
-  if (length > 256_000) throw new Error("Agent card is too large");
-  const body = await response.text();
-  if (body.length > 256_000) throw new Error("Agent card is too large");
-  const card = parseConnectAgentCard(
-    JSON.parse(body),
-    target.origin,
-    target.pathname,
-  );
-  if (!card)
-    throw new Error("This app has an invalid or incompatible agent card.");
-  return card;
+export function buildAgentCardUrl(appUrl: string): string {
+  return appPathUrl(appUrl, "/.well-known/agent-card.json").toString();
 }
 
 function appPathUrl(appUrl: string, suffix: string): URL {

package/src/lib/workspace-apps.ts

@@ -18,6 +18,7 @@ export interface WorkspaceAppSummary {
   id: string;
   name: string;
   description?: string;
+  whenToUse?: string[];
   defaultDescriptionKey?: string;
   path: string;
   homePath?: string;

package/src/routes/pages/$appId.tsx

@@ -98,6 +98,7 @@ export default function WorkspaceAppCatchAllRoute() {
         <ActionQueryError
           error={appsQuery.error}
           onRetry={() => void appsQuery.refetch()}
+          queryName="list-workspace-apps"
         />
       </DispatchShell>
     );

package/src/routes/pages/apps.spec.tsx

@@ -11,12 +11,18 @@ const queryState = vi.hoisted(() => ({
   connectedApps: [] as Array<Record<string, unknown>>,
   connectedAppsError: null as Error | null,
   connectedAppsLoading: false,
+  communityAppsEnabled: false,
+  communityApps: [] as Array<Record<string, unknown>>,
+  installCommunityApp: vi.fn(),
+  installCommunityAppResult: null as Record<string, unknown> | null,
+  sendToAgentChat: vi.fn(),
 }));
 
 vi.mock("@agent-native/core/client/hooks", () => ({
   useActionQuery: (action: string) => {
     const workspaceApps = action === "list-workspace-apps";
     const connectedApps = action === "list-connected-agents";
+    const communityApps = action === "list-curated-community-apps";
     const error = workspaceApps
       ? queryState.workspaceAppsError
       : connectedApps
@@ -27,7 +33,9 @@ vi.mock("@agent-native/core/client/hooks", () => ({
         ? queryState.workspaceApps
         : connectedApps
           ? queryState.connectedApps
-          : { name: null, displayName: null, appCount: 0 },
+          : communityApps
+            ? queryState.communityApps
+            : { name: null, displayName: null, appCount: 0 },
       error,
       isError: Boolean(error),
       isLoading: workspaceApps
@@ -38,6 +46,30 @@ vi.mock("@agent-native/core/client/hooks", () => ({
       refetch: vi.fn(),
     };
   },
+  useActionMutation: (
+    _action: string,
+    options?: { onSuccess?: (result: Record<string, unknown>) => void },
+  ) => ({
+    mutate: (input: unknown) => {
+      queryState.installCommunityApp(input);
+      if (queryState.installCommunityAppResult) {
+        options?.onSuccess?.(queryState.installCommunityAppResult);
+      }
+    },
+    isPending: false,
+  }),
+}));
+
+vi.mock("@agent-native/core/client/agent-chat", () => ({
+  sendToAgentChat: queryState.sendToAgentChat,
+}));
+
+vi.mock("@agent-native/core/client/labs", () => ({
+  useLab: () => queryState.communityAppsEnabled,
+}));
+
+vi.mock("../../shared/labs.js", () => ({
+  COMMUNITY_APPS_LAB: { key: "dispatch.community-apps", defaultEnabled: false },
 }));
 
 vi.mock("@agent-native/core/client/i18n", () => ({
@@ -48,8 +80,16 @@ vi.mock("@agent-native/core/client/i18n", () => ({
 }));
 
 vi.mock("../../components/action-query-error", () => ({
-  ActionQueryError: ({ error }: { error: Error }) => (
-    <div role="alert">{error.message}</div>
+  ActionQueryError: ({
+    error,
+    queryName,
+  }: {
+    error: Error;
+    queryName?: string;
+  }) => (
+    <div role="alert">
+      {queryName}: {error.message}
+    </div>
   ),
 }));
 
@@ -92,6 +132,11 @@ describe("Dispatch apps route", () => {
     queryState.connectedApps = [];
     queryState.connectedAppsError = null;
     queryState.connectedAppsLoading = false;
+    queryState.communityAppsEnabled = false;
+    queryState.communityApps = [];
+    queryState.installCommunityApp.mockReset();
+    queryState.installCommunityAppResult = null;
+    queryState.sendToAgentChat.mockReset();
     container = document.createElement("div");
     document.body.appendChild(container);
     root = createRoot(container);
@@ -129,4 +174,183 @@ describe("Dispatch apps route", () => {
 
     expect(container.textContent).toContain("No workspace apps");
   });
+
+  it("identifies each app discovery query when both fail", async () => {
+    queryState.workspaceAppsError = new Error("Workspace app list failed");
+    queryState.connectedAppsError = new Error("Connected agent list failed");
+
+    await renderAppsRoute();
+
+    const errors = Array.from(
+      container.querySelectorAll('[role="alert"]'),
+      (alert) => alert.textContent,
+    );
+    expect(errors).toContain("list-workspace-apps: Workspace app list failed");
+    expect(errors).toContain(
+      "list-connected-agents: Connected agent list failed",
+    );
+  });
+
+  it("hides community apps while the Lab is off", async () => {
+    await renderAppsRoute();
+
+    expect(container.textContent).not.toContain("dispatch.pages.communityApps");
+  });
+
+  it("lists the reviewed catalog and starts the selected install", async () => {
+    queryState.communityAppsEnabled = true;
+    queryState.communityApps = [
+      {
+        id: "community-qr",
+        name: "QR",
+        description: "Generate QR images.",
+        appId: "community-qr",
+        repo: "BuilderIO/agent-native",
+        ref: "main",
+        license: "MIT",
+        provenance: "Reviewed source",
+        templatePath: "templates/community/qr",
+        installed: false,
+        pending: false,
+        installable: true,
+      },
+    ];
+
+    await renderAppsRoute();
+
+    expect(container.textContent).toContain("QR");
+    expect(
+      container.querySelector<HTMLAnchorElement>("a[href*='github.com']")?.href,
+    ).toContain("/tree/main/templates/community/qr");
+    const installButton = Array.from(
+      container.querySelectorAll<HTMLButtonElement>("button"),
+    ).find((button) =>
+      button.textContent?.includes("dispatch.pages.communityAppsInstall"),
+    );
+    expect(installButton).toBeDefined();
+    await act(async () => installButton?.click());
+    expect(queryState.installCommunityApp).toHaveBeenCalledWith({
+      sourceId: "community-qr",
+    });
+  });
+
+  it("sends verified source files to the local code agent", async () => {
+    queryState.communityAppsEnabled = true;
+    queryState.communityApps = [
+      {
+        id: "community-qr",
+        name: "QR",
+        description: "Generate QR images.",
+        appId: "community-qr",
+        repo: "BuilderIO/agent-native",
+        ref: "main",
+        license: "MIT",
+        provenance: "Reviewed source",
+        templatePath: "templates/community/qr",
+        installed: false,
+        pending: false,
+        installable: true,
+      },
+    ];
+    queryState.installCommunityAppResult = {
+      mode: "local-agent",
+      prompt: "Create this app from the pinned files.",
+      attachments: [
+        {
+          type: "file",
+          name: "community-qr/README.md",
+          contentType: "text/plain",
+          text: "Verified source",
+        },
+      ],
+    };
+
+    await renderAppsRoute();
+    const installButton = Array.from(
+      container.querySelectorAll<HTMLButtonElement>("button"),
+    ).find((button) =>
+      button.textContent?.includes("dispatch.pages.communityAppsInstall"),
+    );
+    await act(async () => installButton?.click());
+
+    expect(queryState.sendToAgentChat).toHaveBeenCalledWith({
+      message: "Create this app from the pinned files.",
+      attachments: [
+        {
+          type: "file",
+          name: "community-qr/README.md",
+          contentType: "text/plain",
+          text: "Verified source",
+        },
+      ],
+      submit: true,
+      type: "code",
+      newTab: true,
+      reuseEmptyTab: true,
+    });
+  });
+
+  it("explains when a community app ID is already in use", async () => {
+    queryState.communityAppsEnabled = true;
+    queryState.communityApps = [
+      {
+        id: "community-qr",
+        name: "QR",
+        description: "Generate QR images.",
+        appId: "qr",
+        repo: "BuilderIO/agent-native",
+        ref: "main",
+        license: "MIT",
+        provenance: "Reviewed source",
+        templatePath: "templates/community/qr",
+        installed: false,
+        pending: false,
+        installable: false,
+        installUnavailableReason: "app-id-conflict",
+      },
+    ];
+
+    await renderAppsRoute();
+
+    expect(container.textContent).toContain(
+      "dispatch.pages.communityAppsIdConflict",
+    );
+    expect(
+      Array.from(container.querySelectorAll("button")).some((button) =>
+        button.textContent?.includes("dispatch.pages.communityAppsInstall"),
+      ),
+    ).toBe(false);
+  });
+
+  it("explains when Builder-mode community installs cannot be verified", async () => {
+    queryState.communityAppsEnabled = true;
+    queryState.communityApps = [
+      {
+        id: "community-qr",
+        name: "QR",
+        description: "Generate QR images.",
+        appId: "community-qr",
+        repo: "BuilderIO/agent-native",
+        ref: "main",
+        license: "MIT",
+        provenance: "Reviewed source",
+        templatePath: "templates/community/qr",
+        installed: false,
+        pending: false,
+        installable: false,
+        installUnavailableReason: "builder-install-unverified",
+      },
+    ];
+
+    await renderAppsRoute();
+
+    expect(container.textContent).toContain(
+      "dispatch.pages.communityAppsBuilderInstallUnavailable",
+    );
+    expect(
+      Array.from(container.querySelectorAll("button")).some((button) =>
+        button.textContent?.includes("dispatch.pages.communityAppsInstall"),
+      ),
+    ).toBe(false);
+  });
 });

package/src/routes/pages/apps.tsx

@@ -16,6 +16,7 @@ import {
   APP_LIST_GRID_ROW_CLASS,
   AppList,
 } from "../../components/app-list-row";
+import { CommunityAppsSection } from "../../components/community-apps-section";
 import { ConnectedAppCard } from "../../components/connected-app-card";
 import { CreateAppPopover } from "../../components/create-app-popover";
 import { DispatchShell } from "../../components/dispatch-shell";
@@ -184,12 +185,14 @@ function AppsRoute() {
             <ActionQueryError
               error={appsQuery.error}
               onRetry={() => void appsQuery.refetch()}
+              queryName="list-workspace-apps"
             />
           ) : null}
           {connectedAppsQuery.isError ? (
             <ActionQueryError
               error={connectedAppsQuery.error}
               onRetry={() => void connectedAppsQuery.refetch()}
+              queryName="list-connected-agents"
             />
           ) : null}
           {showAppSkeletons ? (
@@ -346,6 +349,8 @@ function AppsRoute() {
             </section>
           </Collapsible>
         ) : null}
+
+        <CommunityAppsSection />
       </div>
     </DispatchShell>
   );

package/src/routes/pages/connect.spec.tsx

@@ -8,7 +8,8 @@ import ConnectRoute from "./connect";
 const connectState = vi.hoisted(() => ({
   enabled: false,
   status: "ready" as "loading" | "ready",
-  useQuery: vi.fn(() => ({ data: [], isLoading: false, isError: false })),
+  useActionQuery: vi.fn(() => ({ data: [], isLoading: false, isError: false })),
+  useActionMutation: vi.fn(() => ({ mutateAsync: vi.fn() })),
 }));
 
 vi.mock("@agent-native/core/client/feature-flags", () => ({
@@ -23,8 +24,9 @@ vi.mock("../../components/dispatch-shell", () => ({
 vi.mock("@agent-native/core/client/i18n", () => ({
   useT: () => (key: string) => key,
 }));
-vi.mock("@tanstack/react-query", () => ({
-  useQuery: connectState.useQuery,
+vi.mock("@agent-native/core/client/hooks", () => ({
+  useActionQuery: connectState.useActionQuery,
+  useActionMutation: connectState.useActionMutation,
 }));
 
 describe("ConnectRoute", () => {
@@ -34,7 +36,8 @@ describe("ConnectRoute", () => {
   beforeEach(() => {
     connectState.enabled = false;
     connectState.status = "ready";
-    connectState.useQuery.mockClear();
+    connectState.useActionQuery.mockClear();
+    connectState.useActionMutation.mockClear();
     container = document.createElement("div");
     document.body.appendChild(container);
     root = createRoot(container);
@@ -48,13 +51,57 @@ describe("ConnectRoute", () => {
   it("renders nothing and does not fetch when the labs flag is off", async () => {
     await act(async () => root.render(<ConnectRoute />));
     expect(container.innerHTML).toBe("");
-    expect(connectState.useQuery).not.toHaveBeenCalled();
+    expect(connectState.useActionQuery).not.toHaveBeenCalled();
+    expect(connectState.useActionMutation).not.toHaveBeenCalled();
   });
 
   it("shows the page skeleton while the labs flag is loading", async () => {
     connectState.status = "loading";
     await act(async () => root.render(<ConnectRoute />));
     expect(container.querySelector('[aria-busy="true"]')).not.toBeNull();
-    expect(connectState.useQuery).not.toHaveBeenCalled();
+    expect(connectState.useActionQuery).not.toHaveBeenCalled();
+    expect(connectState.useActionMutation).not.toHaveBeenCalled();
+  });
+
+  it("inspects a URL through the server action and renders its card", async () => {
+    connectState.enabled = true;
+    const mutateAsync = vi.fn().mockResolvedValue({
+      name: "Slides",
+      description: "A slide workspace",
+      url: "https://slides.example.com/_agent-native/a2a",
+      connect: true,
+    });
+    connectState.useActionMutation.mockReturnValue({ mutateAsync } as never);
+
+    await act(async () => root.render(<ConnectRoute />));
+    expect(connectState.useActionQuery).toHaveBeenCalledWith(
+      "list-connect-marketplace-apps",
+      {},
+      { staleTime: 5 * 60 * 1000, retry: 1 },
+    );
+
+    const input = container.querySelector("input");
+    expect(input).not.toBeNull();
+    await act(async () => {
+      const setter = Object.getOwnPropertyDescriptor(
+        HTMLInputElement.prototype,
+        "value",
+      )?.set;
+      setter?.call(input, "https://slides.example.com");
+      input?.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+
+    const inspectButton = [...container.querySelectorAll("button")].find(
+      (button) => button.textContent?.includes("dispatch.pages.inspectApp"),
+    );
+    expect(inspectButton).toBeDefined();
+    await act(async () => inspectButton?.click());
+
+    expect(mutateAsync).toHaveBeenCalledWith({
+      url: "https://slides.example.com/",
+    });
+    expect(container.querySelector("[data-connect-card] h3")?.textContent).toBe(
+      "Slides",
+    );
   });
 });

package/src/routes/pages/connect.tsx

@@ -1,7 +1,10 @@
 import { useFeatureFlagState } from "@agent-native/core/client/feature-flags";
+import {
+  useActionMutation,
+  useActionQuery,
+} from "@agent-native/core/client/hooks";
 import { useT } from "@agent-native/core/client/i18n";
 import { IconExternalLink, IconPlugConnected } from "@tabler/icons-react";
-import { useQuery } from "@tanstack/react-query";
 import { useState } from "react";
 
 import { AppIcon } from "../../components/app-icon";
@@ -11,8 +14,6 @@ import { Input } from "../../components/ui/input";
 import { Skeleton } from "../../components/ui/skeleton";
 import {
   buildIdentityConnectUrl,
-  fetchConnectAgentCard,
-  fetchMarketplaceApps,
   normalizeConnectUrl,
   type ConnectAgentCard,
   type MarketplaceApp,
@@ -143,13 +144,15 @@ function ConnectAppsContent() {
   const [card, setCard] = useState<ConnectAgentCard | null>(null);
   const [cardError, setCardError] = useState(false);
   const [cardLoading, setCardLoading] = useState(false);
-  const feedQuery = useQuery({
-    queryKey: ["connect-apps-marketplace"],
-    queryFn: () => fetchMarketplaceApps(),
-    enabled: true,
-    staleTime: 5 * 60 * 1000,
-    retry: 1,
-  });
+  const feedQuery = useActionQuery(
+    "list-connect-marketplace-apps",
+    {},
+    {
+      staleTime: 5 * 60 * 1000,
+      retry: 1,
+    },
+  );
+  const inspectCard = useActionMutation("inspect-connect-agent-card");
 
   const target = normalizeConnectUrl(url);
 
@@ -159,7 +162,7 @@ function ConnectAppsContent() {
     setCardError(false);
     setCard(null);
     try {
-      setCard(await fetchConnectAgentCard(target.toString()));
+      setCard(await inspectCard.mutateAsync({ url: target.toString() }));
     } catch {
       setCardError(true);
     } finally {

package/src/server/index.ts

@@ -7,6 +7,15 @@ import {
 import { dispatchActions } from "../actions/index.js";
 import type { DispatchConfig } from "../config.js";
 import { dispatchAccessDescriptor } from "../shared/app-roles.js";
+export {
+  listOrganizationVisibleWorkspaceApps,
+  listWorkspaceApps,
+} from "./lib/app-creation-store.js";
+export {
+  invalidateOrgAppsDirectoryCache,
+  orgAppsDirectoryAccessCache,
+  orgAppsDirectoryCache,
+} from "./lib/org-apps-directory-cache.js";
 
 defineAppRoles(dispatchAccessDescriptor, { allowOrgAdmins: true });