@agent-native/dispatch 0.0.0-beta-20260819155526

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

@@ -0,0 +1,129 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  getInstallation: vi.fn(),
+  resolveTokenBundle: vi.fn(),
+  resolveSecret: vi.fn(),
+  sendMessageToTarget: vi.fn(),
+  getDestinationById: vi.fn(),
+  slackAdapter: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/integrations", () => ({
+  listIntegrationInstallations: mocks.getInstallation,
+  resolveIntegrationTokenBundle: mocks.resolveTokenBundle,
+}));
+
+vi.mock("@agent-native/core/server", () => ({
+  getRequestUserEmail: () => "member@example.com",
+  getRequestOrgId: () => "org-a",
+  resolveSecret: mocks.resolveSecret,
+  isEmailConfigured: vi.fn(),
+  slackAdapter: mocks.slackAdapter,
+  telegramAdapter: vi.fn(),
+  emailAdapter: vi.fn(),
+}));
+
+vi.mock("../server/lib/dispatch-store.js", () => ({
+  getDestinationById: mocks.getDestinationById,
+}));
+
+const action = (await import("./send-platform-message.js")).default;
+
+describe("send-platform-message tenant scoping", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.getDestinationById.mockResolvedValue(null);
+    mocks.resolveSecret.mockResolvedValue(null);
+    mocks.slackAdapter.mockImplementation(
+      (options: { resolveBotToken: () => Promise<string | undefined> }) => ({
+        formatAgentResponse: (text: string) => ({
+          text,
+          platformContext: {},
+        }),
+        sendMessageToTarget: async (...args: unknown[]) => {
+          expect(await options.resolveBotToken()).toBe("own-managed-token");
+          return mocks.sendMessageToTarget(...args);
+        },
+      }),
+    );
+  });
+
+  it("resolves and uses only the caller org's Slack installation", async () => {
+    mocks.getInstallation.mockResolvedValue([
+      {
+        id: "installation-a",
+        installationKey: "team:T1:app:A1",
+        teamId: "T1",
+        enterpriseId: null,
+      },
+    ]);
+    mocks.resolveTokenBundle.mockResolvedValue({
+      accessToken: "own-managed-token",
+    });
+
+    await action.run(
+      {
+        platform: "slack",
+        destination: "C1",
+        tenantId: "T1",
+        text: "hello",
+      },
+      {} as never,
+    );
+
+    expect(mocks.getInstallation).toHaveBeenCalledWith(
+      {
+        userEmail: "member@example.com",
+        orgId: "org-a",
+      },
+      "slack",
+    );
+    expect(mocks.resolveTokenBundle).toHaveBeenCalledWith(
+      "slack",
+      "team:T1:app:A1",
+    );
+    expect(mocks.sendMessageToTarget).toHaveBeenCalledOnce();
+  });
+
+  it("does not use another org's managed installation", async () => {
+    mocks.getInstallation.mockResolvedValue([]);
+
+    await expect(
+      action.run(
+        {
+          platform: "slack",
+          destination: "C1",
+          tenantId: "T-other",
+          text: "hello",
+        },
+        {} as never,
+      ),
+    ).rejects.toThrow("That Slack workspace is not connected");
+
+    expect(mocks.resolveTokenBundle).not.toHaveBeenCalled();
+    expect(mocks.slackAdapter).not.toHaveBeenCalled();
+    expect(mocks.sendMessageToTarget).not.toHaveBeenCalled();
+  });
+
+  it("does not use the deployment token for an unconnected workspace", async () => {
+    mocks.getInstallation.mockResolvedValue([]);
+    mocks.resolveSecret.mockResolvedValue("fusion-token");
+
+    await expect(
+      action.run(
+        {
+          platform: "slack",
+          destination: "C1",
+          tenantId: "T-agent-native",
+          text: "hello",
+        },
+        {} as never,
+      ),
+    ).rejects.toThrow("That Slack workspace is not connected");
+
+    expect(mocks.resolveSecret).not.toHaveBeenCalledWith("SLACK_BOT_TOKEN");
+    expect(mocks.slackAdapter).not.toHaveBeenCalled();
+    expect(mocks.sendMessageToTarget).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,150 @@
+import { defineAction } from "@agent-native/core";
+import {
+  listIntegrationInstallations,
+  resolveIntegrationTokenBundle,
+} from "@agent-native/core/integrations";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+  slackAdapter,
+  telegramAdapter,
+  emailAdapter,
+  isEmailConfigured,
+  resolveSecret,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { getDestinationById } from "../server/lib/dispatch-store.js";
+
+function getAdapter(
+  platform: "slack" | "telegram" | "email",
+  slackToken?: string,
+) {
+  if (platform === "email") return emailAdapter();
+  return platform === "slack"
+    ? slackAdapter({ resolveBotToken: async () => slackToken })
+    : telegramAdapter();
+}
+
+async function assertOutboundConfigured(
+  platform: "slack" | "telegram" | "email",
+  tenantId?: string,
+): Promise<string | undefined> {
+  if (platform === "slack") {
+    const userEmail = getRequestUserEmail();
+    if (!userEmail) throw new Error("An authenticated user is required");
+    const installations = tenantId
+      ? await listIntegrationInstallations(
+          { userEmail, orgId: getRequestOrgId() ?? null },
+          "slack",
+        )
+      : [];
+    const installation =
+      installations.find(
+        (candidate) =>
+          candidate.teamId === tenantId || candidate.enterpriseId === tenantId,
+      ) ?? null;
+    const managed = installation
+      ? await resolveIntegrationTokenBundle(
+          "slack",
+          installation.installationKey,
+        )
+      : null;
+    const token = tenantId
+      ? managed?.accessToken
+      : (managed?.accessToken ?? (await resolveSecret("SLACK_BOT_TOKEN")));
+    if (!token) {
+      throw new Error(
+        tenantId
+          ? "That Slack workspace is not connected"
+          : "Select a Slack workspace for managed outbound messaging",
+      );
+    }
+    return token;
+  }
+  if (platform === "telegram" && !(await resolveSecret("TELEGRAM_BOT_TOKEN"))) {
+    throw new Error("Telegram outbound messaging is not configured");
+  }
+  if (platform === "email") {
+    if (
+      !(await resolveSecret("EMAIL_AGENT_ADDRESS")) ||
+      !(await isEmailConfigured())
+    ) {
+      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"),
+    tenantId: z
+      .string()
+      .optional()
+      .describe("Slack workspace/team id for managed installations"),
+    text: z.string().describe("Message to send"),
+  }),
+  audit: {
+    recordInputs: false,
+    target: (args) => ({
+      type: "destination",
+      id: args.destinationId || args.destination || "unknown",
+      visibility: "private",
+    }),
+    summary: (args) => `Sent proactive ${args.platform || "saved"} message`,
+  },
+  run: async ({
+    platform,
+    destinationId,
+    destination,
+    threadRef,
+    tenantId,
+    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");
+    }
+
+    const slackToken = await assertOutboundConfigured(
+      resolvedPlatform,
+      tenantId,
+    );
+
+    const adapter = getAdapter(resolvedPlatform, slackToken);
+    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,
+      tenantId,
+    });
+
+    return {
+      ok: true,
+      platform: resolvedPlatform,
+      destination: resolvedDestination,
+      threadRef: resolvedThreadRef,
+    };
+  },
+});

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

