@jami-studio/dispatch 0.13.14

package/src/actions/list-linked-identities.ts

@@ -0,0 +1,11 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { listIdentityState } from "../server/lib/dispatch-store.js";
+
+export default defineAction({
+  description: "List linked external identities and active link tokens.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => listIdentityState(),
+});

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

@@ -0,0 +1,27 @@
+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-staged-datasets.ts

@@ -0,0 +1,37 @@
+import { defineAction } from "@agent-native/core";
+import { listStagedDatasets } from "@agent-native/core/provider-api/staged-datasets-store";
+import { getCredentialContext } from "@agent-native/core/server/request-context";
+import { z } from "zod";
+
+import { DISPATCH_APP_ID } from "../server/lib/provider-api.js";
+
+export default defineAction({
+  description:
+    "List staged datasets stored by provider-api-request (stageAs) for the current user. Returns dataset ids, names, row counts, columns, and sizes. Use dataset ids with query-staged-dataset to aggregate, or with delete-staged-dataset to free scratch storage.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async () => {
+    const ctx = getCredentialContext();
+    if (!ctx) {
+      throw new Error("No authenticated context for list-staged-datasets.");
+    }
+
+    const datasets = await listStagedDatasets({
+      appId: DISPATCH_APP_ID,
+      ownerEmail: ctx.userEmail,
+    });
+
+    return {
+      datasets: datasets.map((d) => ({
+        id: d.id,
+        name: d.name,
+        rowCount: d.rowCount,
+        columns: d.columns,
+        byteSize: d.byteSize,
+        updatedAt: new Date(d.updatedAt).toISOString(),
+      })),
+      total: datasets.length,
+    };
+  },
+});

package/src/actions/list-vault-audit.ts

@@ -0,0 +1,17 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { listVaultAudit } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "View the vault audit log — secret access, grants, syncs, and requests.",
+  schema: z.object({
+    limit: z.coerce
+      .number()
+      .optional()
+      .describe("Max entries to return (default 50)"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => listVaultAudit(args.limit),
+});

package/src/actions/list-vault-grants.ts

@@ -0,0 +1,15 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { listGrants } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "List explicit vault grants used by manual vault access mode. Optionally filter by app or secret.",
+  schema: z.object({
+    appId: z.string().optional().describe("Filter by app ID"),
+    secretId: z.string().optional().describe("Filter by secret ID"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => listGrants(args),
+});

package/src/actions/list-vault-requests.ts

@@ -0,0 +1,17 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { listRequests } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "List vault secret requests — pending, approved, and denied. Admins see all; members see their own.",
+  schema: z.object({
+    status: z
+      .enum(["pending", "approved", "denied"])
+      .optional()
+      .describe("Filter by status"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => listRequests(args),
+});

package/src/actions/list-vault-secret-options.ts

@@ -0,0 +1,21 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { listSecrets } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "List vault secrets as safe picker options for creating a new app. Does not include secret values.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => {
+    const secrets = await listSecrets();
+    return secrets.map((secret) => ({
+      id: secret.id,
+      name: secret.name,
+      credentialKey: secret.credentialKey,
+      provider: secret.provider,
+      description: secret.description,
+    }));
+  },
+});

package/src/actions/list-vault-secrets.ts

@@ -0,0 +1,27 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { listSecrets } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "List all secrets stored in the workspace vault. Includes raw values so the UI mask/unmask toggle works — masking is a UI concern, not a data concern. Agent responses should still mask values when echoing them to users.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => {
+    const secrets = await listSecrets();
+    return secrets.map((s) => ({
+      id: s.id,
+      name: s.name,
+      credentialKey: s.credentialKey,
+      // Included so the vault UI's eye-icon toggle can reveal the stored
+      // value. Without this the "unmask" click shows an empty string.
+      value: s.value,
+      provider: s.provider,
+      description: s.description,
+      createdBy: s.createdBy,
+      createdAt: s.createdAt,
+      updatedAt: s.updatedAt,
+    }));
+  },
+});

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

