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

package/src/actions/update-workspace-app-metadata.ts

@@ -1,33 +1,57 @@
 import { defineAction } from "@agent-native/core/action";
-import { getWorkspaceAppIdValidationError } from "@agent-native/core/shared";
+import {
+  getWorkspaceAppIdValidationError,
+  parseAgentProfileMetadata,
+} from "@agent-native/core/shared";
 import { z } from "zod";
 
 import { updateWorkspaceAppMetadata } from "../server/lib/app-creation-store.js";
 
 export default defineAction({
   description:
-    "Update the human-editable display name and description Dispatch uses for a workspace app. Workspace members can edit these shared details, which are also used as connected-agent/A2A context.",
-  schema: z.object({
-    appId: z
-      .string()
-      .max(64)
-      .refine((appId) => !getWorkspaceAppIdValidationError(appId), {
-        message:
-          "Use a non-reserved app id with lowercase letters, numbers, and hyphens.",
-      })
-      .describe("Workspace app id, matching the apps/<id> folder"),
-    name: z
-      .string()
-      .max(120)
-      .optional()
-      .nullable()
-      .describe("Human-readable app name"),
-    description: z
-      .string()
-      .max(500)
-      .optional()
-      .nullable()
-      .describe("Human-readable app description"),
-  }),
+    "Update a workspace app's display name, description, and when-to-use profile. Only organization owners and admins can edit these shared details.",
+  schema: z
+    .object({
+      appId: z
+        .string()
+        .max(64)
+        .refine((appId) => !getWorkspaceAppIdValidationError(appId), {
+          message:
+            "Use a non-reserved app id with lowercase letters, numbers, and hyphens.",
+        })
+        .describe("Workspace app id, matching the apps/<id> folder"),
+      name: z
+        .string()
+        .max(120)
+        .optional()
+        .nullable()
+        .describe("Human-readable app name"),
+      description: z
+        .string()
+        .max(1000)
+        .optional()
+        .nullable()
+        .describe("Human-readable app description, up to 1,000 characters"),
+      whenToUse: z
+        .array(z.string())
+        .max(6)
+        .optional()
+        .nullable()
+        .describe("Example requests that indicate when this app is useful"),
+    })
+    .superRefine(({ description, whenToUse }, context) => {
+      if (description == null && whenToUse == null) return;
+      const profile = parseAgentProfileMetadata({
+        ...(description != null ? { description } : {}),
+        ...(whenToUse != null ? { whenToUse } : {}),
+      });
+      if (!profile) {
+        context.addIssue({
+          code: "custom",
+          message:
+            "Use a description up to 1,000 characters and up to 6 non-empty examples, each no longer than 140 characters.",
+        });
+      }
+    }),
   run: async (args) => updateWorkspaceAppMetadata(args),
 });

package/src/components/community-apps-section.tsx

