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

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

@@ -34,7 +34,13 @@ vi.mock("../../../core/dist/client/i18n.js", () => ({
 }));
 
 vi.mock("@agent-native/core/client/hooks", () => ({
-  useActionMutation: () => ({ mutate: vi.fn(), isPending: false }),
+  useActionMutation: (action: string) => ({
+    mutate:
+      action === "update-workspace-app-metadata"
+        ? metadataMutationState.mutate
+        : vi.fn(),
+    isPending: false,
+  }),
   useActionQuery: () => ({
     data: { resources: [], counts: {} },
     isLoading: false,
@@ -53,6 +59,8 @@ vi.mock("@agent-native/core/client/i18n", () => ({
 }));
 
 const frameState = vi.hoisted(() => ({ inBuilderFrame: false }));
+const orgRoleState = vi.hoisted(() => ({ role: "owner" as string }));
+const metadataMutationState = vi.hoisted(() => ({ mutate: vi.fn() }));
 
 function LocationProbe() {
   const location = useLocation();
@@ -64,6 +72,24 @@ vi.mock("@agent-native/core/client/host", () => ({
   isInBuilderFrame: () => frameState.inBuilderFrame,
 }));
 
+vi.mock("@agent-native/core/client/org", () => ({
+  useOrgRole: () => ({
+    org: { orgId: "org-123" },
+    role: orgRoleState.role,
+    isLoading: false,
+    error: null,
+  }),
+}));
+
+function setTextareaValue(textarea: HTMLTextAreaElement, value: string) {
+  const setter = Object.getOwnPropertyDescriptor(
+    HTMLTextAreaElement.prototype,
+    "value",
+  )?.set;
+  setter?.call(textarea, value);
+  textarea.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
 describe("WorkspaceAppCard", () => {
   let container: HTMLDivElement;
   let root: Root;
@@ -71,6 +97,8 @@ describe("WorkspaceAppCard", () => {
 
   beforeEach(() => {
     frameState.inBuilderFrame = false;
+    orgRoleState.role = "owner";
+    metadataMutationState.mutate.mockClear();
     vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
     container = document.createElement("div");
     document.body.appendChild(container);
@@ -90,6 +118,203 @@ describe("WorkspaceAppCard", () => {
     vi.unstubAllGlobals();
   });
 
+  it("edits the app's when-to-use examples with the existing details form", async () => {
+    await act(async () => {
+      root.render(
+        <MemoryRouter>
+          <TooltipProvider>
+            <WorkspaceAppCard
+              app={{
+                id: "analytics",
+                name: "Analytics",
+                path: "/analytics",
+                status: "ready",
+                whenToUse: [
+                  "Explain this week's activation trend",
+                  "Compare signup sources",
+                ],
+              }}
+            />
+          </TooltipProvider>
+        </MemoryRouter>,
+      );
+    });
+
+    const settingsButton = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="Settings for Analytics"]',
+    );
+    await act(async () => {
+      settingsButton?.dispatchEvent(
+        new MouseEvent("pointerdown", { bubbles: true, button: 0 }),
+      );
+    });
+    const editItem = Array.from(
+      document.querySelectorAll<HTMLElement>('[role="menuitem"]'),
+    ).find((item) => item.textContent?.includes("Edit details"));
+    expect(editItem).not.toBeUndefined();
+
+    await act(async () => editItem?.click());
+
+    const whenToUse = document.querySelector<HTMLTextAreaElement>(
+      "#app-when-to-use-analytics",
+    );
+    expect(whenToUse?.value).toBe(
+      "Explain this week's activation trend\nCompare signup sources",
+    );
+    expect(document.body.textContent).toContain("When to use");
+  });
+
+  it("validates profile examples and normalizes description line breaks", async () => {
+    await act(async () => {
+      root.render(
+        <MemoryRouter>
+          <TooltipProvider>
+            <WorkspaceAppCard
+              app={{
+                id: "analytics",
+                name: "Analytics",
+                path: "/analytics",
+                status: "ready",
+                whenToUse: ["Compare signup sources"],
+              }}
+            />
+          </TooltipProvider>
+        </MemoryRouter>,
+      );
+    });
+
+    const settingsButton = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="Settings for Analytics"]',
+    );
+    await act(async () => {
+      settingsButton?.dispatchEvent(
+        new MouseEvent("pointerdown", { bubbles: true, button: 0 }),
+      );
+    });
+    const editItem = Array.from(
+      document.querySelectorAll<HTMLElement>('[role="menuitem"]'),
+    ).find((item) => item.textContent?.includes("Edit details"));
+    await act(async () => editItem?.click());
+
+    const examples = document.querySelector<HTMLTextAreaElement>(
+      "#app-when-to-use-analytics",
+    );
+    const description = document.querySelector<HTMLTextAreaElement>(
+      "#app-description-analytics",
+    );
+    const save = Array.from(
+      document.querySelectorAll<HTMLButtonElement>('button[type="submit"]'),
+    ).find((button) => button.textContent?.includes("Save"));
+    expect(examples).not.toBeNull();
+    expect(description).not.toBeNull();
+    expect(save).not.toBeNull();
+
+    await act(async () => {
+      setTextareaValue(
+        examples!,
+        Array.from({ length: 7 }, (_, i) => `Example ${i + 1}`).join("\n"),
+      );
+    });
+    expect(save?.disabled).toBe(true);
+
+    await act(async () => {
+      setTextareaValue(examples!, `${"x".repeat(141)}\nValid example`);
+    });
+    expect(save?.disabled).toBe(true);
+
+    await act(async () => {
+      setTextareaValue(examples!, "Safe\u0001 example");
+      setTextareaValue(description!, "First line\nSecond line");
+    });
+    expect(examples?.value).toBe("Safe example");
+    expect(description?.value).toBe("First line Second line");
+    expect(save?.disabled).toBe(false);
+  });
+
+  it("submits only the profile field that changed", async () => {
+    await act(async () => {
+      root.render(
+        <MemoryRouter>
+          <TooltipProvider>
+            <WorkspaceAppCard
+              app={{
+                id: "analytics",
+                name: "Analytics",
+                description: "Original description",
+                path: "/analytics",
+                status: "ready",
+                whenToUse: ["Compare signup sources"],
+              }}
+            />
+          </TooltipProvider>
+        </MemoryRouter>,
+      );
+    });
+
+    const settingsButton = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="Settings for Analytics"]',
+    );
+    await act(async () => {
+      settingsButton?.dispatchEvent(
+        new MouseEvent("pointerdown", { bubbles: true, button: 0 }),
+      );
+    });
+    const editItem = Array.from(
+      document.querySelectorAll<HTMLElement>('[role="menuitem"]'),
+    ).find((item) => item.textContent?.includes("Edit details"));
+    await act(async () => editItem?.click());
+
+    const examples = document.querySelector<HTMLTextAreaElement>(
+      "#app-when-to-use-analytics",
+    );
+    const form = examples?.closest("form");
+    await act(async () => {
+      setTextareaValue(examples!, "Track acquisition by channel");
+      form?.dispatchEvent(
+        new Event("submit", { bubbles: true, cancelable: true }),
+      );
+    });
+
+    expect(metadataMutationState.mutate).toHaveBeenCalledWith({
+      appId: "analytics",
+      whenToUse: ["Track acquisition by channel"],
+    });
+  });
+
+  it("hides Edit details from members", async () => {
+    orgRoleState.role = "member";
+    await act(async () => {
+      root.render(
+        <MemoryRouter>
+          <TooltipProvider>
+            <WorkspaceAppCard
+              app={{
+                id: "analytics",
+                name: "Analytics",
+                path: "/analytics",
+                status: "ready",
+              }}
+            />
+          </TooltipProvider>
+        </MemoryRouter>,
+      );
+    });
+
+    const settingsButton = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="Settings for Analytics"]',
+    );
+    await act(async () => {
+      settingsButton?.dispatchEvent(
+        new MouseEvent("pointerdown", { bubbles: true, button: 0 }),
+      );
+    });
+    expect(
+      Array.from(
+        document.querySelectorAll<HTMLElement>('[role="menuitem"]'),
+      ).some((item) => item.textContent?.includes("Edit details")),
+    ).toBe(false);
+  });
+
   it("opens ready apps inline and keeps new-tab opening in the chevron menu", async () => {
     await act(async () => {
       root.render(

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",
+    ]);
   });
 });