@agent-native/dispatch 0.1.1

package/src/actions/list-connected-agents.ts

@@ -0,0 +1,103 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import {
+  discoverAgents,
+  getBuiltinAgents,
+  shouldIncludeRemoteAgentManifest,
+} from "@agent-native/core/server/agent-discovery";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import {
+  resourceGet,
+  resourceListAccessible,
+  SHARED_OWNER,
+} from "@agent-native/core/resources/store";
+import {
+  REMOTE_AGENT_RESOURCE_PREFIXES,
+  parseRemoteAgentManifest,
+} from "@agent-native/core/resources/metadata";
+
+export default defineAction({
+  description:
+    "List agents available to dispatch for A2A delegation, including built-in apps and connected remote agents.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => {
+    const { hiddenAgentIds = [] } = await import("../server/index.js").then(
+      (m) => m.getDispatchConfig(),
+    );
+    const discovered = await discoverAgents("dispatch");
+    const builtinIds = new Set(
+      getBuiltinAgents("dispatch").map((agent) => agent.id),
+    );
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("no authenticated user");
+    const resources: Array<{ id: string; path: string; owner: string }> = [];
+    for (const prefix of [...REMOTE_AGENT_RESOURCE_PREFIXES].reverse()) {
+      resources.push(...(await resourceListAccessible(ownerEmail, prefix)));
+    }
+    const customById = new Map<
+      string,
+      {
+        resourceId: string;
+        path: string;
+        scope: "shared" | "personal";
+        name: string;
+        description: string;
+        url: string;
+        color: string;
+      }
+    >();
+
+    // Only treat a resource as a "custom" agent if its id is not a builtin.
+    // Built-in agents may also be seeded as shared resources so the agent-chat
+    // plugin can overlay them — those should still be reported as builtin.
+    for (const resource of resources) {
+      if (!resource.path.endsWith(".json")) continue;
+      const full = await resourceGet(resource.id);
+      if (!full) continue;
+      const manifest = parseRemoteAgentManifest(full.content, resource.path);
+      if (!manifest) continue;
+      if (!shouldIncludeRemoteAgentManifest(manifest, "dispatch")) continue;
+      if (builtinIds.has(manifest.id)) continue;
+      customById.set(manifest.id, {
+        resourceId: resource.id,
+        path: resource.path,
+        scope: resource.owner === SHARED_OWNER ? "shared" : "personal",
+        name: manifest.name,
+        description: manifest.description || "",
+        url: manifest.url,
+        color: manifest.color || "#6B7280",
+      });
+    }
+
+    const connected = discovered.map((agent) => {
+      const custom = customById.get(agent.id);
+      const isBuiltin = builtinIds.has(agent.id);
+      return {
+        ...agent,
+        source: isBuiltin ? "builtin" : custom ? "custom" : "workspace",
+        resourceId: custom?.resourceId,
+        path: custom?.path,
+        scope: custom?.scope,
+      };
+    });
+
+    const discoveredIds = new Set(connected.map((agent) => agent.id));
+    for (const [id, custom] of customById) {
+      if (discoveredIds.has(id)) continue;
+      connected.push({
+        id,
+        name: custom.name,
+        description: custom.description,
+        url: custom.url,
+        color: custom.color,
+        source: "custom",
+        resourceId: custom.resourceId,
+        path: custom.path,
+        scope: custom.scope,
+      });
+    }
+
+    return connected.filter((a) => !hiddenAgentIds.includes(a.id));
+  },
+});

package/src/actions/list-destinations.ts

@@ -0,0 +1,10 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { listDestinations } from "../server/lib/dispatch-store.js";
+
+export default defineAction({
+  description: "List saved Slack and Telegram destinations for the dispatch.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => listDestinations(),
+});

package/src/actions/list-dispatch-approvals.ts

@@ -0,0 +1,10 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { listApprovalRequests } from "../server/lib/dispatch-store.js";
+
+export default defineAction({
+  description: "List pending and historical dispatch approval requests.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => listApprovalRequests(),
+});

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

