@agent-native/dispatch 0.8.4 → 0.8.6

package/src/actions/index.spec.ts

@@ -5,6 +5,12 @@ import { dispatchActions } from "./index.js";
 describe("dispatch action registry", () => {
   it("keeps workspace resources runtime-inherited instead of exposing sync actions", () => {
     expect(dispatchActions).toHaveProperty("list-workspace-resources-for-app");
+    expect(dispatchActions).toHaveProperty("list-mcp-app-access");
+    expect(dispatchActions).toHaveProperty("set-mcp-app-access");
+    expect(dispatchActions).toHaveProperty("list_apps");
+    expect(dispatchActions).toHaveProperty("ask_app");
+    expect(dispatchActions).toHaveProperty("open_app");
+    expect(dispatchActions).toHaveProperty("create_embed_session");
     expect(dispatchActions).toHaveProperty(
       "get-workspace-resource-effective-context",
     );

package/src/actions/index.ts

@@ -2,6 +2,7 @@ import type { ActionEntry } from "@agent-native/core/server";
 import approveDispatchChange from "./approve-dispatch-change.js";
 import approveVaultRequest from "./approve-vault-request.js";
 import archiveWorkspaceApp from "./archive-workspace-app.js";
+import askApp from "./ask_app.js";
 import createLinkToken from "./create-link-token.js";
 import createPylonTicket from "./create-pylon-ticket.js";
 import createVaultGrant from "./create-vault-grant.js";
@@ -9,6 +10,7 @@ import createVaultSecret from "./create-vault-secret.js";
 import createWorkspaceResourceGrant from "./create-workspace-resource-grant.js";
 import createWorkspaceResource from "./create-workspace-resource.js";
 import createDreamReport from "./create-dream-report.js";
+import createEmbedSession from "./create_embed_session.js";
 import deleteDestination from "./delete-destination.js";
 import deleteVaultSecret from "./delete-vault-secret.js";
 import deleteWorkspaceResource from "./delete-workspace-resource.js";
@@ -36,6 +38,8 @@ import listDreamCandidates from "./list-dream-candidates.js";
 import listDreams from "./list-dreams.js";
 import listIntegrationsCatalog from "./list-integrations-catalog.js";
 import listLinkedIdentities from "./list-linked-identities.js";
+import listMcpAppAccess from "./list-mcp-app-access.js";
+import listApps from "./list_apps.js";
 import listVaultAudit from "./list-vault-audit.js";
 import listVaultGrants from "./list-vault-grants.js";
 import listVaultRequests from "./list-vault-requests.js";
@@ -47,6 +51,7 @@ import listWorkspaceResourceGrants from "./list-workspace-resource-grants.js";
 import listWorkspaceResourcesForApp from "./list-workspace-resources-for-app.js";
 import listWorkspaceResources from "./list-workspace-resources.js";
 import navigate from "./navigate.js";
+import openApp from "./open_app.js";
 import applyDreamProposal from "./apply-dream-proposal.js";
 import previewDreamProposal from "./preview-dream-proposal.js";
 import previewWorkspaceResourceChange from "./preview-workspace-resource-change.js";
@@ -64,6 +69,7 @@ import sendPlatformMessage from "./send-platform-message.js";
 import setAppCreationSettings from "./set-app-creation-settings.js";
 import setDispatchApprovalPolicy from "./set-dispatch-approval-policy.js";
 import setDreamSettings from "./set-dream-settings.js";
+import setMcpAppAccess from "./set-mcp-app-access.js";
 import setVaultAccessSettings from "./set-vault-access-settings.js";
 import startWorkspaceAppCreation from "./start-workspace-app-creation.js";
 import syncVaultToApp from "./sync-vault-to-app.js";
@@ -84,6 +90,7 @@ export const dispatchActions: Record<string, ActionEntry> = {
   "approve-dispatch-change": approveDispatchChange,
   "approve-vault-request": approveVaultRequest,
   "archive-workspace-app": archiveWorkspaceApp,
+  ask_app: askApp,
   "create-link-token": createLinkToken,
   "create-pylon-ticket": createPylonTicket,
   "create-vault-grant": createVaultGrant,
@@ -91,6 +98,7 @@ export const dispatchActions: Record<string, ActionEntry> = {
   "create-workspace-resource-grant": createWorkspaceResourceGrant,
   "create-workspace-resource": createWorkspaceResource,
   "create-dream-report": createDreamReport,
+  create_embed_session: createEmbedSession,
   "delete-destination": deleteDestination,
   "delete-vault-secret": deleteVaultSecret,
   "delete-workspace-resource": deleteWorkspaceResource,
@@ -119,6 +127,8 @@ export const dispatchActions: Record<string, ActionEntry> = {
   "list-dreams": listDreams,
   "list-integrations-catalog": listIntegrationsCatalog,
   "list-linked-identities": listLinkedIdentities,
+  "list-mcp-app-access": listMcpAppAccess,
+  list_apps: listApps,
   "list-vault-audit": listVaultAudit,
   "list-vault-grants": listVaultGrants,
   "list-vault-requests": listVaultRequests,
@@ -130,6 +140,7 @@ export const dispatchActions: Record<string, ActionEntry> = {
   "list-workspace-resources-for-app": listWorkspaceResourcesForApp,
   "list-workspace-resources": listWorkspaceResources,
   navigate: navigate,
+  open_app: openApp,
   "apply-dream-proposal": applyDreamProposal,
   "preview-dream-proposal": previewDreamProposal,
   "preview-workspace-resource-change": previewWorkspaceResourceChange,
@@ -147,6 +158,7 @@ export const dispatchActions: Record<string, ActionEntry> = {
   "set-app-creation-settings": setAppCreationSettings,
   "set-dispatch-approval-policy": setDispatchApprovalPolicy,
   "set-dream-settings": setDreamSettings,
+  "set-mcp-app-access": setMcpAppAccess,
   "set-vault-access-settings": setVaultAccessSettings,
   "start-workspace-app-creation": startWorkspaceAppCreation,
   "sync-vault-to-app": syncVaultToApp,

package/src/actions/list-mcp-app-access.ts

@@ -0,0 +1,26 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { listDispatchMcpApps } from "../server/lib/mcp-gateway.js";
+
+export default defineAction({
+  description:
+    "List the apps exposed through Dispatch's unified MCP gateway and the current app access policy.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async () => {
+    const { settings, apps } = await listDispatchMcpApps();
+    return {
+      mode: settings.mode,
+      selectedAppIds: settings.selectedAppIds,
+      updatedAt: settings.updatedAt,
+      updatedBy: settings.updatedBy,
+      apps,
+      grantedApps: apps.filter((app) => app.granted),
+      counts: {
+        apps: apps.length,
+        granted: apps.filter((app) => app.granted).length,
+      },
+    };
+  },
+});

package/src/actions/list_apps.ts

@@ -0,0 +1,27 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { listGrantedDispatchMcpApps } from "../server/lib/mcp-gateway.js";
+
+export default defineAction({
+  description:
+    "List the apps this Dispatch MCP gateway can route to. The result is filtered by Dispatch's MCP app access policy.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  parallelSafe: true,
+  run: async () => {
+    const apps = await listGrantedDispatchMcpApps();
+    return {
+      workspace: true,
+      gateway: "dispatch",
+      apps: apps.map((app) => ({
+        id: app.id,
+        name: app.name,
+        description: app.description,
+        url: app.url,
+        running: true,
+        source: "dispatch-mcp-grant",
+      })),
+    };
+  },
+});

package/src/actions/open_app.ts

@@ -0,0 +1,61 @@
+import { defineAction, embedApp } from "@agent-native/core";
+import { z } from "zod";
+import { openGrantedDispatchMcpApp } from "../server/lib/mcp-gateway.js";
+
+const deepLinkParam = z.union([z.string(), z.number(), z.boolean()]);
+const openAppSchema = z
+  .object({
+    app: z.string().describe("Granted app id, e.g. mail or calendar."),
+    view: z.string().optional().describe("Target view in the app, e.g. inbox."),
+    path: z
+      .string()
+      .optional()
+      .describe(
+        "Optional same-origin app route to open directly, e.g. /dashboards/q2.",
+      ),
+    params: z
+      .record(z.string(), deepLinkParam)
+      .optional()
+      .describe("Optional record-focus or filter params."),
+    embed: z
+      .boolean()
+      .optional()
+      .describe("Render the app inline in MCP Apps when supported."),
+    chrome: z
+      .enum(["full", "minimal"])
+      .optional()
+      .describe("Embed chrome preference for compatible app routes."),
+  })
+  .refine((input) => input.view?.trim() || input.path?.trim(), {
+    message: "open_app requires either view or path",
+    path: ["view"],
+  });
+
+export default defineAction({
+  description:
+    "Build a deep link or embeddable app route for an app available through Dispatch MCP. No side effects; surface the returned Open link to the user.",
+  schema: openAppSchema,
+  http: { method: "GET" },
+  readOnly: true,
+  parallelSafe: true,
+  run: async (args) => openGrantedDispatchMcpApp(args),
+  link: ({ result }) => {
+    if (!result || typeof result !== "object") return null;
+    const r = result as { url?: string; app?: string; view?: string };
+    if (!r.url) return null;
+    return {
+      url: r.url,
+      label: `Open ${r.app ?? "app"}`,
+      view: r.view,
+    };
+  },
+  mcpApp: {
+    resource: embedApp({
+      title: "Open app",
+      description: "Render the requested granted app route inline.",
+      iframeTitle: "Dispatch MCP app",
+      openLabel: "Open app",
+      frameDomains: ["https:", "http://localhost:*", "http://127.0.0.1:*"],
+    }),
+  },
+});

package/src/actions/set-mcp-app-access.ts

@@ -0,0 +1,59 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { discoverAgents } from "@agent-native/core/server/agent-discovery";
+import { setDispatchMcpAppAccessSettings } from "../server/lib/mcp-access-store.js";
+import { recordAudit } from "../server/lib/dispatch-store.js";
+import listMcpAppAccess from "./list-mcp-app-access.js";
+
+const modeSchema = z.enum(["all-apps", "selected-apps"]);
+
+export default defineAction({
+  description:
+    "Set which apps are available through Dispatch's unified MCP gateway.",
+  schema: z.object({
+    mode: modeSchema.describe(
+      "Use all-apps to expose every discovered app, or selected-apps to allow only selectedAppIds.",
+    ),
+    selectedAppIds: z
+      .array(z.string())
+      .default([])
+      .describe("App IDs to expose when mode is selected-apps."),
+  }),
+  run: async (args) => {
+    const agents = await discoverAgents("dispatch");
+    const knownIds = new Set(agents.map((agent) => agent.id));
+    const selectedAppIds = Array.from(
+      new Set(
+        args.selectedAppIds
+          .map((id) => id.trim().toLowerCase())
+          .filter(Boolean),
+      ),
+    );
+    const unknown = selectedAppIds.filter((id) => !knownIds.has(id));
+    if (unknown.length > 0) {
+      throw new Error(
+        `Unknown app(s): ${unknown.join(", ")}. Use list-mcp-app-access to see available app IDs.`,
+      );
+    }
+    if (args.mode === "selected-apps" && selectedAppIds.length === 0) {
+      throw new Error("selected-apps mode requires at least one app ID.");
+    }
+
+    await setDispatchMcpAppAccessSettings({
+      mode: args.mode,
+      selectedAppIds,
+    });
+    await recordAudit({
+      action: "mcp-access.updated",
+      targetType: "dispatch-mcp-access",
+      targetId: "unified-mcp",
+      summary:
+        args.mode === "all-apps"
+          ? "Allowed Dispatch MCP access to all apps"
+          : `Allowed Dispatch MCP access to ${selectedAppIds.length} selected app(s)`,
+      metadata: { mode: args.mode, selectedAppIds },
+    }).catch(() => {});
+
+    return listMcpAppAccess.run({});
+  },
+});

package/src/actions/start-workspace-app-creation.ts

@@ -5,7 +5,7 @@ import { startWorkspaceAppCreation } from "../server/lib/app-creation-store.js";
 
 export default defineAction({
   description:
-    "Start creating a new workspace app from Dispatch when the request truly needs its own app. In local dev this returns a code-agent prompt; in production it creates a Builder branch when a Builder project is configured. The result must be a separate workspace app under apps/<app-id>, not a new route or file in apps/starter. If the request needs Mail, Calendar, Analytics, Brain, or another first-party app, use the existing hosted/connected app via links or A2A; do not clone, wrap, or nest those templates inside the new app unless the user explicitly asks for a customized copy.",
+    'Start creating a new workspace app from Dispatch when the request truly needs its own app. Callers should include a concise generated description by default; Dispatch generates one from the prompt when omitted. In local dev this returns a code-agent prompt; in production it creates a Builder branch when a Builder project is configured. The result must be a separate workspace app under apps/<app-id>, not a new route or file in apps/starter. If starter is used as the source template, the finished app must be branded as the requested app and must not leave visible "Starter", "Blank app", or "New app" UI behind. If the request needs Mail, Calendar, Analytics, Brain, or another first-party app, use the existing hosted/connected app via links or A2A; do not clone, wrap, or nest those templates inside the new app unless the user explicitly asks for a customized copy.',
   schema: z.object({
     prompt: z.string().min(1).describe("The user's app creation request"),
     appId: z

package/src/actions/view-screen.ts

@@ -74,6 +74,14 @@ export default defineAction({
     if (navigation?.view === "destinations") {
       screen.recentDestinations = overview.recentDestinations;
     }
+    if (navigation?.view === "agents") {
+      const [connectedAgents, mcpAccess] = await Promise.all([
+        runLocalDispatchAction("list-connected-agents", {}),
+        runLocalDispatchAction("list-mcp-app-access", {}),
+      ]);
+      screen.connectedAgents = connectedAgents;
+      screen.mcpAppAccess = mcpAccess;
+    }
     if (
       navigation?.view === "overview" ||
       navigation?.view === "metrics" ||

package/src/components/create-app-popover.tsx

@@ -111,6 +111,7 @@ function buildAppCreationPrompt(input: {
     `Dispatch workspace resources with scope=all are inherited workspace context. Do not copy or sync them into the new app; every workspace app reads them at runtime and may override with app shared or personal resources.`,
     ``,
     `Pick a starter template that fits the user's prompt — analytics, brain, calendar, content, design, dispatch, forms, mail, slides, clips, or starter when none of the others fit.`,
+    `If you use the starter template, treat it as scaffolding only: the finished app must use the requested app's real name, home screen, navigation, package metadata, and manifest, and it must not leave visible "Starter", "Blank app", or "New app" UI behind.`,
     `Use the workspace app layout: create it under apps/${input.appId}, mount it at /${input.appId}, keep it on the shared workspace database/hosting model, and avoid table-name collisions by namespacing any new domain tables to the app.`,
     `Important routing rule: from outside the app, link to /${input.appId}; inside apps/${input.appId}, React Router routes are app-local. Use <Link to="/review"> and navigate("/review"), not "/${input.appId}/review"; APP_BASE_PATH supplies the mounted prefix, and hardcoding it causes doubled URLs like /${input.appId}/${input.appId}/review.`,
     `Prefer useActionQuery/useActionMutation for actions. If you must raw-fetch framework endpoints, wrap them with agentNativePath("/_agent-native/actions/<name>") so mounted apps call the right URL.`,

package/src/routes/pages/agents.tsx

@@ -1,11 +1,190 @@
-import { useActionQuery } from "@agent-native/core/client";
+import { useMemo, useState } from "react";
+import {
+  agentNativePath,
+  useActionMutation,
+  useActionQuery,
+} from "@agent-native/core/client";
 import { AgentsPanel, type ConnectedAgent } from "@/components/agents-panel";
 import { DispatchShell } from "@/components/dispatch-shell";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Switch } from "@/components/ui/switch";
+import { IconCheck, IconCopy, IconPlugConnected } from "@tabler/icons-react";
+import { toast } from "sonner";
 
 export function meta() {
   return [{ title: "Agents — Dispatch" }];
 }
 
+interface McpAccessApp {
+  id: string;
+  name: string;
+  description: string;
+  url: string;
+  color: string;
+  granted: boolean;
+}
+
+type McpAccessMode = "all-apps" | "selected-apps";
+
+interface McpAccessState {
+  mode: McpAccessMode;
+  selectedAppIds: string[];
+}
+
+function dispatchMcpUrl(): string {
+  const path = agentNativePath("/_agent-native/mcp");
+  if (typeof window === "undefined") return path;
+  return new URL(path, window.location.origin).href;
+}
+
+function DispatchMcpAccessPanel() {
+  const { data, isLoading } = useActionQuery("list-mcp-app-access", {});
+  const [optimistic, setOptimistic] = useState<McpAccessState | null>(null);
+  const saveAccess = useActionMutation("set-mcp-app-access", {
+    onSuccess: () => {
+      setOptimistic(null);
+      toast.success("MCP app access updated");
+    },
+    onError: (error) => {
+      setOptimistic(null);
+      toast.error(error.message);
+    },
+  });
+
+  const apps = ((data as { apps?: McpAccessApp[] } | undefined)?.apps ??
+    []) as McpAccessApp[];
+  const access =
+    optimistic ??
+    ({
+      mode: ((data as { mode?: McpAccessMode } | undefined)?.mode ??
+        "all-apps") as McpAccessMode,
+      selectedAppIds:
+        (data as { selectedAppIds?: string[] } | undefined)?.selectedAppIds ??
+        [],
+    } satisfies McpAccessState);
+  const selected = useMemo(
+    () => new Set(access.selectedAppIds),
+    [access.selectedAppIds],
+  );
+  const grantedCount =
+    access.mode === "all-apps" ? apps.length : access.selectedAppIds.length;
+  const mcpUrl = dispatchMcpUrl();
+
+  function persist(next: McpAccessState) {
+    if (next.mode === "selected-apps" && next.selectedAppIds.length === 0) {
+      toast.error("Select at least one app, or expose all apps.");
+      return;
+    }
+    setOptimistic(next);
+    saveAccess.mutate(next);
+  }
+
+  function toggleApp(appId: string) {
+    const next = selected.has(appId)
+      ? access.selectedAppIds.filter((id) => id !== appId)
+      : [...access.selectedAppIds, appId];
+    persist({ mode: "selected-apps", selectedAppIds: next });
+  }
+
+  async function copyUrl() {
+    try {
+      await navigator.clipboard.writeText(mcpUrl);
+      toast.success("MCP URL copied");
+    } catch {
+      toast.error("Could not copy MCP URL");
+    }
+  }
+
+  return (
+    <section className="rounded-2xl border bg-card p-5">
+      <div className="flex flex-col gap-4 lg:flex-row lg:items-start lg:justify-between">
+        <div className="min-w-0">
+          <div className="flex items-center gap-2 text-sm font-medium text-foreground">
+            <IconPlugConnected size={16} />
+            Unified MCP gateway
+          </div>
+          <div className="mt-1 max-w-2xl text-sm text-muted-foreground">
+            Connect external agents to Dispatch once, then route to granted
+            workspace apps through <code>list_apps</code>, <code>ask_app</code>,
+            and <code>open_app</code>.
+          </div>
+        </div>
+        <div className="flex items-center gap-3 rounded-xl border px-3 py-2">
+          <div>
+            <div className="text-xs font-medium text-foreground">
+              {access.mode === "all-apps" ? "All apps" : "Selected apps"}
+            </div>
+            <div className="text-xs text-muted-foreground">
+              {isLoading ? "Loading" : `${grantedCount} granted`}
+            </div>
+          </div>
+          <Switch
+            checked={access.mode === "all-apps"}
+            disabled={saveAccess.isPending || apps.length === 0}
+            onCheckedChange={(checked) =>
+              persist({
+                mode: checked ? "all-apps" : "selected-apps",
+                selectedAppIds: checked
+                  ? access.selectedAppIds
+                  : apps.map((app) => app.id),
+              })
+            }
+            aria-label="Expose all apps through Dispatch MCP"
+          />
+        </div>
+      </div>
+
+      <div className="mt-4 flex flex-col gap-2 sm:flex-row">
+        <Input readOnly value={mcpUrl} className="font-mono text-xs" />
+        <Button type="button" variant="outline" onClick={copyUrl}>
+          <IconCopy size={15} />
+          Copy URL
+        </Button>
+      </div>
+
+      {access.mode === "selected-apps" ? (
+        <div className="mt-4 grid gap-2 sm:grid-cols-2 xl:grid-cols-3">
+          {apps.map((app) => {
+            const isSelected = selected.has(app.id);
+            return (
+              <button
+                key={app.id}
+                type="button"
+                disabled={
+                  saveAccess.isPending &&
+                  optimistic?.selectedAppIds.includes(app.id) !== isSelected
+                }
+                onClick={() => toggleApp(app.id)}
+                className="flex min-h-[76px] items-start gap-3 rounded-xl border bg-muted/20 px-3 py-3 text-left transition hover:bg-muted/40 disabled:cursor-not-allowed disabled:opacity-60"
+                aria-pressed={isSelected}
+              >
+                <span
+                  className="mt-0.5 flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-xs font-bold text-white"
+                  style={{ backgroundColor: app.color }}
+                >
+                  {app.name.charAt(0).toUpperCase()}
+                </span>
+                <span className="min-w-0 flex-1">
+                  <span className="flex items-center gap-2 text-sm font-medium text-foreground">
+                    {app.name}
+                    {isSelected ? (
+                      <IconCheck size={14} className="text-emerald-500" />
+                    ) : null}
+                  </span>
+                  <span className="mt-1 line-clamp-2 block text-xs text-muted-foreground">
+                    {app.description || app.url}
+                  </span>
+                </span>
+              </button>
+            );
+          })}
+        </div>
+      ) : null}
+    </section>
+  );
+}
+
 export default function AgentsRoute() {
   const { data, refetch } = useActionQuery("list-connected-agents", {});
 
@@ -14,10 +193,13 @@ export default function AgentsRoute() {
       title="Agents"
       description="Dispatch can delegate to the built-in app suite over A2A by default. Add extra agents here only if you want to route work to apps outside that built-in set."
     >
-      <AgentsPanel
-        agents={(data || []) as ConnectedAgent[]}
-        onRefresh={refetch}
-      />
+      <div className="space-y-4">
+        <DispatchMcpAccessPanel />
+        <AgentsPanel
+          agents={(data || []) as ConnectedAgent[]}
+          onRefresh={refetch}
+        />
+      </div>
     </DispatchShell>
   );
 }