@agent-native/dispatch 0.0.0-beta-20260819155526

package/src/actions/list-workspace-resources-for-app.ts

@@ -0,0 +1,14 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { listWorkspaceResourcesForApp } from "../server/lib/workspace-resources-store.js";
+
+export default defineAction({
+  description:
+    "List the inherited workspace and explicitly granted resources an app receives, including auto-loaded instructions.",
+  schema: z.object({
+    appId: z.string().describe("Workspace app ID"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => listWorkspaceResourcesForApp(args.appId),
+});

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

@@ -0,0 +1,24 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { listWorkspaceResources } from "../server/lib/workspace-resources-store.js";
+
+export default defineAction({
+  description:
+    "List all workspace-wide resources (skills, instructions, agent profiles, reference resources, and MCP servers) that apps inherit at runtime.",
+  schema: z.object({
+    kind: z
+      .enum([
+        "skill",
+        "instruction",
+        "agent",
+        "agent-file",
+        "knowledge",
+        "mcp-server",
+      ])
+      .optional()
+      .describe("Filter by resource kind"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => listWorkspaceResources(args),
+});

package/src/actions/list_apps.spec.ts

@@ -0,0 +1,52 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  listGrantedApps: vi.fn(),
+}));
+
+vi.mock("../server/lib/mcp-gateway.js", () => ({
+  listGrantedDispatchMcpApps: mocks.listGrantedApps,
+}));
+
+import listApps from "./list_apps.js";
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.listGrantedApps.mockResolvedValue([
+    {
+      id: "slides",
+      name: "Slides",
+      description: "Create presentations",
+      url: "https://slides.example.test",
+    },
+    {
+      id: "analytics",
+      name: "Analytics",
+      description: "Answer data questions",
+      url: "https://analytics.example.test",
+    },
+  ]);
+});
+
+describe("list_apps", () => {
+  it("returns a compact valid JSON message for MCP hosts", async () => {
+    const result = await listApps.run({});
+
+    expect(JSON.parse(result.message)).toEqual({
+      apps: [
+        { id: "slides", name: "Slides" },
+        { id: "analytics", name: "Analytics" },
+      ],
+    });
+    expect(result.apps).toEqual([
+      expect.objectContaining({
+        id: "slides",
+        url: "https://slides.example.test",
+      }),
+      expect.objectContaining({
+        id: "analytics",
+        url: "https://analytics.example.test",
+      }),
+    ]);
+  });
+});

package/src/actions/list_apps.ts

@@ -0,0 +1,36 @@
+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, including "dispatch" itself for Dispatch-owned pages such as extensions. 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();
+    const appSummaries = apps.map((app) => ({
+      id: app.id,
+      name: app.name,
+      description: app.description,
+      url: app.url,
+      running: true,
+      source: "dispatch-mcp-grant",
+    }));
+    return {
+      workspace: true,
+      gateway: "dispatch",
+      apps: appSummaries,
+      // MCP model-visible results are deliberately text-only unless a tool is
+      // app-only or opens an MCP App. Supplying a compact, valid JSON message
+      // keeps large app catalogs machine-readable instead of letting the
+      // generic text limiter cut the full result into invalid JSON.
+      message: JSON.stringify({
+        apps: appSummaries.map(({ id, name }) => ({ id, name })),
+      }),
+    };
+  },
+});

package/src/actions/navigate.ts

@@ -0,0 +1,53 @@
+/**
+ * Navigate the UI to a view.
+ *
+ * Writes a navigate command to application state which the UI reads and auto-deletes.
+ *
+ * Usage:
+ *   pnpm action navigate --view=overview
+ *   pnpm action navigate --view=dreams
+ *   pnpm action navigate --view=<custom-dispatch-extension-id>
+ *   pnpm action navigate --path=/some/route
+ *
+ * Options:
+ *   --view   View name to navigate to
+ *   --path   URL path to navigate to
+ *   --threadId Chat thread ID to open on the chat route
+ */
+
+import { defineAction } from "@agent-native/core";
+import { writeAppState } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+export default defineAction({
+  description:
+    "Navigate the UI to a specific view or path. Use threadId to open a specific chat thread on the chat route. Writes a navigate command to application state which the UI reads and auto-deletes.",
+  schema: z.object({
+    view: z
+      .string()
+      .optional()
+      .describe(
+        "Named dispatch view to navigate to. Built-in views include chat, overview, apps, operations (or monitoring, observability, database), metrics, new-app, vault, integrations, messaging, workspace, agents, connected-agents, destinations, identities, approvals, automations, audit, thread-debug, dreams, and team. Generated Dispatch extension tabs can also use their nav item id.",
+      ),
+    path: z.string().optional().describe("URL path to navigate to"),
+    threadId: z
+      .string()
+      .optional()
+      .describe("Chat thread ID to open on the chat route"),
+  }),
+  http: false,
+  run: async (args) => {
+    const threadId = args.threadId?.trim();
+    if (!args.view && !args.path && !threadId) {
+      return "Error: At least --view, --path, or --threadId is required.";
+    }
+    const nav: Record<string, string> = {};
+    // A thread id without an explicit view implies the chat surface.
+    if (args.view) nav.view = args.view;
+    else if (threadId) nav.view = "chat";
+    if (args.path) nav.path = args.path;
+    if (threadId) nav.threadId = threadId;
+    await writeAppState("navigate", nav);
+    return `Navigating to ${args.view || args.path || `chat thread ${threadId}`}`;
+  },
+});