@@ -0,0 +1,12 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { listAuditEvents } from "../server/lib/dispatch-store.js";
+
+export default defineAction({
+  description: "List recent dispatch audit events.",
+  schema: z.object({
+    limit: z.coerce.number().int().min(1).max(200).optional(),
+  }),
+  http: { method: "GET" },
+  run: async ({ limit }) => listAuditEvents(limit || 50),
+});

package/src/actions/list-dispatch-overview.ts

@@ -0,0 +1,18 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { listOverview } from "../server/lib/dispatch-store.js";
+import { listVaultOverview } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "Get the dispatch overview metrics, recent activity, approval settings, and vault health.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => {
+    const [overview, vault] = await Promise.all([
+      listOverview(),
+      listVaultOverview(),
+    ]);
+    return { ...overview, vault };
+  },
+});

package/src/actions/list-integrations-catalog.ts

@@ -0,0 +1,11 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { listIntegrationsCatalog } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "List all workspace apps and their credential/integration requirements. Shows which credentials are configured, which are granted from the vault, and which are missing.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => listIntegrationsCatalog(),
+});

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

@@ -0,0 +1,10 @@
+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-vault-audit.ts

@@ -0,0 +1,16 @@
+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,14 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { listGrants } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "List vault grants — which apps have access to which secrets. 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,16 @@
+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,20 @@
+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,26 @@
+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,25 @@
+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, 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.",
+      ),
+  }),
+  http: { method: "GET" },
+  run: async (input) => listWorkspaceApps(input),
+});

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

@@ -0,0 +1,14 @@
+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 which shared skills, instructions, and agents.",
+  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-resources.ts

@@ -0,0 +1,16 @@
+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, agents) that can be shared across apps.",
+  schema: z.object({
+    kind: z
+      .enum(["skill", "instruction", "agent"])
+      .optional()
+      .describe("Filter by resource kind"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => listWorkspaceResources(args),
+});

package/src/actions/navigate.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 --path=/some/route
+ *
+ * Options:
+ *   --view   View name to navigate to
+ *   --path   URL path to navigate to
+ */
+
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { writeAppState } from "@agent-native/core/application-state";
+
+export default defineAction({
+  description:
+    "Navigate the UI to a specific view or path. Writes a navigate command to application state which the UI reads and auto-deletes.",
+  schema: z.object({
+    view: z
+      .enum([
+        "overview",
+        "apps",
+        "new-app",
+        "vault",
+        "integrations",
+        "messaging",
+        "workspace",
+        "agents",
+        "destinations",
+        "routes",
+        "identities",
+        "approvals",
+        "audit",
+        "team",
+      ])
+      .optional()
+      .describe("Named dispatch view to navigate to"),
+    path: z.string().optional().describe("URL path to navigate to"),
+  }),
+  http: false,
+  run: async (args) => {
+    if (!args.view && !args.path) {
+      return "Error: At least --view or --path is required.";
+    }
+    const nav: Record<string, string> = {};
+    if (args.view) nav.view = args.view;
+    if (args.path) nav.path = args.path;
+    await writeAppState("navigate", nav);
+    return `Navigating to ${args.view || args.path}`;
+  },
+});

package/src/actions/reject-dispatch-change.ts

@@ -0,0 +1,12 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { rejectRequest } from "../server/lib/dispatch-store.js";
+
+export default defineAction({
+  description: "Reject a pending dispatch change request.",
+  schema: z.object({
+    id: z.string().describe("Approval request id"),
+    reason: z.string().optional().describe("Optional rejection reason"),
+  }),
+  run: async ({ id, reason }) => rejectRequest(id, reason),
+});

package/src/actions/request-vault-secret.ts

@@ -0,0 +1,16 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { createRequest } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "Request access to a credential for an app. Non-admins use this to ask workspace admins to provision a secret.",
+  schema: z.object({
+    credentialKey: z
+      .string()
+      .describe("Environment variable name needed, e.g. GOOGLE_CLIENT_ID"),
+    appId: z.string().describe("App ID that needs the credential"),
+    reason: z.string().optional().describe("Why this credential is needed"),
+  }),
+  run: async (args) => createRequest(args),
+});