@@ -0,0 +1,224 @@
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+import {
+  useActionMutation,
+  useActionQuery,
+} from "@agent-native/core/client/hooks";
+import { useT } from "@agent-native/core/client/i18n";
+import { useLab } from "@agent-native/core/client/labs";
+import {
+  IconArrowUpRight,
+  IconCircleCheck,
+  IconPlus,
+} from "@tabler/icons-react";
+import { useState } from "react";
+import { toast } from "sonner";
+
+import { COMMUNITY_APPS_LAB } from "../shared/labs.js";
+import { ActionQueryError } from "./action-query-error";
+import { AppIcon } from "./app-icon";
+import { AppList, AppListRow } from "./app-list-row";
+import { Badge } from "./ui/badge";
+import { Button } from "./ui/button";
+import { Skeleton } from "./ui/skeleton";
+import { Spinner } from "./ui/spinner";
+
+interface CommunityAppSource {
+  id: string;
+  name: string;
+  description?: string;
+  appId: string;
+  repo: string;
+  ref: string;
+  license: string;
+  provenance: string;
+  templatePath: string;
+  installed: boolean;
+  pending: boolean;
+  installable: boolean;
+  installUnavailableReason?:
+    | "workspace-required"
+    | "app-id-conflict"
+    | "builder-install-unverified";
+}
+
+function pinnedSourceUrl(source: CommunityAppSource): string {
+  return (
+    "https://github.com/" +
+    source.repo +
+    "/tree/" +
+    source.ref +
+    "/" +
+    source.templatePath
+  );
+}
+
+export function CommunityAppsSection() {
+  const t = useT();
+  const enabled = useLab(COMMUNITY_APPS_LAB);
+  const [installingId, setInstallingId] = useState<string | null>(null);
+  const catalogQuery = useActionQuery<CommunityAppSource[]>(
+    "list-curated-community-apps" as never,
+    {},
+    { enabled },
+  );
+  const workspaceAppsQuery = useActionQuery("list-workspace-apps", {
+    includeAgentCards: false,
+    includeArchived: true,
+  });
+  const install = useActionMutation("install-curated-community-app", {
+    onSuccess: (result) => {
+      const mode = (result as { mode?: string } | null)?.mode;
+      const message = (result as { message?: string } | null)?.message;
+      if (mode === "builder") {
+        toast.success(t("dispatch.pages.communityAppsInstallStarted"));
+      } else if (mode === "pending") {
+        toast.info(t("dispatch.pages.communityAppsPending"));
+      } else if (mode === "already-installed") {
+        toast.success(t("dispatch.pages.communityAppsAlreadyInstalled"));
+      } else if (mode === "builder-unavailable" || mode === "app-id-taken") {
+        toast.error(message || t("dispatch.pages.communityAppsInstallFailed"));
+      } else if (mode === "local-agent") {
+        sendToAgentChat({
+          message:
+            (result as { prompt?: string } | null)?.prompt ||
+            t("dispatch.pages.communityAppsLocalRequestReady"),
+          attachments: (
+            result as {
+              attachments?: Array<{
+                type: "file";
+                name: string;
+                contentType: string;
+                text: string;
+              }>;
+            } | null
+          )?.attachments,
+          submit: true,
+          type: "code",
+          newTab: true,
+          reuseEmptyTab: true,
+        });
+        toast.info(t("dispatch.pages.communityAppsLocalRequestReady"));
+      } else {
+        toast.error(t("dispatch.pages.communityAppsInstallFailed"));
+      }
+      setInstallingId(null);
+      void catalogQuery.refetch();
+      void workspaceAppsQuery.refetch();
+    },
+    onError: () => {
+      setInstallingId(null);
+      toast.error(t("dispatch.pages.communityAppsInstallFailed"));
+    },
+  });
+
+  if (!enabled) return null;
+
+  return (
+    <section className="space-y-3 border-t pt-6">
+      <h2 className="text-sm font-semibold text-foreground">
+        {t("dispatch.pages.communityApps")}
+      </h2>
+      {catalogQuery.isError ? (
+        <ActionQueryError
+          error={catalogQuery.error}
+          onRetry={() => void catalogQuery.refetch()}
+        />
+      ) : catalogQuery.isLoading ? (
+        <AppList className="divide-y rounded-xl border">
+          <div className="flex items-center gap-3 px-4 py-3.5">
+            <Skeleton className="size-8 rounded-lg" />
+            <Skeleton className="h-4 w-40" />
+          </div>
+        </AppList>
+      ) : catalogQuery.data?.length ? (
+        <AppList className="divide-y rounded-xl border">
+          {catalogQuery.data.map((source) => (
+            <AppListRow key={source.id} className="border-b-0">
+              <AppIcon id={source.id} name={source.name} size="sm" />
+              <div className="min-w-0 flex-1">
+                <div className="flex min-w-0 flex-wrap items-center gap-2">
+                  <h3 className="truncate text-sm font-semibold text-foreground">
+                    {source.name}
+                  </h3>
+                  {source.installed ? (
+                    <Badge variant="secondary" className="gap-1">
+                      <IconCircleCheck size={13} />
+                      {t("dispatch.pages.communityAppsInstalled")}
+                    </Badge>
+                  ) : source.pending ? (
+                    <Badge variant="secondary">
+                      {t("dispatch.pages.communityAppsPending")}
+                    </Badge>
+                  ) : null}
+                </div>
+                {source.description ? (
+                  <p className="mt-0.5 truncate text-xs text-muted-foreground">
+                    {source.description}
+                  </p>
+                ) : null}
+                <div className="mt-1 flex flex-wrap items-center gap-x-2 text-xs text-muted-foreground">
+                  <span>
+                    {t("dispatch.pages.communityAppsLicense")}: {source.license}
+                  </span>
+                  <a
+                    href={pinnedSourceUrl(source)}
+                    target="_blank"
+                    rel="noreferrer"
+                    className="inline-flex items-center gap-1 underline-offset-4 hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  >
+                    {t("dispatch.pages.communityAppsTemplateSource")}
+                    <IconArrowUpRight size={12} aria-hidden="true" />
+                  </a>
+                </div>
+              </div>
+              {source.installable ? (
+                <Button
+                  type="button"
+                  size="sm"
+                  variant="outline"
+                  disabled={install.isPending}
+                  onClick={() => {
+                    setInstallingId(source.id);
+                    install.mutate({ sourceId: source.id });
+                  }}
+                >
+                  {install.isPending && installingId === source.id ? (
+                    <Spinner className="mr-1.5" />
+                  ) : (
+                    <IconPlus size={14} className="mr-1.5" />
+                  )}
+                  {install.isPending && installingId === source.id
+                    ? t("dispatch.pages.communityAppsInstalling")
+                    : t("dispatch.pages.communityAppsInstall")}
+                </Button>
+              ) : !source.installed &&
+                !source.pending &&
+                source.installUnavailableReason === "workspace-required" ? (
+                <span className="max-w-48 text-right text-xs text-muted-foreground">
+                  {t("dispatch.pages.communityAppsWorkspaceRequired")}
+                </span>
+              ) : !source.installed &&
+                !source.pending &&
+                source.installUnavailableReason === "app-id-conflict" ? (
+                <span className="max-w-48 text-right text-xs text-muted-foreground">
+                  {t("dispatch.pages.communityAppsIdConflict")}
+                </span>
+              ) : !source.installed &&
+                !source.pending &&
+                source.installUnavailableReason ===
+                  "builder-install-unverified" ? (
+                <span className="max-w-48 text-right text-xs text-muted-foreground">
+                  {t("dispatch.pages.communityAppsBuilderInstallUnavailable")}
+                </span>
+              ) : null}
+            </AppListRow>
+          ))}
+        </AppList>
+      ) : (
+        <p className="text-sm text-muted-foreground">
+          {t("dispatch.pages.communityAppsEmpty")}
+        </p>
+      )}
+    </section>
+  );
+}

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(