package/src/actions/open_app.spec.ts

@@ -0,0 +1,106 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  listGrantedDispatchMcpAppOrigins: vi.fn(),
+  openGrantedDispatchMcpApp: vi.fn(),
+}));
+
+vi.mock("../server/lib/mcp-gateway.js", () => ({
+  listGrantedDispatchMcpAppOrigins: mocks.listGrantedDispatchMcpAppOrigins,
+  openGrantedDispatchMcpApp: mocks.openGrantedDispatchMcpApp,
+}));
+
+import openAppAction from "./open_app.js";
+
+describe("open_app MCP App metadata", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("uses exact granted app origins instead of broad HTTPS CSP", async () => {
+    mocks.listGrantedDispatchMcpAppOrigins.mockResolvedValue([
+      "https://dispatch.agent-native.com",
+      "https://mail.agent-native.com",
+      "https://calendar.agent-native.com",
+    ]);
+
+    const cspBuilder = openAppAction.mcpApp?.resource.csp;
+    expect(typeof cspBuilder).toBe("function");
+
+    const csp = await (cspBuilder as any)({
+      actionName: "open_app",
+      appId: "dispatch",
+      requestOrigin: "https://dispatch.agent-native.com",
+    });
+
+    expect(csp.connectDomains).toEqual([
+      "https://esm.sh",
+      "$requestOrigin",
+      "https://mail.agent-native.com",
+      "https://calendar.agent-native.com",
+      "http://localhost:*",
+      "http://127.0.0.1:*",
+    ]);
+    expect(csp.resourceDomains).toEqual(csp.connectDomains);
+    expect(csp.frameDomains).toEqual([
+      "$requestOrigin",
+      "https://mail.agent-native.com",
+      "https://calendar.agent-native.com",
+      "http://localhost:*",
+      "http://127.0.0.1:*",
+    ]);
+    expect(csp.baseUriDomains).toEqual(csp.frameDomains);
+    expect(JSON.stringify(csp)).not.toContain('"https:"');
+  });
+
+  it("keeps exact granted origins when request origin is unavailable", async () => {
+    mocks.listGrantedDispatchMcpAppOrigins.mockResolvedValue([
+      "https://mail.agent-native.com",
+      "https://calendar.agent-native.com",
+    ]);
+
+    const cspBuilder = openAppAction.mcpApp?.resource.csp;
+    const csp = await (cspBuilder as any)({
+      actionName: "open_app",
+      appId: "dispatch",
+    });
+
+    expect(csp.frameDomains).toEqual([
+      "$requestOrigin",
+      "https://mail.agent-native.com",
+      "https://calendar.agent-native.com",
+      "http://localhost:*",
+      "http://127.0.0.1:*",
+    ]);
+  });
+
+  it("promotes embed and chrome from params for hosts that nest open options", async () => {
+    mocks.openGrantedDispatchMcpApp.mockResolvedValue({
+      app: "mail",
+      view: "inbox",
+      url: "https://mail.agent-native.com/inbox",
+      embed: true,
+      chrome: "minimal",
+      embedStartUrl:
+        "https://mail.agent-native.com/_agent-native/embed/start?ticket=test",
+    });
+
+    await openAppAction.run({
+      app: "mail",
+      view: "inbox",
+      params: {
+        embed: true,
+        chrome: "minimal",
+        threadId: "abc",
+      },
+    });
+
+    expect(mocks.openGrantedDispatchMcpApp).toHaveBeenCalledWith({
+      app: "mail",
+      view: "inbox",
+      params: { threadId: "abc" },
+      embed: true,
+      chrome: "minimal",
+    });
+  });
+});

package/src/actions/open_app.ts

