@agent-native/dispatch 0.13.13 → 0.14.1

package/src/routes/index.spec.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+
+import { dispatchRoutes } from "./index.js";
+
+describe("Dispatch route registration", () => {
+  it("registers chat and operator routes before the workspace-app fallback", () => {
+    const routes = dispatchRoutes as Array<{
+      path?: string;
+      file?: string;
+      index?: boolean;
+    }>;
+    const paths = routes.map((route) => route.path);
+
+    expect(paths).toContain("chat");
+    expect(paths).toContain("chat/:threadId");
+    expect(paths).toContain("operations");
+    expect(paths.indexOf("chat")).toBeLessThan(paths.indexOf(":appId"));
+    expect(paths.indexOf("chat/:threadId")).toBeLessThan(
+      paths.indexOf(":appId"),
+    );
+    expect(paths.indexOf("operations")).toBeLessThan(paths.indexOf(":appId"));
+  });
+});

package/src/routes/index.ts

@@ -35,6 +35,7 @@ export const dispatchRoutes: RouteConfig = [
   route("chat/:threadId", "./pages/chat.js"),
   route("overview", "./pages/overview.js"),
   route("metrics", "./pages/metrics.js"),
+  route("operations", "./pages/operations.js"),
   route("apps", "./pages/apps.js"),
   route("apps/:appId", "./pages/apps.$appId.js"),
   route("new-app", "./pages/new-app.js"),

package/src/routes/pages/messaging.tsx

@@ -9,7 +9,7 @@ export default function MessagingRoute() {
   return (
     <DispatchShell
       title="Messaging"
-      description="Connect Slack and Telegram directly in dispatch so inbound conversations come through one place."
+      description="Connect Slack, Microsoft Teams, Discord interactions, Telegram, WhatsApp Cloud API, or provider-webhook email so supported inbound conversations reach one Dispatch inbox."
     >
       <MessagingSetupPanel />
     </DispatchShell>

package/src/routes/pages/operations.tsx

@@ -0,0 +1,134 @@
+import {
+  DbAdminPage,
+  ObservabilityDashboard,
+  useT,
+} from "@agent-native/core/client";
+import {
+  IconActivity,
+  IconArrowUpRight,
+  IconDatabase,
+  IconHistory,
+  IconMessages,
+  IconSend,
+} from "@tabler/icons-react";
+import { Link, useSearchParams } from "react-router";
+
+import { DispatchShell } from "../../components/dispatch-shell";
+import {
+  Tabs,
+  TabsContent,
+  TabsList,
+  TabsTrigger,
+} from "../../components/ui/tabs";
+
+type OperationsView = "monitoring" | "database";
+
+function selectedView(value: string | null): OperationsView {
+  return value === "database" ? "database" : "monitoring";
+}
+
+function OperationsShortcuts() {
+  const t = useT();
+
+  const tools = [
+    {
+      to: "/thread-debug",
+      icon: IconMessages,
+      title: t("dispatch.nav.threadDebug", { defaultValue: "Thread debug" }),
+    },
+    {
+      to: "/audit",
+      icon: IconHistory,
+      title: t("dispatch.nav.audit"),
+    },
+    {
+      to: "/destinations",
+      icon: IconSend,
+      title: t("dispatch.pages.deliveryQueue"),
+    },
+  ];
+
+  return (
+    <section className="border-t pt-5">
+      <h2 className="text-sm font-semibold text-foreground">
+        {t("dispatch.nav.advanced", { defaultValue: "Related tools" })}
+      </h2>
+      <div className="mt-2 grid gap-x-6 gap-y-1 lg:grid-cols-3">
+        {tools.map(({ to, icon: Icon, title }) => (
+          <Link
+            key={to}
+            to={to}
+            className="group flex min-w-0 items-start gap-2 rounded-md px-2 py-2 text-sm transition-colors hover:bg-muted"
+          >
+            <Icon
+              size={16}
+              className="mt-0.5 shrink-0 text-muted-foreground transition-colors group-hover:text-foreground"
+            />
+            <span className="min-w-0">
+              <span className="flex items-center gap-1 font-medium text-foreground">
+                <span className="truncate">{title}</span>
+                <IconArrowUpRight
+                  size={13}
+                  className="shrink-0 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100"
+                />
+              </span>
+            </span>
+          </Link>
+        ))}
+      </div>
+    </section>
+  );
+}
+
+export function meta() {
+  return [{ title: "Operations — Dispatch" }];
+}
+
+export default function OperationsRoute() {
+  const t = useT();
+  const [searchParams, setSearchParams] = useSearchParams();
+  const view = selectedView(searchParams.get("view"));
+
+  function setView(nextView: OperationsView) {
+    const next = new URLSearchParams(searchParams);
+    if (nextView === "monitoring") next.delete("view");
+    else next.set("view", nextView);
+    setSearchParams(next, { replace: true });
+  }
+
+  return (
+    <DispatchShell title={t("dispatch.nav.operations")}>
+      <Tabs
+        value={view}
+        onValueChange={(value) => {
+          if (value === "monitoring" || value === "database") setView(value);
+        }}
+        className="flex min-w-0 flex-col gap-5"
+      >
+        <TabsList className="w-fit">
+          <TabsTrigger value="monitoring">
+            <IconActivity size={15} />
+            {t("dispatch.pages.monitoring")}
+          </TabsTrigger>
+          <TabsTrigger value="database">
+            <IconDatabase size={15} />
+            {t("dispatch.pages.database")}
+          </TabsTrigger>
+        </TabsList>
+
+        <TabsContent value="monitoring" className="mt-0 min-w-0">
+          <ObservabilityDashboard />
+          <div className="mt-8">
+            <OperationsShortcuts />
+          </div>
+        </TabsContent>
+
+        <TabsContent value="database" className="mt-0 min-w-0">
+          <div className="min-h-[620px] overflow-hidden rounded-lg border bg-background">
+            <DbAdminPage title={t("dispatch.pages.database")} />
+          </div>
+        </TabsContent>
+      </Tabs>
+    </DispatchShell>
+  );
+}

package/src/server/lib/dispatch-integrations.spec.ts

@@ -4,6 +4,7 @@ const mocks = vi.hoisted(() => ({
   consumeLinkToken: vi.fn(),
   resolveLinkedOwner: vi.fn(),
   resolveOrgIdForEmail: vi.fn(),
+  resolveSecret: vi.fn(),
 }));
 
 vi.mock("./dispatch-store.js", () => ({
@@ -15,6 +16,16 @@ vi.mock("@agent-native/core/org", () => ({
   resolveOrgIdForEmail: mocks.resolveOrgIdForEmail,
 }));
 
+vi.mock("@agent-native/core/server", async () => {
+  const actual = await vi.importActual<
+    typeof import("@agent-native/core/server")
+  >("@agent-native/core/server");
+  return {
+    ...actual,
+    resolveSecret: mocks.resolveSecret,
+  };
+});
+
 import type {
   IncomingMessage,
   PlatformAdapter,
@@ -24,6 +35,7 @@ import {
   beforeDispatchProcess,
   identityKeyForIncoming,
   resolveDispatchOwner,
+  resolveDispatchExecutionContext,
 } from "./dispatch-integrations.js";
 
 const originalFetch = globalThis.fetch;
@@ -94,6 +106,9 @@ beforeEach(() => {
   mocks.resolveLinkedOwner.mockResolvedValue(null);
   mocks.consumeLinkToken.mockResolvedValue("owner@example.test");
   mocks.resolveOrgIdForEmail.mockResolvedValue(null);
+  mocks.resolveSecret.mockImplementation(
+    async (key: string) => process.env[key] ?? null,
+  );
   vi.stubGlobal(
     "fetch",
     vi.fn(async () => new Response(JSON.stringify({ ok: false }))),
@@ -130,6 +145,7 @@ describe("resolveDispatchOwner", () => {
 
   it("uses the verified Slack email for org members", async () => {
     vi.stubEnv("SLACK_BOT_TOKEN", "xoxb-token");
+    mocks.resolveSecret.mockResolvedValueOnce(null);
     mocks.resolveOrgIdForEmail.mockResolvedValueOnce("org_123");
     vi.mocked(globalThis.fetch).mockResolvedValueOnce(
       new Response(
@@ -153,6 +169,37 @@ describe("resolveDispatchOwner", () => {
     expect(incoming.platformContext.senderEmail).toBe("user@example.test");
   });
 
+  it("uses the request-scoped Slack token when no env token exists", async () => {
+    mocks.resolveSecret.mockResolvedValueOnce("configured-slack-token");
+    mocks.resolveOrgIdForEmail.mockResolvedValueOnce("org_123");
+    vi.mocked(globalThis.fetch).mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          ok: true,
+          user: {
+            profile: { email: "member@example.test", display_name: "Member" },
+          },
+        }),
+      ),
+    );
+
+    await expect(
+      resolveDispatchOwner(
+        slackIncoming({
+          senderId: "U999",
+          platformContext: { teamId: "T999", channelId: "C1" },
+        }),
+      ),
+    ).resolves.toBe("member@example.test");
+    expect(mocks.resolveSecret).toHaveBeenCalledWith("SLACK_BOT_TOKEN");
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      "https://slack.com/api/users.info?user=U999",
+      {
+        headers: { Authorization: "Bearer configured-slack-token" },
+      },
+    );
+  });
+
   it("falls back to the configured Slack owner when the sender is not an org member", async () => {
     vi.stubEnv("SLACK_BOT_TOKEN", "xoxb-token");
     vi.stubEnv("DISPATCH_DEFAULT_OWNER_EMAIL", "default@example.test");
@@ -226,6 +273,20 @@ describe("resolveDispatchOwner", () => {
 });
 
 describe("beforeDispatchProcess", () => {
+  it("attaches capability-based guidance for structured intake", async () => {
+    const incoming = slackIncoming({
+      text: "File this review request using our intake form",
+    });
+
+    await expect(beforeDispatchProcess(incoming, noopAdapter)).resolves.toEqual(
+      { handled: false },
+    );
+    expect((incoming as any).routingHint.targetAgent).toBeUndefined();
+    expect((incoming as any).routingHint.instruction).toContain(
+      "workspace instructions/resources",
+    );
+  });
+
   it("asks unlinked Telegram users to link before using org context", async () => {
     vi.stubEnv("APP_URL", "https://dispatch.agent-native.test");
 
@@ -274,4 +335,56 @@ describe("beforeDispatchProcess", () => {
       externalUserName: "Steve",
     });
   });
+
+  it("replies with linking guidance instead of silently dropping an unlinked Slack DM", async () => {
+    vi.stubEnv("APP_URL", "https://dispatch.agent-native.test");
+    const incoming = slackIncoming({
+      triggerKind: "dm",
+      conversationType: "dm",
+      platformContext: {
+        teamId: "T123",
+        channelId: "D123",
+        channelType: "im",
+      },
+    });
+
+    const execution = await resolveDispatchExecutionContext(incoming);
+    const result = await beforeDispatchProcess(incoming, noopAdapter);
+
+    expect(execution.ownerEmail).toMatch(/@integration\.local$/);
+    expect(incoming.platformContext.identityLinkRequired).toBe(true);
+    expect(result).toEqual({
+      handled: true,
+      responseText:
+        "Agent Native is ready, but this Slack account is not linked to an Agent Native user yet. Open https://dispatch.agent-native.test/identities, create a Slack link token, then send `/link <token>` in this DM.",
+    });
+  });
+
+  it("lets an unlinked Slack DM consume a link token before the agent gate", async () => {
+    const incoming = slackIncoming({
+      text: "/link token-123",
+      triggerKind: "dm",
+      conversationType: "dm",
+      platformContext: {
+        teamId: "T123",
+        channelId: "D123",
+        channelType: "im",
+      },
+    });
+
+    await resolveDispatchExecutionContext(incoming);
+    const result = await beforeDispatchProcess(incoming, noopAdapter);
+
+    expect(result).toEqual({
+      handled: true,
+      responseText:
+        "Linked successfully. Future slack messages will use owner@example.test's personal dispatch context.",
+    });
+    expect(mocks.consumeLinkToken).toHaveBeenCalledWith({
+      platform: "slack",
+      token: "token-123",
+      externalUserId: "T123:U123",
+      externalUserName: "U123",
+    });
+  });
 });

package/src/server/lib/dispatch-integrations.ts

@@ -1,18 +1,36 @@
 import crypto from "node:crypto";
 
+import {
+  evaluateIntegrationScopePolicy,
+  getActiveIntegrationInstallationByKey,
+  getIntegrationScope,
+  resolveIntegrationTokenBundle,
+  saveIntegrationScope,
+  slackInstallationKey,
+} from "@agent-native/core/integrations";
 import { resolveOrgIdForEmail } from "@agent-native/core/org";
-import { withConfiguredAppBasePath } from "@agent-native/core/server";
+import {
+  readDeployCredentialEnv,
+  resolveSecret,
+  withConfiguredAppBasePath,
+} from "@agent-native/core/server";
 import type {
   IncomingMessage,
+  IntegrationExecutionContext,
   PlatformAdapter,
 } from "@agent-native/core/server";
 
 import { handleRemoteCodeCommand } from "./dispatch-remote-commands.js";
+import {
+  dispatchIntegrationRoutingHint,
+  type DispatchIntegrationRoutingHint,
+} from "./dispatch-routing.js";
 import { consumeLinkToken, resolveLinkedOwner } from "./dispatch-store.js";
 
 type SlackSenderProfile = {
   email: string | null;
   name: string | null;
+  trust: "trusted" | "guest" | "external_shared" | "unknown";
 };
 
 const slackProfileCache = new Map<
@@ -104,6 +122,33 @@ function configuredDispatchIdentitiesUrl(): string | null {
   }
 }
 
+async function resolveManagedSlackInstallation(incoming: IncomingMessage) {
+  if (incoming.platform !== "slack") return null;
+  const teamId = contextString(incoming.platformContext.teamId);
+  const apiAppId = contextString(incoming.platformContext.apiAppId);
+  if (!teamId) return null;
+  try {
+    return await getActiveIntegrationInstallationByKey(
+      "slack",
+      slackInstallationKey({ teamId, apiAppId }),
+    );
+  } catch {
+    return null;
+  }
+}
+
+async function resolveManagedSlackToken(
+  incoming: IncomingMessage,
+): Promise<string | null> {
+  const installation = await resolveManagedSlackInstallation(incoming);
+  if (!installation) return null;
+  const bundle = await resolveIntegrationTokenBundle(
+    "slack",
+    installation.installationKey,
+  );
+  return bundle?.accessToken ?? null;
+}
+
 function formatTelegramLinkRequiredMessage(): string {
   const identitiesUrl = configuredDispatchIdentitiesUrl();
   const linkStep = identitiesUrl
@@ -112,14 +157,30 @@ function formatTelegramLinkRequiredMessage(): string {
   return `Telegram is connected, but this Telegram account is not linked to an Agent-Native user yet. ${linkStep} After that I can use your Builder.io org and connected apps.`;
 }
 
+function formatSlackLinkRequiredMessage(): string {
+  const identitiesUrl = configuredDispatchIdentitiesUrl();
+  const linkStep = identitiesUrl
+    ? `Open ${identitiesUrl}, create a Slack link token, then send \`/link <token>\` in this DM.`
+    : "Open Dispatch while signed in, create a Slack link token, then send `/link <token>` in this DM.";
+  return `Agent Native is ready, but this Slack account is not linked to an Agent Native user yet. ${linkStep}`;
+}
+
 async function resolveSlackSenderProfile(
   incoming: IncomingMessage,
 ): Promise<SlackSenderProfile> {
-  if (incoming.platform !== "slack") return { email: null, name: null };
-  const token = process.env.SLACK_BOT_TOKEN;
+  if (incoming.platform !== "slack") {
+    return { email: null, name: null, trust: "unknown" };
+  }
+  const managedToken = await resolveManagedSlackToken(incoming);
+  const token =
+    managedToken ??
+    (await resolveSecret("SLACK_BOT_TOKEN")) ??
+    readDeployCredentialEnv("SLACK_BOT_TOKEN");
   const userId = contextString(incoming.senderId);
   const teamId = contextString(incoming.platformContext.teamId);
-  if (!token || !userId) return { email: null, name: null };
+  if (!token || !userId) {
+    return { email: null, name: null, trust: "unknown" };
+  }
 
   // Slack user IDs are scoped per workspace, so without a teamId we can't
   // safely cache: two installs of the bot in different workspaces could
@@ -146,6 +207,8 @@ async function resolveSlackSenderProfile(
           real_name?: string;
           display_name?: string;
         };
+        is_restricted?: boolean;
+        is_ultra_restricted?: boolean;
       };
     };
     const profile = data.ok
@@ -157,8 +220,14 @@ async function resolveSlackSenderProfile(
             data.user?.real_name?.trim() ||
             data.user?.name?.trim() ||
             null,
+          trust:
+            data.user?.is_ultra_restricted === true
+              ? ("external_shared" as const)
+              : data.user?.is_restricted === true
+                ? ("guest" as const)
+                : ("trusted" as const),
         }
-      : { email: null, name: null };
+      : { email: null, name: null, trust: "unknown" as const };
     if (cacheKey) {
       slackProfileCache.set(cacheKey, {
         profile,
@@ -167,7 +236,7 @@ async function resolveSlackSenderProfile(
     }
     return profile;
   } catch {
-    return { email: null, name: null };
+    return { email: null, name: null, trust: "unknown" };
   }
 }
 
@@ -188,6 +257,51 @@ async function resolveSlackOwnerFromVerifiedEmail(
   return orgId ? profile.email : null;
 }
 
+async function resolveSlackConversationTrust(
+  incoming: IncomingMessage,
+  actorTrust: SlackSenderProfile["trust"],
+): Promise<{
+  trust: SlackSenderProfile["trust"];
+  conversationType: "channel" | "direct_message" | "group_direct_message";
+}> {
+  if (incoming.triggerKind === "dm") {
+    return { trust: actorTrust, conversationType: "direct_message" };
+  }
+  const token = await resolveManagedSlackToken(incoming);
+  const channel = contextString(incoming.platformContext.channelId);
+  if (!token || !channel) {
+    return { trust: "unknown", conversationType: "channel" };
+  }
+  try {
+    const params = new URLSearchParams({ channel });
+    const response = await fetch(
+      `https://slack.com/api/conversations.info?${params}`,
+      { headers: { Authorization: `Bearer ${token}` } },
+    );
+    const data = (await response.json()) as {
+      ok?: boolean;
+      channel?: {
+        is_ext_shared?: boolean;
+        is_im?: boolean;
+        is_mpim?: boolean;
+      };
+    };
+    if (!data.ok) {
+      return { trust: "unknown", conversationType: "channel" };
+    }
+    return {
+      trust: data.channel?.is_ext_shared ? "external_shared" : actorTrust,
+      conversationType: data.channel?.is_im
+        ? "direct_message"
+        : data.channel?.is_mpim
+          ? "group_direct_message"
+          : "channel",
+    };
+  } catch {
+    return { trust: "unknown", conversationType: "channel" };
+  }
+}
+
 export async function resolveDispatchOwner(
   incoming: IncomingMessage,
 ): Promise<string> {
@@ -254,6 +368,111 @@ export async function resolveDispatchOwner(
   }
 }
 
+/**
+ * Resolve a personal DM user or a workspace-qualified channel service
+ * principal. Managed Slack channels never silently inherit one requester's
+ * personal credentials or memory.
+ */
+export async function resolveDispatchExecutionContext(
+  incoming: IncomingMessage,
+): Promise<IntegrationExecutionContext> {
+  if (incoming.platform !== "slack" || incoming.triggerKind === "dm") {
+    const ownerEmail = await resolveDispatchOwner(incoming);
+    if (
+      incoming.platform === "slack" &&
+      ownerEmail.endsWith("@integration.local")
+    ) {
+      // Preserve a credential-less principal long enough for beforeProcess to
+      // deliver linking guidance or consume `/link <token>`. Never run the
+      // agent under this synthetic owner.
+      incoming.platformContext.identityLinkRequired = true;
+    }
+    return {
+      ownerEmail,
+      orgId: (await resolveOrgIdForEmail(ownerEmail)) ?? null,
+      principalType: "user",
+    };
+  }
+
+  const installation = await resolveManagedSlackInstallation(incoming);
+  if (!installation) {
+    // Preserve the legacy manually configured app path while managed installs
+    // roll out. Its behavior remains explicit and visible in Settings.
+    const ownerEmail = await resolveDispatchOwner(incoming);
+    return {
+      ownerEmail,
+      orgId: (await resolveOrgIdForEmail(ownerEmail)) ?? null,
+      principalType: "user",
+    };
+  }
+
+  const teamId = contextString(incoming.platformContext.teamId);
+  const channelId = contextString(incoming.platformContext.channelId);
+  if (!teamId || !channelId) {
+    throw new Error("Slack channel identity is incomplete");
+  }
+  const profile = await resolveSlackSenderProfile(incoming);
+  const conversation = await resolveSlackConversationTrust(
+    incoming,
+    profile.trust,
+  );
+  const access = {
+    ownerEmail: installation.ownerEmail,
+    orgId: installation.orgId,
+  };
+  const key = {
+    platform: "slack",
+    tenantId: teamId,
+    conversationId: channelId,
+  };
+  let scope = await getIntegrationScope(key, access);
+  if (!scope && incoming.triggerKind === "mention") {
+    scope = await saveIntegrationScope(
+      {
+        ...key,
+        conversationType: conversation.conversationType,
+        trust: conversation.trust,
+        orgId: installation.orgId,
+        installationId: installation.id,
+      },
+      access,
+    );
+  }
+  if (!scope) throw new Error("Slack channel is not enabled for Agent Native");
+  const decision = evaluateIntegrationScopePolicy(scope, {
+    // Thread replies reached this point only after the adapter's active-task
+    // gate, so they are continuation steering rather than ambient chatter.
+    mentioned:
+      incoming.triggerKind === "mention" ||
+      incoming.triggerKind === "thread_reply",
+  });
+  if (!decision.allowed) {
+    throw new Error(`Slack channel policy denied: ${decision.reason}`);
+  }
+  incoming.integrationScopeId = scope.id;
+  if (scope.defaultModel) {
+    incoming.platformContext.defaultModel = scope.defaultModel;
+  }
+  incoming.actorTrust = {
+    memberType:
+      conversation.trust === "guest"
+        ? "guest"
+        : conversation.trust === "external_shared"
+          ? "external"
+          : conversation.trust === "trusted"
+            ? "member"
+            : "unknown",
+    verified: conversation.trust !== "unknown",
+  };
+  return {
+    ownerEmail: scope.serviceOwnerEmail,
+    orgId: scope.orgId,
+    principalType: "service",
+    installationId: installation.id,
+    scopeId: scope.id,
+  };
+}
+
 export async function beforeDispatchProcess(
   incoming: IncomingMessage,
   adapter: PlatformAdapter,
@@ -263,6 +482,20 @@ export async function beforeDispatchProcess(
     contextString(incoming.platformContext.rawText) || trimmed;
   const match = commandText.match(/^\/link(?:@\w+)?\s+([a-zA-Z0-9_-]+)$/);
   if (!match) {
+    const routedIncoming = incoming as IncomingMessage & {
+      routingHint?: DispatchIntegrationRoutingHint;
+    };
+    routedIncoming.routingHint ??= dispatchIntegrationRoutingHint(trimmed);
+    if (
+      incoming.platform === "slack" &&
+      incoming.triggerKind === "dm" &&
+      incoming.platformContext.identityLinkRequired === true
+    ) {
+      return {
+        handled: true,
+        responseText: formatSlackLinkRequiredMessage(),
+      };
+    }
     if (platformRequiresExplicitLink(incoming)) {
       const owner = await resolveLinkedOwner(
         incoming.platform,