@@ -0,0 +1,22 @@
+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, and the Builder project this organization uses for cloud code changes. Organization owners and admins only. Stores the project id as an organization-scoped credential; does not write env vars or files.",
+  schema: z.object({
+    builderProjectId: z
+      .string()
+      .trim()
+      .min(1)
+      .max(128)
+      .optional()
+      .nullable()
+      .describe(
+        "Builder project ID used for app-creation branches and for cloud code-change branches across this organization's workspace apps. Pass null to clear it and return those apps to the connect/waitlist prompt.",
+      ),
+  }),
+  run: async (args) => setAppCreationSettings(args),
+});

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

@@ -0,0 +1,25 @@
+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/set-dream-settings.spec.ts

@@ -0,0 +1,81 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  setDreamSettings: vi.fn(),
+}));
+
+vi.mock("../server/lib/dreams-store.js", () => ({
+  setDreamSettings: mocks.setDreamSettings,
+}));
+
+import action from "./set-dream-settings.js";
+
+describe("set-dream-settings action", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.setDreamSettings.mockImplementation(async (input) => ({
+      enabled: false,
+      schedule: "0 9 * * 1",
+      sourceId: "all",
+      sourceIds: [],
+      allSources: true,
+      query: null,
+      limit: 8,
+      sourceTimeoutMs: 30000,
+      sourceConcurrency: 2,
+      sourceStartStaggerMs: 250,
+      threadConcurrency: 3,
+      threadTimeoutMs: 8000,
+      minCandidateCount: 1,
+      ...input,
+    }));
+  });
+
+  it("coerces numeric fields and preserves explicit clears", async () => {
+    await action.run({
+      enabled: true,
+      schedule: "0 8 * * 2",
+      sourceId: "current",
+      sourceIds: [],
+      allSources: false,
+      query: "",
+      limit: "50",
+      sourceTimeoutMs: "60000",
+      sourceConcurrency: "8",
+      sourceStartStaggerMs: "5000",
+      threadConcurrency: "10",
+      threadTimeoutMs: "30000",
+      minCandidateCount: "0",
+    } as any);
+
+    expect(mocks.setDreamSettings).toHaveBeenCalledWith({
+      enabled: true,
+      schedule: "0 8 * * 2",
+      sourceId: "current",
+      sourceIds: [],
+      allSources: false,
+      query: "",
+      limit: 50,
+      sourceTimeoutMs: 60000,
+      sourceConcurrency: 8,
+      sourceStartStaggerMs: 5000,
+      threadConcurrency: 10,
+      threadTimeoutMs: 30000,
+      minCandidateCount: 0,
+    });
+  });
+
+  it("rejects out-of-range numeric settings before writing", async () => {
+    await expect(action.run({ limit: "0" } as any)).rejects.toThrow(
+      /Invalid action parameters/,
+    );
+    await expect(
+      action.run({ sourceTimeoutMs: "60001" } as any),
+    ).rejects.toThrow(/Invalid action parameters/);
+    await expect(
+      action.run({ threadTimeoutMs: "30001" } as any),
+    ).rejects.toThrow(/Invalid action parameters/);
+
+    expect(mocks.setDreamSettings).not.toHaveBeenCalled();
+  });
+});