@@ -0,0 +1,152 @@
+import {
+  defineAction,
+  embedApp,
+  MCP_APP_REQUEST_ORIGIN_CSP_SOURCE,
+  type ActionMcpAppCsp,
+  type ActionMcpAppCspBuilder,
+} from "@agent-native/core";
+import { z } from "zod";
+
+import {
+  listGrantedDispatchMcpAppOrigins,
+  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. Use "dispatch" for Dispatch-owned pages such as /extensions.',
+      ),
+    view: z.string().optional().describe("Target view in the app, e.g. inbox."),
+    path: z
+      .string()
+      .optional()
+      .describe(
+        'Optional route within the target app, e.g. /adhoc/q2 or /chart?panel=... . Dispatch extension routes such as /extensions/<id>/<slug> belong to app "dispatch".',
+      ),
+    params: z
+      .record(z.string(), deepLinkParam)
+      .optional()
+      .describe("Optional record-focus or filter params."),
+    embed: z
+      .boolean()
+      .optional()
+      .describe(
+        "Render the app or focused route/component 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"],
+  });
+
+type OpenAppArgs = z.infer<typeof openAppSchema>;
+
+function normalizeOpenAppArgs(args: OpenAppArgs): OpenAppArgs {
+  if (!args.params) return args;
+
+  const params = { ...args.params };
+  const embedded = params.embed;
+  const chrome = params.chrome;
+  let changed = false;
+
+  let normalizedEmbed = args.embed;
+  if (normalizedEmbed == null) {
+    if (embedded === true || embedded === "true") {
+      normalizedEmbed = true;
+      changed = true;
+    } else if (embedded === false || embedded === "false") {
+      normalizedEmbed = false;
+      changed = true;
+    }
+  }
+  if (
+    embedded === true ||
+    embedded === false ||
+    embedded === "true" ||
+    embedded === "false"
+  ) {
+    delete params.embed;
+    changed = true;
+  }
+
+  let normalizedChrome = args.chrome;
+  if (normalizedChrome == null && (chrome === "full" || chrome === "minimal")) {
+    normalizedChrome = chrome;
+    changed = true;
+  }
+  if (chrome === "full" || chrome === "minimal") {
+    delete params.chrome;
+    changed = true;
+  }
+
+  if (!changed) return args;
+  return {
+    ...args,
+    params: Object.keys(params).length ? params : undefined,
+    ...(normalizedEmbed == null ? {} : { embed: normalizedEmbed }),
+    ...(normalizedChrome == null ? {} : { chrome: normalizedChrome }),
+  };
+}
+
+const localDevFrameSources = ["http://localhost:*", "http://127.0.0.1:*"];
+
+const dispatchOpenAppCsp: ActionMcpAppCspBuilder = async (
+  ctx,
+): Promise<ActionMcpAppCsp> => {
+  const appOrigins = (await listGrantedDispatchMcpAppOrigins()).filter(
+    (origin) => !ctx.requestOrigin || origin !== ctx.requestOrigin,
+  );
+  const routeSources = [
+    MCP_APP_REQUEST_ORIGIN_CSP_SOURCE,
+    ...appOrigins,
+    ...localDevFrameSources,
+  ];
+  return {
+    connectDomains: ["https://esm.sh", ...routeSources],
+    resourceDomains: ["https://esm.sh", ...routeSources],
+    frameDomains: routeSources,
+    baseUriDomains: routeSources,
+  };
+};
+
+const openAppResource = embedApp({
+  title: "Open app",
+  description: "Render the requested granted app route inline.",
+  iframeTitle: "Dispatch MCP app",
+  openLabel: "Open app",
+});
+
+export default defineAction({
+  description:
+    'Build a deep link or embeddable app route/component route for an app available through Dispatch MCP. Use app "dispatch" for Dispatch extension/tool pages. No side effects; surface the returned Open link to the user.',
+  schema: openAppSchema,
+  http: { method: "GET" },
+  readOnly: true,
+  parallelSafe: true,
+  run: async (args) => openGrantedDispatchMcpApp(normalizeOpenAppArgs(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: {
+    compactCatalog: true,
+    resource: {
+      ...openAppResource,
+      csp: dispatchOpenAppCsp,
+    },
+  },
+});

package/src/actions/preview-dream-proposal.ts

@@ -0,0 +1,15 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { previewDreamProposal } from "../server/lib/dreams-store.js";
+
+export default defineAction({
+  description:
+    "Preview one Dispatch dream proposal before applying it, including target, current content, proposed content, and approval behavior.",
+  schema: z.object({
+    id: z.string().min(1).describe("Dream proposal id."),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async ({ id }) => previewDreamProposal(id),
+});

package/src/actions/preview-workspace-resource-change.ts

@@ -0,0 +1,26 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { previewWorkspaceResourceChange } from "../server/lib/workspace-resources-store.js";
+
+export default defineAction({
+  description:
+    "Preview the impact of creating, updating, or deleting a workspace resource, including All-app reach, overrides, and whether Dispatch approval will be requested.",
+  schema: z.object({
+    operation: z
+      .enum(["create", "update", "delete"])
+      .optional()
+      .describe("Change operation to preview."),
+    resourceId: z.string().optional().describe("Existing resource id."),
+    path: z
+      .string()
+      .optional()
+      .describe("Resource path, such as context/brand.md."),
+    scope: z
+      .enum(["all", "selected"])
+      .optional()
+      .describe("Resulting resource scope after the change."),
+  }),
+  http: { method: "GET" },
+  run: async (args) => previewWorkspaceResourceChange(args),
+});

package/src/actions/provider-api-audit.spec.ts

@@ -0,0 +1,51 @@
+import {
+  buildProviderApiAuditSummary,
+  sanitizeProviderApiAuditPath,
+} from "@agent-native/core/provider-api/actions/provider-api-audit";
+import { describe, expect, it } from "vitest";
+
+describe("provider API audit summaries", () => {
+  it("redacts every query value from relative and absolute request paths", () => {
+    expect(
+      sanitizeProviderApiAuditPath(
+        "/v1/resources?api_key=secret-example&cursor=page-example",
+      ),
+    ).toBe("/v1/resources?api_key=[redacted]&cursor=[redacted]");
+    expect(
+      sanitizeProviderApiAuditPath(
+        "https://api.example.test/download?X-Amz-Signature=signed-example&part=1",
+      ),
+    ).toBe(
+      "https://api.example.test/download?X-Amz-Signature=[redacted]&part=[redacted]",
+    );
+  });
+
+  it("redacts credential-named and opaque path segments", () => {
+    expect(
+      sanitizeProviderApiAuditPath(
+        "/hooks/token/secret-example-value/callback/api_key=another-example",
+      ),
+    ).toBe("/hooks/token/[redacted]/callback/api_key=[redacted]");
+    expect(
+      sanitizeProviderApiAuditPath(
+        "/download/0123456789abcdef0123456789abcdef/file",
+      ),
+    ).toBe("/download/[redacted]/file");
+  });
+
+  it("drops fragments and keeps explicit query arguments out of summaries", () => {
+    const summary = buildProviderApiAuditSummary({
+      method: "get",
+      provider: "example",
+      path: "/records?filter=customer-example#secret-example-fragment",
+      query: { api_key: "query-secret-example" },
+    } as Parameters<typeof buildProviderApiAuditSummary>[0] & {
+      query: unknown;
+    });
+
+    expect(summary).toBe("GET example /records?filter=[redacted]");
+    expect(summary).not.toContain("customer-example");
+    expect(summary).not.toContain("secret-example");
+    expect(summary).not.toContain("query-secret-example");
+  });
+});

package/src/actions/provider-api-catalog.ts

@@ -0,0 +1,14 @@
+import { createProviderApiCatalogAction } from "@agent-native/core/provider-api/actions/provider-api";
+
+import { listProviderApiCatalog } from "../server/lib/provider-api.js";
+
+export default createProviderApiCatalogAction(
+  { listCatalog: listProviderApiCatalog },
+  {
+    description:
+      "List raw HTTP API capabilities for shared workspace integrations, configured providers, and custom registered providers. Use before provider-api-request when grant/setup metadata is not enough and the provider's actual API must be inspected. Returns base URLs, auth style, credential key names, docs/spec URLs, placeholders, and examples; never returns secret values. Custom providers registered via provider-api-register are included.",
+    guidance:
+      "Workspace integrations and grants are not capability limits. When a provider can answer a question through its HTTP API, inspect docs/spec URLs here and call provider-api-request with the exact provider API method/path/query/body instead of adding a rigid one-off action. For broad searches, joins, classification, or absence claims, stage or save the full bounded corpus and reduce it with query-staged-dataset or run-code. Custom providers registered via provider-api-register also appear here.",
+    http: { method: "GET" },
+  },
+);

package/src/actions/provider-api-docs.ts

@@ -0,0 +1,24 @@
+import {
+  createProviderApiDocsAction,
+  createProviderApiDocsSchema,
+} from "@agent-native/core/provider-api/actions/provider-api";
+import { z } from "zod";
+
+import { fetchProviderApiDocs } from "../server/lib/provider-api.js";
+
+export default createProviderApiDocsAction(
+  { fetchDocs: fetchProviderApiDocs },
+  {
+    description:
+      "Inspect provider API docs/spec metadata, or fetch ANY public API documentation page, OpenAPI spec, changelog, or web page. Registered docs/spec URLs from provider-api-catalog are curated starting points, but any public https/http URL is allowed. Use web-search to find documentation URLs first when uncertain, then fetch them here. SSRF guard still applies — private/internal addresses are blocked.",
+    schema: createProviderApiDocsSchema(
+      z
+        .string()
+        .min(1)
+        .describe(
+          "Provider whose API docs/spec to inspect. Can be a built-in provider id or a custom provider id registered via provider-api-register.",
+        ),
+    ),
+    http: { method: "GET" },
+  },
+);