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

package/src/actions/list-workspace-connections.spec.ts

@@ -10,6 +10,9 @@ const mocks = vi.hoisted(() => ({
   hasWorkspaceProviderOAuthCredentials: vi.fn(),
   isProviderApiId: vi.fn(() => false),
   listProviderApiCatalog: vi.fn(() => []),
+  listWorkspaceApps: vi.fn(async () => [
+    { id: "dispatch", name: "Dispatch", status: "ready" },
+  ]),
   listWorkspaceConnectionGrants: vi.fn(),
   listWorkspaceConnectionProviders: vi.fn(),
   listWorkspaceConnectionsForUser: vi.fn(),
@@ -54,9 +57,7 @@ vi.mock("@agent-native/core/workspace-connections", () => ({
 vi.mock("@agent-native/dispatch/actions", () => ({
   dispatchActions: {
     "list-workspace-apps": {
-      run: vi.fn(async () => [
-        { id: "dispatch", name: "Dispatch", status: "ready" },
-      ]),
+      run: mocks.listWorkspaceApps,
     },
   },
 }));
@@ -123,4 +124,14 @@ describe("list-workspace-connections", () => {
     expect(result.providers.map((provider) => provider.id)).toEqual(["github"]);
     expect(result.counts.providers).toBe(1);
   });
+
+  it("preserves workspace app lookup failures instead of returning partial grants", async () => {
+    const error = Object.assign(new Error("Workspace registry unavailable"), {
+      statusCode: 503,
+      errorCode: "workspace_gateway_org_a2a_secret_unavailable",
+    });
+    mocks.listWorkspaceApps.mockRejectedValueOnce(error);
+
+    await expect(action.run({})).rejects.toBe(error);
+  });
 });

package/src/actions/list-workspace-connections.ts

@@ -79,23 +79,19 @@ async function listGrantApps(): Promise<GrantApp[]> {
   const listWorkspaceApps = dispatchActions["list-workspace-apps"];
   if (!listWorkspaceApps) return [{ id: "dispatch", label: "Dispatch" }];
 
-  try {
-    const apps = (await listWorkspaceApps.run({
-      includeAgentCards: false,
-      audience: "all",
-    } as any)) as WorkspaceApp[];
-    const grantApps = apps
-      .filter((app) => !app.archived && app.status !== "pending")
-      .map((app) => ({
-        id: app.id,
-        label: app.name || humanizeAppId(app.id),
-      }));
-    return grantApps.length > 0
-      ? grantApps
-      : [{ id: "dispatch", label: "Dispatch" }];
-  } catch {
-    return [{ id: "dispatch", label: "Dispatch" }];
-  }
+  const apps = (await listWorkspaceApps.run({
+    includeAgentCards: false,
+    audience: "all",
+  } as any)) as WorkspaceApp[];
+  const grantApps = apps
+    .filter((app) => !app.archived && app.status !== "pending")
+    .map((app) => ({
+      id: app.id,
+      label: app.name || humanizeAppId(app.id),
+    }));
+  return grantApps.length > 0
+    ? grantApps
+    : [{ id: "dispatch", label: "Dispatch" }];
 }
 
 export default defineAction({

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

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+
+import action from "./update-workspace-app-metadata.js";
+
+describe("update-workspace-app-metadata action schema", () => {
+  it("validates when-to-use examples when description is explicitly cleared", () => {
+    expect(
+      action.schema.safeParse({
+        appId: "todo",
+        description: null,
+        whenToUse: ["Create a task from a meeting note"],
+      }).success,
+    ).toBe(true);
+  });
+
+  it("validates description when when-to-use examples are explicitly cleared", () => {
+    expect(
+      action.schema.safeParse({
+        appId: "todo",
+        description: "Track team tasks.",
+        whenToUse: null,
+      }).success,
+    ).toBe(true);
+  });
+});

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/action-query-error.spec.tsx

@@ -53,4 +53,24 @@ describe("ActionQueryError", () => {
     });
     expect(onRetry).toHaveBeenCalledOnce();
   });
+
+  it("shows the query and safe HTTP diagnostic without exposing the message", () => {
+    act(() => {
+      root.render(
+        <ActionQueryError
+          error={Object.assign(new Error("secret database detail"), {
+            status: 401,
+            errorCode: "workspace_gateway_rejected",
+          })}
+          queryName="list-workspace-apps"
+          onRetry={() => {}}
+        />,
+      );
+    });
+
+    expect(container.textContent).toContain(
+      "list-workspace-apps · HTTP 401 · workspace_gateway_rejected",
+    );
+    expect(container.textContent).not.toContain("secret database detail");
+  });
 });

package/src/components/action-query-error.tsx

@@ -8,13 +8,48 @@ interface ActionQueryErrorProps {
   error?: unknown;
   onRetry: () => unknown;
   className?: string;
+  queryName?: string;
+}
+
+function actionQueryDiagnostic(
+  error: unknown,
+  queryName: string | undefined,
+): string | null {
+  const parts: string[] = [];
+  if (queryName) parts.push(queryName);
+
+  if (error && typeof error === "object") {
+    const details = error as Record<string, unknown>;
+    const status =
+      typeof details.statusCode === "number"
+        ? details.statusCode
+        : details.status;
+    if (
+      typeof status === "number" &&
+      Number.isInteger(status) &&
+      status >= 100 &&
+      status <= 599
+    ) {
+      parts.push(`HTTP ${status}`);
+    }
+
+    const code = details.errorCode ?? details.code;
+    if (typeof code === "string" && /^[a-zA-Z0-9_.-]{1,80}$/.test(code)) {
+      parts.push(code);
+    }
+  }
+
+  return parts.length > 0 ? parts.join(" · ") : null;
 }
 
 export function ActionQueryError({
+  error,
   onRetry,
   className,
+  queryName,
 }: ActionQueryErrorProps) {
   const t = useT();
+  const diagnostic = actionQueryDiagnostic(error, queryName);
 
   return (
     <Alert variant="destructive" className={className}>
@@ -22,6 +57,11 @@ export function ActionQueryError({
       <AlertTitle>{t("dispatch.pages.dataLoadFailed")}</AlertTitle>
       <AlertDescription className="flex flex-wrap items-center justify-between gap-3">
         <span>{t("dispatch.pages.dataLoadFailedDescription")}</span>
+        {diagnostic ? (
+          <code className="w-full break-all text-xs text-muted-foreground">
+            {diagnostic}
+          </code>
+        ) : null}
         <Button type="button" variant="outline" size="sm" onClick={onRetry}>
           <IconRefresh className="size-4" />
           {t("dispatch.pages.tryAgain")}

package/src/components/chat-home-apps.spec.tsx

@@ -25,7 +25,11 @@ const launcherState = vi.hoisted(() => ({
       },
     ],
     isLoading: false,
-    error: undefined,
+    error: undefined as unknown,
+    errorQueryName: undefined as
+      | "list-workspace-apps"
+      | "list-connected-agents"
+      | undefined,
     openApp: vi.fn(),
     retry: vi.fn(),
   },
@@ -89,6 +93,8 @@ describe("DispatchChatHomeApps", () => {
     ];
     launcherState.value.openApp.mockReset();
     launcherState.value.retry.mockReset();
+    launcherState.value.error = undefined;
+    launcherState.value.errorQueryName = undefined;
     container = document.createElement("div");
     document.body.appendChild(container);
     root = createRoot(container);
@@ -194,4 +200,29 @@ describe("DispatchChatHomeApps", () => {
     expect(container.textContent).toContain("Localized Calendar description");
     expect(container.textContent).not.toContain("Default English text");
   });
+
+  it.each([
+    ["list-workspace-apps", "Workspace apps failed"],
+    ["list-connected-agents", "Connected agents failed"],
+  ] as const)("identifies the failed %s query", async (queryName, message) => {
+    launcherState.value.workspaceApps = [];
+    launcherState.value.error = Object.assign(new Error(message), {
+      statusCode: 503,
+      errorCode: "workspace_gateway_unavailable",
+    });
+    launcherState.value.errorQueryName = queryName;
+
+    await act(async () => {
+      root.render(
+        <MemoryRouter initialEntries={["/chat"]}>
+          <DispatchChatHomeApps />
+        </MemoryRouter>,
+      );
+    });
+
+    expect(container.textContent).toContain(
+      `${queryName} · HTTP 503 · workspace_gateway_unavailable`,
+    );
+    expect(container.textContent).not.toContain(message);
+  });
 });

package/src/components/chat-home-apps.tsx

@@ -48,7 +48,11 @@ export function DispatchChatHomeApps() {
   if (launcher.error && launcher.workspaceApps.length === 0) {
     return (
       <div className="mx-auto w-full max-w-[1000px]">
-        <ActionQueryError error={launcher.error} onRetry={launcher.retry} />
+        <ActionQueryError
+          error={launcher.error}
+          onRetry={launcher.retry}
+          queryName={launcher.errorQueryName}
+        />
       </div>
     );
   }
@@ -61,6 +65,7 @@ export function DispatchChatHomeApps() {
           error={launcher.error}
           onRetry={launcher.retry}
           className="mb-3"
+          queryName={launcher.errorQueryName}
         />
       ) : null}
       <section aria-label={t("dispatch.nav.apps")}>

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/dispatch-control-plane.tsx

@@ -360,6 +360,7 @@ export function DispatchControlPlane() {
         <ActionQueryError
           error={appsQuery.error}
           onRetry={() => void appsQuery.refetch()}
+          queryName="list-workspace-apps"
         />
       ) : (
         <AppsPanel apps={workspaceApps ?? []} isLoading={appsLoading} />

package/src/components/layout/Layout.tsx

@@ -299,6 +299,7 @@ interface DispatchWorkspaceAppLauncher {
   workspaceApps: readonly WorkspaceAppSummary[];
   isLoading: boolean;
   error?: unknown;
+  errorQueryName?: "list-workspace-apps" | "list-connected-agents";
   openApp: (app: ChatFirstAppItem) => void;
   retry: () => void;
 }
@@ -1487,6 +1488,12 @@ function DispatchLayout({
   const chatFirstAppsFailed = chatFirstAppsQuery.isError;
   const chatFirstAppsError =
     chatFirstAppsQuery.error ?? chatFirstConnectedAppsQuery.error;
+  const chatFirstAppsErrorQueryName =
+    chatFirstAppsQuery.error != null
+      ? "list-workspace-apps"
+      : chatFirstConnectedAppsQuery.error != null
+        ? "list-connected-agents"
+        : undefined;
   const chatFirstResolvableApps = useMemo(
     () =>
       mergeChatFirstWorkspaceApps(
@@ -1574,6 +1581,7 @@ function DispatchLayout({
       workspaceApps: chatFirstWorkspaceApps,
       isLoading: chatFirstAppsLoading,
       error: chatFirstAppsError,
+      errorQueryName: chatFirstAppsErrorQueryName,
       openApp: openChatFirstApp,
       retry: () => {
         void chatFirstAppsQuery.refetch();
@@ -1582,6 +1590,7 @@ function DispatchLayout({
     }),
     [
       chatFirstAppsError,
+      chatFirstAppsErrorQueryName,
       chatFirstAppsLoading,
       chatFirstAppsQuery.refetch,
       chatFirstConnectedAppsQuery.refetch,