package/src/actions/revoke-vault-grant.ts

@@ -0,0 +1,11 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { revokeGrant } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description: "Revoke an app's access to a vault secret. Admin only.",
+  schema: z.object({
+    grantId: z.string().describe("Grant ID to revoke"),
+  }),
+  run: async (args) => revokeGrant(args.grantId),
+});

package/src/actions/revoke-workspace-resource-grant.ts

@@ -0,0 +1,15 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import {
+  requireWorkspaceResourceCtx,
+  revokeResourceGrant,
+} from "../server/lib/workspace-resources-store.js";
+
+export default defineAction({
+  description: "Revoke an app's access to a workspace resource. Admin only.",
+  schema: z.object({
+    grantId: z.string().describe("Grant ID to revoke"),
+  }),
+  run: async (args) =>
+    revokeResourceGrant(args.grantId, requireWorkspaceResourceCtx()),
+});

package/src/actions/send-platform-message.ts

@@ -0,0 +1,96 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import {
+  slackAdapter,
+  telegramAdapter,
+  emailAdapter,
+} from "@agent-native/core/server";
+import {
+  getDestinationById,
+  recordAudit,
+} from "../server/lib/dispatch-store.js";
+
+function getAdapter(platform: "slack" | "telegram" | "email") {
+  if (platform === "email") return emailAdapter();
+  return platform === "slack" ? slackAdapter() : telegramAdapter();
+}
+
+function assertOutboundConfigured(platform: "slack" | "telegram" | "email") {
+  if (platform === "slack" && !process.env.SLACK_BOT_TOKEN) {
+    throw new Error("Slack outbound messaging is not configured");
+  }
+  if (platform === "telegram" && !process.env.TELEGRAM_BOT_TOKEN) {
+    throw new Error("Telegram outbound messaging is not configured");
+  }
+  if (platform === "email") {
+    const hasProvider = !!(
+      process.env.RESEND_API_KEY || process.env.SENDGRID_API_KEY
+    );
+    if (!process.env.EMAIL_AGENT_ADDRESS || !hasProvider) {
+      throw new Error("Email outbound messaging is not configured");
+    }
+  }
+}
+
+export default defineAction({
+  description:
+    "Send a proactive message to a saved Slack, Telegram, or email destination.",
+  schema: z.object({
+    platform: z.enum(["slack", "telegram", "email"]).optional(),
+    destinationId: z.string().optional().describe("Saved destination id"),
+    destination: z.string().optional().describe("Raw platform destination id"),
+    threadRef: z.string().optional().describe("Optional thread reference"),
+    text: z.string().describe("Message to send"),
+  }),
+  run: async ({ platform, destinationId, destination, threadRef, text }) => {
+    const saved = destinationId
+      ? await getDestinationById(destinationId)
+      : null;
+    const resolvedPlatform = (saved?.platform || platform) as
+      | "slack"
+      | "telegram"
+      | "email"
+      | undefined;
+    const resolvedDestination = saved?.destination || destination;
+    const resolvedThreadRef = saved?.threadRef || threadRef || null;
+
+    if (!resolvedPlatform || !resolvedDestination) {
+      throw new Error("A platform and destination are required");
+    }
+
+    assertOutboundConfigured(resolvedPlatform);
+
+    const adapter = getAdapter(resolvedPlatform);
+    if (!adapter.sendMessageToTarget) {
+      throw new Error(
+        `Platform ${resolvedPlatform} does not support proactive outbound messaging`,
+      );
+    }
+
+    await adapter.sendMessageToTarget(adapter.formatAgentResponse(text), {
+      destination: resolvedDestination,
+      threadRef: resolvedThreadRef,
+      label: saved?.name || undefined,
+    });
+
+    await recordAudit({
+      action: "message.sent",
+      targetType: "destination",
+      targetId: destinationId || resolvedDestination,
+      summary: `Sent proactive ${resolvedPlatform} message${saved?.name ? ` to ${saved.name}` : ""}`,
+      metadata: {
+        platform: resolvedPlatform,
+        destination: resolvedDestination,
+        threadRef: resolvedThreadRef,
+        text,
+      },
+    });
+
+    return {
+      ok: true,
+      platform: resolvedPlatform,
+      destination: resolvedDestination,
+      threadRef: resolvedThreadRef,
+    };
+  },
+});

