@agent-native/dispatch 0.8.5 → 0.8.6

package/src/server/lib/mcp-access-store.ts

@@ -0,0 +1,104 @@
+import {
+  getOrgSetting,
+  getUserSetting,
+  putOrgSetting,
+  putUserSetting,
+} from "@agent-native/core/settings";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+
+export const MCP_APP_ACCESS_SETTINGS_KEY = "dispatch-mcp-app-access";
+
+export type DispatchMcpAppAccessMode = "all-apps" | "selected-apps";
+
+export interface DispatchMcpAppAccessSettings {
+  mode: DispatchMcpAppAccessMode;
+  selectedAppIds: string[];
+  updatedAt?: string;
+  updatedBy?: string;
+}
+
+interface AccessScope {
+  kind: "org" | "user";
+  id: string;
+  actor: string;
+}
+
+function uniqueAppIds(values: unknown): string[] {
+  const input = Array.isArray(values) ? values : [];
+  return Array.from(
+    new Set(
+      input
+        .filter((value): value is string => typeof value === "string")
+        .map((value) => value.trim().toLowerCase())
+        .filter(Boolean),
+    ),
+  );
+}
+
+export function normalizeMcpAppAccessSettings(
+  raw: unknown,
+): DispatchMcpAppAccessSettings {
+  const record =
+    raw && typeof raw === "object" && !Array.isArray(raw)
+      ? (raw as Record<string, unknown>)
+      : {};
+  const mode = record.mode === "selected-apps" ? "selected-apps" : "all-apps";
+  return {
+    mode,
+    selectedAppIds: uniqueAppIds(record.selectedAppIds),
+    updatedAt:
+      typeof record.updatedAt === "string" ? record.updatedAt : undefined,
+    updatedBy:
+      typeof record.updatedBy === "string" ? record.updatedBy : undefined,
+  };
+}
+
+function currentAccessScope(): AccessScope {
+  const actor = getRequestUserEmail();
+  if (!actor) throw new Error("no authenticated user");
+  const orgId = getRequestOrgId();
+  if (orgId) return { kind: "org", id: orgId, actor };
+  return { kind: "user", id: actor, actor };
+}
+
+export async function getDispatchMcpAppAccessSettings(): Promise<DispatchMcpAppAccessSettings> {
+  const scope = currentAccessScope();
+  const raw =
+    scope.kind === "org"
+      ? await getOrgSetting(scope.id, MCP_APP_ACCESS_SETTINGS_KEY)
+      : await getUserSetting(scope.id, MCP_APP_ACCESS_SETTINGS_KEY);
+  return normalizeMcpAppAccessSettings(raw);
+}
+
+export async function setDispatchMcpAppAccessSettings(input: {
+  mode: DispatchMcpAppAccessMode;
+  selectedAppIds?: string[];
+}): Promise<DispatchMcpAppAccessSettings> {
+  const scope = currentAccessScope();
+  const next: DispatchMcpAppAccessSettings = {
+    mode: input.mode,
+    selectedAppIds: uniqueAppIds(input.selectedAppIds),
+    updatedAt: new Date().toISOString(),
+    updatedBy: scope.actor,
+  };
+  const value = next as unknown as Record<string, unknown>;
+  if (scope.kind === "org") {
+    await putOrgSetting(scope.id, MCP_APP_ACCESS_SETTINGS_KEY, value);
+  } else {
+    await putUserSetting(scope.id, MCP_APP_ACCESS_SETTINGS_KEY, value);
+  }
+  return next;
+}
+
+export function isAppAllowedByMcpAccess(
+  appId: string,
+  settings: DispatchMcpAppAccessSettings,
+): boolean {
+  const normalized = appId.trim().toLowerCase();
+  if (!normalized) return false;
+  if (settings.mode === "all-apps") return true;
+  return settings.selectedAppIds.includes(normalized);
+}

package/src/server/lib/mcp-gateway.ts