@@ -0,0 +1,30 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { listWorkspaceApps } from "../server/lib/app-creation-store.js";
+
+const httpBoolean = z.preprocess((value) => {
+  if (typeof value !== "string") return value;
+  const normalized = value.trim().toLowerCase();
+  if (["true", "1", "yes", "on"].includes(normalized)) return true;
+  if (["false", "0", "no", "off"].includes(normalized)) return false;
+  return value;
+}, z.boolean());
+
+export default defineAction({
+  description:
+    "List apps installed in this workspace, including mounted paths, absolute URLs, audience (internal/public), page route access overrides, and agent-card/A2A metadata for ready apps by default. UI polling callers can pass includeAgentCards=false to skip network probes.",
+  schema: z.object({
+    includeAgentCards: httpBoolean
+      .default(true)
+      .describe(
+        "Fetch each ready app's /.well-known/agent-card.json with a short non-throwing timeout and include agentCardUrl, agentCardReachable, a2aEndpointUrl, agentName, and agentSkillsCount. Defaults to true for agent calls; UI polling should pass false. Pending Builder apps are not probed.",
+      ),
+    audience: z
+      .enum(["all", "internal", "public"])
+      .default("all")
+      .describe("Filter by workspace app audience."),
+  }),
+  http: { method: "GET" },
+  run: async (input) => listWorkspaceApps(input),
+});

package/src/actions/list-workspace-resource-grants.ts

@@ -0,0 +1,15 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { listResourceGrants } from "../server/lib/workspace-resources-store.js";
+
+export default defineAction({
+  description:
+    "List workspace resource grants — which apps have access to selected shared skills, instructions, agents, knowledge packs, and MCP servers.",
+  schema: z.object({
+    resourceId: z.string().optional().describe("Filter by resource ID"),
+    appId: z.string().optional().describe("Filter by app ID"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => listResourceGrants(args),
+});

package/src/actions/list-workspace-resource-options.ts

@@ -0,0 +1,17 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { listWorkspaceResourceOptions } from "../server/lib/workspace-resources-store.js";
+
+export default defineAction({
+  description:
+    "List lightweight workspace resource options for selectors, without returning full content.",
+  schema: z.object({
+    kind: z
+      .enum(["skill", "instruction", "agent", "knowledge", "mcp-server"])
+      .optional()
+      .describe("Filter by resource kind"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => listWorkspaceResourceOptions(args),
+});

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,17 @@
+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", "knowledge", "mcp-server"])
+      .optional()
+      .describe("Filter by resource kind"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => listWorkspaceResources(args),
+});

package/src/actions/list_apps.ts

@@ -0,0 +1,28 @@
+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();
+    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/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, metrics, new-app, vault, integrations, messaging, workspace, 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.jami.studio",
+      "https://mail.jami.studio",
+      "https://calendar.jami.studio",
+    ]);
+
+    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.jami.studio",
+    });
+
+    expect(csp.connectDomains).toEqual([
+      "https://esm.sh",
+      "$requestOrigin",
+      "https://mail.jami.studio",
+      "https://calendar.jami.studio",
+      "http://localhost:*",
+      "http://127.0.0.1:*",
+    ]);
+    expect(csp.resourceDomains).toEqual(csp.connectDomains);
+    expect(csp.frameDomains).toEqual([
+      "$requestOrigin",
+      "https://mail.jami.studio",
+      "https://calendar.jami.studio",
+      "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.jami.studio",
+      "https://calendar.jami.studio",
+    ]);
+
+    const cspBuilder = openAppAction.mcpApp?.resource.csp;
+    const csp = await (cspBuilder as any)({
+      actionName: "open_app",
+      appId: "dispatch",
+    });
+
+    expect(csp.frameDomains).toEqual([
+      "$requestOrigin",
+      "https://mail.jami.studio",
+      "https://calendar.jami.studio",
+      "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.jami.studio/inbox",
+      embed: true,
+      chrome: "minimal",
+      embedStartUrl:
+        "https://mail.jami.studio/_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),
+});