package/src/actions/set-dream-settings.ts

@@ -0,0 +1,45 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { setDreamSettings } from "../server/lib/dreams-store.js";
+
+export default defineAction({
+  description:
+    "Update recurring Dispatch dream settings without immediately running or applying a dream pass.",
+  schema: z.object({
+    enabled: z
+      .boolean()
+      .optional()
+      .describe("Whether recurring dreams are on."),
+    schedule: z
+      .string()
+      .optional()
+      .describe('Five-field cron schedule, for example "0 9 * * 1".'),
+    sourceId: z
+      .string()
+      .optional()
+      .describe(
+        "Thread debug source id. Use 'all' for every connected source.",
+      ),
+    sourceIds: z
+      .array(z.string().min(1))
+      .optional()
+      .describe("Optional explicit source ids to scan together."),
+    allSources: z.coerce
+      .boolean()
+      .optional()
+      .describe("Scan every connected thread-debug source."),
+    query: z
+      .string()
+      .optional()
+      .describe("Optional search term for recurring dream passes."),
+    limit: z.coerce.number().int().min(1).max(50).optional(),
+    sourceTimeoutMs: z.coerce.number().int().min(1000).max(60000).optional(),
+    sourceConcurrency: z.coerce.number().int().min(1).max(8).optional(),
+    sourceStartStaggerMs: z.coerce.number().int().min(0).max(5000).optional(),
+    threadConcurrency: z.coerce.number().int().min(1).max(10).optional(),
+    threadTimeoutMs: z.coerce.number().int().min(1000).max(30000).optional(),
+    minCandidateCount: z.coerce.number().int().min(0).max(50).optional(),
+  }),
+  run: async (input) => setDreamSettings(input),
+});

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