@@ -0,0 +1,333 @@
+import { callAgent, signA2AToken } from "@agent-native/core/a2a";
+import {
+  buildMcpToolName,
+  McpClientManager,
+} from "@agent-native/core/mcp-client";
+import { buildDeepLink } from "@agent-native/core/server";
+import {
+  discoverAgents,
+  type DiscoveredAgent,
+} from "@agent-native/core/server/agent-discovery";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { getOrgA2ASecret, getOrgDomain } from "@agent-native/core/org";
+import {
+  getDispatchMcpAppAccessSettings,
+  isAppAllowedByMcpAccess,
+  type DispatchMcpAppAccessSettings,
+} from "./mcp-access-store.js";
+
+export interface DispatchMcpAccessibleApp {
+  id: string;
+  name: string;
+  description: string;
+  url: string;
+  color: string;
+  granted: boolean;
+}
+
+function normalizeAppId(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+const CONTROL_CHARS = new RegExp("[\\u0000-\\u001f\\u007f]");
+
+function safeAppPath(raw: unknown): string | null {
+  if (typeof raw !== "string" || !raw.trim()) return null;
+  const value = raw.trim();
+  if (CONTROL_CHARS.test(value)) return null;
+  if (!value.startsWith("/")) return null;
+  if (value.startsWith("//") || value.startsWith("/\\")) return null;
+  if (/^\/[a-z][a-z0-9+.-]*:/i.test(value)) return null;
+  return value;
+}
+
+function appendParamsToPath(
+  path: string,
+  params: Record<string, string | number | boolean> | undefined,
+): string {
+  if (!params || Object.keys(params).length === 0) return path;
+  const url = new URL(path, "http://agent-native.invalid");
+  for (const [key, value] of Object.entries(params)) {
+    url.searchParams.set(key, String(value));
+  }
+  return `${url.pathname}${url.search}${url.hash}`;
+}
+
+function appOrigin(app: DispatchMcpAccessibleApp): string {
+  return new URL(app.url).origin;
+}
+
+function appBaseUrl(app: DispatchMcpAccessibleApp): string {
+  return app.url.replace(/\/+$/, "");
+}
+
+function toAccessibleApp(
+  agent: DiscoveredAgent,
+  settings: DispatchMcpAppAccessSettings,
+): DispatchMcpAccessibleApp {
+  return {
+    id: agent.id,
+    name: agent.name,
+    description: agent.description,
+    url: agent.url,
+    color: agent.color,
+    granted: isAppAllowedByMcpAccess(agent.id, settings),
+  };
+}
+
+export async function listDispatchMcpApps(): Promise<{
+  settings: DispatchMcpAppAccessSettings;
+  apps: DispatchMcpAccessibleApp[];
+}> {
+  const [settings, agents] = await Promise.all([
+    getDispatchMcpAppAccessSettings(),
+    discoverAgents("dispatch"),
+  ]);
+  return {
+    settings,
+    apps: agents.map((agent) => toAccessibleApp(agent, settings)),
+  };
+}
+
+export async function listGrantedDispatchMcpApps(): Promise<
+  DispatchMcpAccessibleApp[]
+> {
+  const { apps } = await listDispatchMcpApps();
+  return apps.filter((app) => app.granted);
+}
+
+export async function resolveGrantedDispatchMcpApp(
+  app: string,
+): Promise<DispatchMcpAccessibleApp> {
+  const target = normalizeAppId(app);
+  if (!target) throw new Error("app is required");
+  const { apps } = await listDispatchMcpApps();
+  const match = apps.find(
+    (candidate) =>
+      candidate.id === target || candidate.name.toLowerCase() === target,
+  );
+  if (!match) {
+    throw new Error(
+      `Unknown app "${app}". Call list_apps to see apps available through Dispatch MCP.`,
+    );
+  }
+  if (!match.granted) {
+    throw new Error(
+      `Dispatch MCP access to "${match.id}" is not granted. Open Dispatch > Agents to change MCP app access.`,
+    );
+  }
+  return match;
+}
+
+export async function askGrantedDispatchMcpApp(
+  app: string,
+  message: string,
+): Promise<{ app: string; routedVia: "a2a"; response: string }> {
+  const trimmedMessage = message.trim();
+  if (!trimmedMessage) throw new Error("message is required");
+  const target = await resolveGrantedDispatchMcpApp(app);
+  const userEmail = getRequestUserEmail();
+  if (!userEmail) throw new Error("no authenticated user");
+
+  const orgId = getRequestOrgId();
+  const [orgDomain, orgSecret] = orgId
+    ? await Promise.all([
+        getOrgDomain(orgId).catch(() => null),
+        getOrgA2ASecret(orgId).catch(() => null),
+      ])
+    : [null, null];
+
+  const response = await callAgent(target.url, trimmedMessage, {
+    userEmail,
+    orgDomain: orgDomain ?? undefined,
+    orgSecret: orgSecret ?? undefined,
+    timeoutMs: 5 * 60_000,
+  });
+  return { app: target.id, routedVia: "a2a", response };
+}
+
+export async function openGrantedDispatchMcpApp(input: {
+  app: string;
+  view?: string;
+  path?: string;
+  params?: Record<string, string | number | boolean>;
+  embed?: boolean;
+  chrome?: "full" | "minimal";
+}): Promise<{
+  app: string;
+  view?: string;
+  path?: string;
+  url: string;
+  embed?: boolean;
+  chrome?: "full" | "minimal";
+}> {
+  const view = input.view?.trim() ?? "";
+  const path = safeAppPath(input.path);
+  if (!view && !path) throw new Error("open_app requires view or path");
+  const target = await resolveGrantedDispatchMcpApp(input.app);
+  const relUrl = path
+    ? appendParamsToPath(path, input.params)
+    : buildDeepLink({
+        app: target.id,
+        view,
+        params: input.params,
+      });
+  return {
+    app: target.id,
+    ...(view ? { view } : {}),
+    ...(path ? { path } : {}),
+    url: `${appBaseUrl(target)}${relUrl}`,
+    ...(input.embed === true ? { embed: true } : {}),
+    ...(input.chrome ? { chrome: input.chrome } : {}),
+  };
+}
+
+function parseMcpToolTextResult(result: unknown): Record<string, unknown> {
+  if (result && typeof result === "object") {
+    const structured = (result as any).structuredContent;
+    if (structured && typeof structured === "object") return structured;
+    const parts = Array.isArray((result as any).content)
+      ? ((result as any).content as Array<Record<string, unknown>>)
+      : [];
+    const text = parts.find(
+      (part) => part?.type === "text" && typeof part.text === "string",
+    )?.text;
+    if (typeof text === "string" && text.trim()) {
+      const parsed = JSON.parse(text);
+      if (parsed && typeof parsed === "object") return parsed;
+    }
+  }
+  throw new Error("Target app did not return an embed session.");
+}
+
+async function resolveDispatchEmbedTarget(input: {
+  app?: string;
+  url?: string;
+  path?: string;
+}): Promise<{ app: DispatchMcpAccessibleApp; path: string; url: string }> {
+  const explicitApp = input.app?.trim()
+    ? await resolveGrantedDispatchMcpApp(input.app)
+    : null;
+  if (explicitApp && input.path) {
+    const path = safeAppPath(input.path);
+    if (!path) throw new Error("path must be a safe app-relative route");
+    return {
+      app: explicitApp,
+      path,
+      url: `${appBaseUrl(explicitApp)}${path}`,
+    };
+  }
+
+  if (!input.url) {
+    throw new Error("create_embed_session requires a url or app + path.");
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(input.url);
+  } catch {
+    if (!explicitApp) {
+      throw new Error("Relative embed paths require an app id.");
+    }
+    const path = safeAppPath(input.url);
+    if (!path) throw new Error("url must be a safe app route.");
+    return {
+      app: explicitApp,
+      path,
+      url: `${appBaseUrl(explicitApp)}${path}`,
+    };
+  }
+
+  const apps = explicitApp ? [explicitApp] : await listGrantedDispatchMcpApps();
+  const target = apps.find((app) => parsed.origin === appOrigin(app));
+  if (!target) {
+    throw new Error(
+      "Embed URL must belong to an app granted through Dispatch.",
+    );
+  }
+  const path = safeAppPath(`${parsed.pathname}${parsed.search}${parsed.hash}`);
+  if (!path) throw new Error("Embed URL path is not safe.");
+  return { app: target, path, url: `${appBaseUrl(target)}${path}` };
+}
+
+export async function createGrantedDispatchMcpEmbedSession(input: {
+  app?: string;
+  url?: string;
+  path?: string;
+  chrome?: "full" | "minimal";
+}): Promise<{
+  startUrl: string;
+  targetPath?: string;
+  expiresAt?: number;
+  app: string;
+}> {
+  const userEmail = getRequestUserEmail();
+  if (!userEmail) throw new Error("no authenticated user");
+  const target = await resolveDispatchEmbedTarget(input);
+
+  const orgId = getRequestOrgId();
+  const [orgDomain, orgSecret] = orgId
+    ? await Promise.all([
+        getOrgDomain(orgId).catch(() => null),
+        getOrgA2ASecret(orgId).catch(() => null),
+      ])
+    : [null, null];
+  const token = await signA2AToken(
+    userEmail,
+    orgDomain ?? undefined,
+    orgSecret ?? undefined,
+    {
+      expiresIn: "5m",
+      preferGlobalSecret: !orgSecret,
+    },
+  );
+
+  const serverId = "target";
+  const manager = new McpClientManager({
+    servers: {
+      [serverId]: {
+        type: "http",
+        url: `${appBaseUrl(target.app)}/_agent-native/mcp`,
+        headers: {
+          Authorization: `Bearer ${token}`,
+        },
+      },
+    },
+  });
+  await manager.start();
+  try {
+    const result = await manager.callTool(
+      buildMcpToolName(serverId, "create_embed_session"),
+      {
+        url: target.url,
+        chrome: input.chrome ?? "full",
+      },
+    );
+    const parsed = parseMcpToolTextResult(result) as {
+      startUrl?: string;
+      targetPath?: string;
+      expiresAt?: number;
+    };
+    if (!parsed.startUrl) {
+      throw new Error("Target app did not return an embed start URL.");
+    }
+    const output: {
+      startUrl: string;
+      targetPath?: string;
+      expiresAt?: number;
+      app: string;
+    } = {
+      startUrl: parsed.startUrl,
+      app: target.app.id,
+    };
+    if (parsed.targetPath) output.targetPath = parsed.targetPath;
+    if (typeof parsed.expiresAt === "number")
+      output.expiresAt = parsed.expiresAt;
+    return output;
+  } finally {
+    await manager.stop();
+  }
+}

package/src/server/plugins/agent-chat.ts

@@ -30,6 +30,7 @@ Use the standard workspace primitives:
 - You receive a compact available-apps block with sibling workspace app names and descriptions. Use it to pick the right A2A target, and call list-connected-agents or tool-search only when you need fresh details.
 - When answering whether workspace apps expose agent cards or A2A endpoints, call list-workspace-apps with includeAgentCards=true. If you have not requested that probe, absence of agent-card fields means unchecked, not unavailable.
 - When creating a new workspace app, create a separate app under apps/<app-id> with apps/<app-id>/package.json including a concise generated description, mount it at /<app-id>, use relative /<app-id> links, never hardcode localhost or dev ports, use shadcn/ui with @tabler/icons-react rather than lucide-react, and ensure the React Router client entry preserves APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath(). There is no separate workspace app registry to edit.
+- If the starter template is used, treat it as scaffolding only: the finished app must be branded as the requested app with its own home screen/navigation/package metadata/manifest, and must not leave visible "Starter", "Blank app", or "New app" UI behind.
 - Treat first-party apps such as Mail, Calendar, Analytics, Brain, and Dispatch as existing hosted/connected neighbors available through links and A2A/default connected agents. Do not create wrapper apps, child apps, nested routes, or cloned template copies just to give a new app access to them; build only the genuinely new workflow and delegate cross-app work to those existing apps.
 
 When a user asks for something like a digest, reminder, routing rule, or saved behavior:

package/src/server/plugins/integrations.ts

@@ -23,7 +23,8 @@ When a user asks for something:
 - Exception: if the downstream agent reports a missing model/provider credential, do not name exact env vars, Vault keys, tokens, or secrets. Say the target app needs an LLM connection and recommend connecting Builder/managed LLM for that app; keep bring-your-own provider keys as a secondary option only if the user asks.
 - If the user asks to create, build, make, scaffold, or generate an "agent" from Dispatch chat or by tagging @agent-native in Slack, email, or Telegram, first classify the ask. If it is a simple Dispatch-native behavior like a reminder, digest, monitor, routing rule, saved instruction, or recurring workflow, create or update the recurring job/resource/destination in Dispatch. If it is a robust unique product or teammate that needs its own UI, data model, actions, integrations, or domain workflow, treat it as a new workspace app and call start-workspace-app-creation.
 - If a new-app prompt asks for access to Mail, Calendar, Analytics, Brain, or similar first-party app data/agents, keep using the existing hosted/connected app and A2A path. Do not ask Builder to scaffold those apps as children of the new app unless the user explicitly asks for a customized fork/copy.
-- If the user explicitly asks for a new app or workspace app, call start-workspace-app-creation with their prompt and include a concise generated description when possible. Do not satisfy a new-app request by adding a route, page, component, or file inside apps/starter or another existing app unless the user explicitly asks to modify that existing app. If the request is too vague to classify, ask one concise follow-up. If the action returns mode "builder", reply with the Builder branch URL; Builder is responsible for creating the separate workspace app under apps/<app-id>, mounting it at /<app-id>, ensuring apps/<app-id>/package.json exists with name/displayName and description so Dispatch discovers it, using relative /<app-id> links instead of hardcoded localhost/dev ports, and preserving APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath() in the React Router client entry. The new app lives at the workspace root /<app-id>, NOT under /dispatch/<app-id>, /apps/<app-id>, or any other Dispatch tab — when telling the user where to find it, link to /<app-id> only. There is no separate workspace app registry to edit. If it returns mode "local-agent", tell the user it is ready for the local code agent and include the returned app path/prompt summary. If it returns mode "coming-soon" or "builder-unavailable", explain the missing Builder setup and ask them to connect/configure Builder.
+- If the starter template is used, treat it as scaffolding only: the finished app must be branded as the requested app with its own home screen/navigation/package metadata/manifest, and must not leave visible "Starter", "Blank app", or "New app" UI behind.
+- If the user explicitly asks for a new app or workspace app, call start-workspace-app-creation with their prompt and include a concise generated description by default. Do not satisfy a new-app request by adding a route, page, component, or file inside apps/starter or another existing app unless the user explicitly asks to modify that existing app. If the request is too vague to classify, ask one concise follow-up. If the action returns mode "builder", reply with the Builder branch URL; Builder is responsible for creating the separate workspace app under apps/<app-id>, mounting it at /<app-id>, ensuring apps/<app-id>/package.json exists with name/displayName and description so Dispatch discovers it, using relative /<app-id> links instead of hardcoded localhost/dev ports, and preserving APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath() in the React Router client entry. The new app lives at the workspace root /<app-id>, NOT under /dispatch/<app-id>, /apps/<app-id>, or any other Dispatch tab — when telling the user where to find it, link to /<app-id> only. There is no separate workspace app registry to edit. If it returns mode "local-agent", tell the user it is ready for the local code agent and include the returned app path/prompt summary. If it returns mode "coming-soon" or "builder-unavailable", explain the missing Builder setup and ask them to connect/configure Builder.
 - For digests, reminders, or saved behavior, prefer recurring jobs, resources, or destinations over chat replies.
 - Keep responses concise and operational — messaging platforms have character limits.
 - Use markdown sparingly (bold and lists are fine, avoid complex formatting).