package/src/actions/set-app-creation-settings.ts

@@ -0,0 +1,19 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { setAppCreationSettings } from "../server/lib/app-creation-store.js";
+
+export default defineAction({
+  description:
+    "Set Dispatch settings for creating new workspace apps. Does not write env vars or files.",
+  schema: z.object({
+    builderProjectId: z
+      .string()
+      .trim()
+      .min(1)
+      .max(128)
+      .optional()
+      .nullable()
+      .describe("Default Builder project ID to use for app creation branches"),
+  }),
+  run: async (args) => setAppCreationSettings(args),
+});

package/src/actions/set-dispatch-approval-policy.ts

@@ -0,0 +1,24 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import {
+  getApprovalPolicy,
+  setApprovalPolicy,
+} from "../server/lib/dispatch-store.js";
+
+export default defineAction({
+  description: "Enable or disable dispatch approval flow for durable changes.",
+  schema: z.object({
+    enabled: z.boolean(),
+    approverEmails: z.array(z.string().email()).default([]),
+  }),
+  run: async ({ enabled, approverEmails }) => {
+    const current = await getApprovalPolicy();
+    if (
+      current.enabled === enabled &&
+      JSON.stringify(current.approverEmails) === JSON.stringify(approverEmails)
+    ) {
+      return current;
+    }
+    return setApprovalPolicy({ enabled, approverEmails });
+  },
+});

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

@@ -0,0 +1,33 @@
+import { defineAction } from "@agent-native/core";
+import { getWorkspaceAppIdValidationError } from "@agent-native/core/shared";
+import { z } from "zod";
+import { startWorkspaceAppCreation } from "../server/lib/app-creation-store.js";
+
+export default defineAction({
+  description:
+    "Start creating a new workspace app from Dispatch. In local dev this returns a code-agent prompt; in production it creates a Builder branch when a Builder project is configured.",
+  schema: z.object({
+    prompt: z.string().min(1).describe("The user's app creation request"),
+    appId: z
+      .string()
+      .max(64)
+      .refine((appId) => !getWorkspaceAppIdValidationError(appId), {
+        message:
+          "Use a non-reserved app id with lowercase letters, numbers, and hyphens.",
+      })
+      .optional()
+      .nullable()
+      .describe("Desired workspace app id/path"),
+    template: z
+      .string()
+      .optional()
+      .nullable()
+      .describe("Template to start from"),
+    secretIds: z
+      .array(z.string())
+      .max(100)
+      .optional()
+      .describe("Dispatch vault secret IDs to grant to the app"),
+  }),
+  run: async (args) => startWorkspaceAppCreation(args),
+});

package/src/actions/sync-vault-to-app.ts

@@ -0,0 +1,14 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { syncGrantsToApp } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "Push all granted secrets to an app by calling its env-vars endpoint. Returns the list of synced credential keys.",
+  schema: z.object({
+    appId: z
+      .string()
+      .describe("App ID to sync secrets to, e.g. mail, calendar, analytics"),
+  }),
+  run: async (args) => syncGrantsToApp(args.appId),
+});

package/src/actions/sync-workspace-resources-to-all.ts

@@ -0,0 +1,10 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { syncResourcesToAllApps } from "../server/lib/workspace-resources-store.js";
+
+export default defineAction({
+  description:
+    "Push workspace resources to all discovered apps. Scope=all resources go everywhere; scope=selected only go to apps with grants.",
+  schema: z.object({}),
+  run: async () => syncResourcesToAllApps(),
+});