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

package/src/components/workspace-app-card.tsx

@@ -3,6 +3,8 @@ import {
   useActionQuery,
 } from "@agent-native/core/client/hooks";
 import { useT } from "@agent-native/core/client/i18n";
+import { useOrgRole } from "@agent-native/core/client/org";
+import { parseAgentProfileMetadata } from "@agent-native/core/shared";
 import { APP_ACTION_MENU_CONTENT_CLASS } from "@agent-native/toolkit/app/chat/chat-first/app-open-actions";
 import { ShareButton } from "@agent-native/toolkit/app/sharing";
 import {
@@ -70,6 +72,23 @@ import { AppResourceEffectiveStack } from "./workspace-resource-effective-stack"
 const APP_CARD_ACTION_CLASS =
   "size-7 rounded-md p-0 text-muted-foreground transition-[background-color,color] hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring data-[state=open]:bg-accent data-[state=open]:text-foreground";
 
+function normalizeProfileDescription(value: string): string {
+  return value.replace(/[\r\n]+/g, " ").replace(/[\u0000-\u001f\u007f]/g, "");
+}
+
+function normalizeWhenToUseText(value: string): string {
+  return value
+    .replace(/\r\n?/g, "\n")
+    .replace(/[\u0000-\u0009\u000b-\u001f\u007f]/g, "");
+}
+
+function parseWhenToUseText(value: string): string[] {
+  return value
+    .split("\n")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
 function deferWorkspaceAppOverlayOpen(
   event: { preventDefault: () => void },
   closeMenu: () => void,
@@ -108,6 +127,12 @@ export function WorkspaceAppCard({
   onTogglePinned?: () => void;
 }) {
   const t = useT();
+  const { org, role, isLoading: orgLoading, error: orgError } = useOrgRole();
+  const canEditMetadata =
+    !orgLoading &&
+    !orgError &&
+    !!org?.orgId &&
+    (role === "owner" || role === "admin");
   const href = workspaceAppHref(app);
   const directHref =
     app.status !== "pending" &&
@@ -130,14 +155,27 @@ export function WorkspaceAppCard({
   const [resourcesOpen, setResourcesOpen] = useState(false);
   const [draftName, setDraftName] = useState(app.name);
   const [draftDescription, setDraftDescription] = useState(
-    app.description || "",
+    normalizeProfileDescription(app.description || ""),
+  );
+  const [draftWhenToUse, setDraftWhenToUse] = useState(
+    app.whenToUse?.join("\n") ?? "",
+  );
+  const draftWhenToUseValues = parseWhenToUseText(draftWhenToUse);
+  const validProfile = Boolean(
+    parseAgentProfileMetadata({
+      ...(draftDescription.trim()
+        ? { description: draftDescription.trim() }
+        : {}),
+      whenToUse: draftWhenToUseValues,
+    }),
   );
 
   useEffect(() => {
     if (editOpen) return;
     setDraftName(app.name);
-    setDraftDescription(app.description || "");
-  }, [app.description, app.name, editOpen]);
+    setDraftDescription(normalizeProfileDescription(app.description || ""));
+    setDraftWhenToUse(app.whenToUse?.join("\n") ?? "");
+  }, [app.description, app.name, app.whenToUse, editOpen]);
 
   const archive = useActionMutation("archive-workspace-app", {
     onError: (err) =>
@@ -179,10 +217,35 @@ export function WorkspaceAppCard({
       toast.error("App name is required.");
       return;
     }
+    const description = draftDescription.trim();
+    const currentDescription = normalizeProfileDescription(
+      app.description || "",
+    ).trim();
+    const currentWhenToUse = app.whenToUse ?? [];
+    const nameChanged = name !== app.name.trim();
+    const descriptionChanged = description !== currentDescription;
+    const whenToUseChanged =
+      draftWhenToUseValues.length !== currentWhenToUse.length ||
+      draftWhenToUseValues.some(
+        (example, index) => example !== currentWhenToUse[index],
+      );
+    if (
+      !parseAgentProfileMetadata({
+        ...(description ? { description } : {}),
+        whenToUse: draftWhenToUseValues,
+      })
+    ) {
+      return;
+    }
+    if (!nameChanged && !descriptionChanged && !whenToUseChanged) {
+      setEditOpen(false);
+      return;
+    }
     updateMetadata.mutate({
       appId: app.id,
-      name,
-      description: draftDescription.trim(),
+      ...(nameChanged ? { name } : {}),
+      ...(descriptionChanged ? { description } : {}),
+      ...(whenToUseChanged ? { whenToUse: draftWhenToUseValues } : {}),
     });
   };
   const pinLabel = t(
@@ -247,6 +310,7 @@ export function WorkspaceAppCard({
           />
           <WorkspaceAppSettings
             app={app}
+            canEditMetadata={canEditMetadata}
             isArchived={isArchived}
             isPending={isPending}
             onEdit={() => setEditOpen(true)}
@@ -284,10 +348,42 @@ export function WorkspaceAppCard({
               <Textarea
                 id={`app-description-${app.id}`}
                 value={draftDescription}
-                maxLength={500}
+                maxLength={1000}
                 rows={4}
-                onChange={(event) => setDraftDescription(event.target.value)}
+                onChange={(event) =>
+                  setDraftDescription(
+                    normalizeProfileDescription(event.target.value),
+                  )
+                }
+              />
+            </div>
+            <div className="space-y-2">
+              <Label htmlFor={`app-when-to-use-${app.id}`}>
+                {t("dispatch.pages.appProfileWhenToUse", {
+                  defaultValue: "When to use",
+                })}
+              </Label>
+              <Textarea
+                id={`app-when-to-use-${app.id}`}
+                value={draftWhenToUse}
+                aria-invalid={!validProfile}
+                rows={3}
+                placeholder={t(
+                  "dispatch.pages.appProfileWhenToUsePlaceholder",
+                  {
+                    defaultValue: "One example request per line",
+                  },
+                )}
+                onChange={(event) =>
+                  setDraftWhenToUse(normalizeWhenToUseText(event.target.value))
+                }
               />
+              <p className="text-xs text-muted-foreground">
+                {t("dispatch.pages.appProfileWhenToUseHint", {
+                  defaultValue:
+                    "Add up to 6 examples, with no more than 140 characters each.",
+                })}
+              </p>
             </div>
             <DialogFooter>
               <Button
@@ -297,7 +393,10 @@ export function WorkspaceAppCard({
               >
                 Cancel
               </Button>
-              <Button type="submit" disabled={updateMetadata.isPending}>
+              <Button
+                type="submit"
+                disabled={updateMetadata.isPending || !validProfile}
+              >
                 {updateMetadata.isPending ? "Saving..." : "Save"}
               </Button>
             </DialogFooter>
@@ -406,6 +505,7 @@ type WorkspaceAppMetadataLabels = {
 
 function WorkspaceAppSettings({
   app,
+  canEditMetadata,
   isArchived,
   isPending,
   onEdit,
@@ -417,6 +517,7 @@ function WorkspaceAppSettings({
   labels,
 }: {
   app: WorkspaceAppSummary;
+  canEditMetadata: boolean;
   isArchived: boolean;
   isPending: boolean;
   onEdit: () => void;
@@ -477,10 +578,12 @@ function WorkspaceAppSettings({
             )
           }
         >
-          <DropdownMenuItem onSelect={onEdit}>
-            <IconEdit size={14} aria-hidden="true" />
-            Edit details
-          </DropdownMenuItem>
+          {canEditMetadata ? (
+            <DropdownMenuItem onSelect={onEdit}>
+              <IconEdit size={14} aria-hidden="true" />
+              Edit details
+            </DropdownMenuItem>
+          ) : null}
           {!isPending ? (
             <DropdownMenuItem
               onSelect={(event) =>

package/src/lib/connect-apps.spec.ts

@@ -1,21 +1,41 @@
-import { describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { ssrfSafeFetchMock } = vi.hoisted(() => ({
+  ssrfSafeFetchMock: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/extensions/url-safety", () => ({
+  ssrfSafeFetch: (...args: unknown[]) => ssrfSafeFetchMock(...args),
+}));
 
 import {
-  buildIdentityConnectUrl,
   fetchConnectAgentCard,
   fetchMarketplaceApps,
+} from "../server/lib/connect-apps";
+import {
+  buildAgentCardUrl,
+  buildIdentityConnectUrl,
   normalizeConnectUrl,
   parseConnectAgentCard,
 } from "./connect-apps";
 
 describe("connect apps helpers", () => {
+  beforeEach(() => ssrfSafeFetchMock.mockReset());
+
   it("rejects unsafe or credential-bearing URLs", () => {
     expect(normalizeConnectUrl("javascript:alert(1)")).toBeNull();
     expect(normalizeConnectUrl("https://user:pass@example.com")).toBeNull();
     expect(normalizeConnectUrl("https://127.0.0.1")).toBeNull();
     expect(normalizeConnectUrl("https://169.254.169.254")).toBeNull();
     expect(normalizeConnectUrl("https://[::1]")).toBeNull();
-    expect(normalizeConnectUrl("http://localhost:3000")).not.toBeNull();
+    expect(normalizeConnectUrl("https://[::ffff:127.0.0.1]")).toBeNull();
+    expect(normalizeConnectUrl("https://[::ffff:7f00:1]")).toBeNull();
+    expect(normalizeConnectUrl("https://[::ffff:6440:1]")).toBeNull();
+    expect(normalizeConnectUrl("https://[::ffff:0:0]")).toBeNull();
+    expect(normalizeConnectUrl("https://[fc00::1]")).toBeNull();
+    expect(normalizeConnectUrl("https://[fe80::1]")).toBeNull();
+    expect(normalizeConnectUrl("https://fdroid.org")).not.toBeNull();
+    expect(normalizeConnectUrl("http://localhost:3000")).toBeNull();
   });
 
   it("accepts a connect-capable card only from the requested origin", () => {
@@ -84,24 +104,17 @@ describe("connect apps helpers", () => {
     expect(url.searchParams.get("return")).toBe("/_agent-native/open");
   });
 
-  it("preserves a path-mounted app when building connection URLs", async () => {
-    const identity = new URL(
-      buildIdentityConnectUrl(
-        "https://community.agent-native.com/account-tiering",
-      ),
-    );
-    expect(identity.pathname).toBe(
-      "/account-tiering/_agent-native/identity/login",
-    );
-    expect(identity.searchParams.get("return")).toBe(
-      "/account-tiering/_agent-native/open",
+  it("builds a path-mounted agent card URL", () => {
+    expect(
+      buildAgentCardUrl("https://community.agent-native.com/account-tiering"),
+    ).toBe(
+      "https://community.agent-native.com/account-tiering/.well-known/agent-card.json",
     );
+  });
 
-    const originalFetch = globalThis.fetch;
-    let requestedUrl = "";
-    globalThis.fetch = (async (input) => {
-      requestedUrl = String(input);
-      return new Response(
+  it("fetches agent cards through the server SSRF boundary", async () => {
+    ssrfSafeFetchMock.mockResolvedValue(
+      new Response(
         JSON.stringify({
           name: "Account Tiering",
           description: "Prioritize accounts",
@@ -109,57 +122,96 @@ describe("connect apps helpers", () => {
           capabilities: { connect: true },
         }),
         { status: 200 },
-      );
-    }) as typeof fetch;
-    try {
-      await fetchConnectAgentCard(
+      ),
+    );
+
+    await expect(
+      fetchConnectAgentCard(
         "https://community.agent-native.com/account-tiering",
-      );
-      expect(requestedUrl).toBe(
+      ),
+    ).resolves.toMatchObject({ name: "Account Tiering", connect: true });
+    expect(ssrfSafeFetchMock).toHaveBeenCalledWith(
+      "https://community.agent-native.com/account-tiering/.well-known/agent-card.json",
+      expect.objectContaining({
+        headers: { accept: "application/json" },
+        signal: expect.any(AbortSignal),
+      }),
+      expect.objectContaining({
+        maxRedirects: 3,
+        requireDispatcher: true,
+        httpsOnly: true,
+        assertUrlAllowed: expect.any(Function),
+      }),
+    );
+    const fetchPolicy = ssrfSafeFetchMock.mock.calls[0]?.[2] as {
+      assertUrlAllowed: (url: string) => void;
+    };
+    expect(() =>
+      fetchPolicy.assertUrlAllowed(
+        "https://evil.example.test/account-tiering/.well-known/agent-card.json",
+      ),
+    ).toThrow(/requested URL/);
+    expect(() =>
+      fetchPolicy.assertUrlAllowed(
         "https://community.agent-native.com/account-tiering/.well-known/agent-card.json",
-      );
-    } finally {
-      globalThis.fetch = originalFetch;
-    }
+      ),
+    ).not.toThrow();
+  });
+
+  it("rejects unsafe addresses before calling the server fetch boundary", async () => {
+    await expect(fetchConnectAgentCard("https://127.0.0.1")).rejects.toThrow(
+      /secure app URL/,
+    );
+    await expect(
+      fetchConnectAgentCard("http://localhost:3000"),
+    ).rejects.toThrow(/secure app URL/);
+    expect(ssrfSafeFetchMock).not.toHaveBeenCalled();
   });
 
   it("rejects unsafe marketplace entries before rendering links", async () => {
-    const originalFetch = globalThis.fetch;
-    globalThis.fetch = (async (input) =>
-      new Response(
-        typeof input === "string" && input === "https://feed.test"
-          ? JSON.stringify({
-              apps: [
-                {
-                  id: "unsafe",
-                  name: "Unsafe",
-                  description: "bad",
-                  url: "javascript:alert(1)",
-                  capabilities: ["connect"],
-                },
-                {
-                  id: "safe",
-                  name: "Safe",
-                  description: "ok",
-                  url: "https://safe.example.test",
-                  capabilities: ["connect"],
-                },
-              ],
-            })
-          : JSON.stringify({
-              name: "Safe",
-              description: "ok",
-              url: "https://safe.example.test",
-              capabilities: { connect: true },
-            }),
-        { status: 200 },
-      )) as typeof fetch;
-    try {
-      await expect(fetchMarketplaceApps("https://feed.test")).resolves.toEqual([
-        expect.objectContaining({ id: "safe" }),
-      ]);
-    } finally {
-      globalThis.fetch = originalFetch;
-    }
+    ssrfSafeFetchMock
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            apps: [
+              {
+                id: "unsafe",
+                name: "Unsafe",
+                description: "bad",
+                url: "javascript:alert(1)",
+                capabilities: ["connect"],
+              },
+              {
+                id: "safe",
+                name: "Safe",
+                description: "ok",
+                url: "https://safe.example.test",
+                capabilities: ["connect"],
+              },
+            ],
+          }),
+          { status: 200 },
+        ),
+      )
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            name: "Safe",
+            description: "ok",
+            url: "https://safe.example.test/_agent-native/a2a",
+            capabilities: { connect: true },
+          }),
+          { status: 200 },
+        ),
+      );
+
+    await expect(fetchMarketplaceApps("https://feed.test")).resolves.toEqual([
+      expect.objectContaining({ id: "safe" }),
+    ]);
+    expect(ssrfSafeFetchMock).toHaveBeenCalledTimes(2);
+    expect(ssrfSafeFetchMock.mock.calls.map(([url]) => url)).toEqual([
+      "https://feed.test/",
+      "https://safe.example.test/.well-known/agent-card.json",
+    ]);
   });
 });

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;