@@ -0,0 +1,73 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  discoverAgents: vi.fn(),
+  setAccess: vi.fn(),
+  recordAudit: vi.fn(),
+  listAccess: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/server/agent-discovery", () => ({
+  discoverAgents: mocks.discoverAgents,
+}));
+
+vi.mock("../server/lib/mcp-access-store.js", () => ({
+  setDispatchMcpAppAccessSettings: mocks.setAccess,
+}));
+
+vi.mock("../server/lib/dispatch-store.js", () => ({
+  recordAudit: mocks.recordAudit,
+}));
+
+vi.mock("./list-mcp-app-access.js", () => ({
+  default: { run: mocks.listAccess },
+}));
+
+import setMcpAppAccess from "./set-mcp-app-access.js";
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.discoverAgents.mockResolvedValue([
+    { id: "analytics" },
+    { id: "slides" },
+  ]);
+  mocks.setAccess.mockResolvedValue(undefined);
+  mocks.recordAudit.mockResolvedValue(undefined);
+  mocks.listAccess.mockResolvedValue({ mode: "selected-apps" });
+});
+
+describe("set-mcp-app-access", () => {
+  it("accepts Dispatch itself in selected-app mode", async () => {
+    await setMcpAppAccess.run({
+      mode: "selected-apps",
+      selectedAppIds: ["Dispatch", "slides"],
+    });
+
+    expect(mocks.setAccess).toHaveBeenCalledWith({
+      mode: "selected-apps",
+      selectedAppIds: ["dispatch", "slides"],
+    });
+  });
+
+  it("allows an owner or admin to revoke every app grant", async () => {
+    await setMcpAppAccess.run({
+      mode: "selected-apps",
+      selectedAppIds: [],
+    });
+
+    expect(mocks.setAccess).toHaveBeenCalledWith({
+      mode: "selected-apps",
+      selectedAppIds: [],
+    });
+  });
+
+  it("rejects unknown app ids before changing access", async () => {
+    await expect(
+      setMcpAppAccess.run({
+        mode: "selected-apps",
+        selectedAppIds: ["unknown"],
+      }),
+    ).rejects.toThrow(/Unknown app/);
+    expect(mocks.setAccess).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,56 @@
+import { defineAction } from "@agent-native/core";
+import { discoverAgents } from "@agent-native/core/server/agent-discovery";
+import { z } from "zod";
+
+import { recordAudit } from "../server/lib/dispatch-store.js";
+import { setDispatchMcpAppAccessSettings } from "../server/lib/mcp-access-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(["dispatch", ...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.`,
+      );
+    }
+    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/set-vault-access-settings.ts

@@ -0,0 +1,17 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { setVaultAccessSettings } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "Set the Dispatch vault access mode. Admin only. Use all-apps for the default workspace-wide mode or manual to require explicit per-app grants.",
+  schema: z.object({
+    mode: z
+      .enum(["all-apps", "manual"])
+      .describe(
+        "all-apps shares every vault key with every app; manual requires grants",
+      ),
+  }),
+  run: async (args) => setVaultAccessSettings(args),
+});

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

@@ -0,0 +1,55 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getWorkspaceAppIdValidationError,
+  normalizeWorkspaceAppId,
+} 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 when the request truly needs its own app. For Claude Web, ChatGPT Web, or either host\'s web Project, this action is the Builder handoff: call it after forming a bounded source brief and do not scaffold or edit files in the host sandbox. This handoff is autonomous once the brief exists: do not ask the user for non-blocking product or UX choices; choose recommended defaults and let Builder record assumptions while it implements. 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 reuses the connected Agent-Native workspace project or, for an organization owner/admin, provisions it through the Builder Projects API before starting the Builder Cloud Agent branch. If no project is configured, organization members must ask an owner/admin to configure it first. The result must be a separate workspace app under apps/<app-id>, not a new route or file in apps/chat. If chat is used as the source template, the finished app must be branded as the requested app and must not leave visible "Chat", "Starter", "Blank app", or "New app" UI behind. If the request needs Mail, Calendar, Analytics, Brain, Assets, or another first-party app, use the existing hosted/connected app via links or A2A; do not wrap or nest those apps inside the new app unless the user explicitly asks for a customized app from that template.',
+  schema: z.object({
+    prompt: z.string().min(1).describe("The user's app creation request"),
+    appId: z
+      .string()
+      .max(64)
+      .transform(normalizeWorkspaceAppId)
+      .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 or human-friendly name. Names are converted to lowercase, hyphenated ids.",
+      ),
+    template: z
+      .string()
+      .optional()
+      .nullable()
+      .describe("Template to start from"),
+    description: z
+      .string()
+      .max(500)
+      .optional()
+      .nullable()
+      .describe(
+        "Concise AI-generated description of the app based on the user's prompt. Dispatch saves this while the app is being created.",
+      ),
+    secretIds: z
+      .array(z.string())
+      .max(100)
+      .optional()
+      .describe("Dispatch vault secret IDs to grant to the app"),
+    resourceIds: z
+      .array(z.string())
+      .max(100)
+      .optional()
+      .describe(
+        "Dispatch workspace resource IDs or knowledge packs to grant to the app",
+      ),
+  }),
+  run: async (args) => startWorkspaceAppCreation(args),
+});

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

@@ -0,0 +1,15 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { syncGrantsToApp } from "../server/lib/vault-store.js";
+
+export default defineAction({
+  description:
+    "Push vault secrets to an app by calling its env-vars endpoint. Admin only. In all-apps mode this syncs every vault key; in manual mode it syncs active grants.",
+  schema: z.object({
+    appId: z
+      .string()
+      .describe("App ID to sync secrets to, e.g. mail, calendar, analytics"),
+  }),
+  run: async (args) => syncGrantsToApp(args.appId),
+});