feat(plugin-slack): role-aware outbound client routing — OWNER posts as user

Adds the runtime primitive PR #7868 unblocks: when a Slack
account is configured with role: "OWNER" and a user token (xoxp-)
is present, outbound chat.postMessage calls go through a second
WebClient bound to the user token so the agent acts as the user.
AGENT accounts continue to use the bot client (xoxb-), preserving
all existing single-bot deployments unchanged.

Changes:

- accounts.ts:
  * SlackAccountConfig gains an optional `role` field.
  * ResolvedSlackAccount gains a required `role: ConnectorAccountRole`.
  * `resolveSlackAccount` reads role from per-account character.settings
    or the SLACK_ACCOUNT_ROLE env var (default-account only); falls
    back to "AGENT". Config role beats env role.
  * New `normalizeSlackAccountRole` helper accepts OWNER/AGENT/TEAM
    (mixed case, trimmed) and defaults unknown / non-string input to
    AGENT.

- service.ts:
  * SlackAccountRuntime gains `userClient: WebClient | null`,
    constructed in `initializeAccount` only when `account.userToken`
    is set. The user client is outbound-only — no socket mode.
  * New private `getOutboundClient(accountId)` selects the user
    client when the account's role is OWNER and a user client
    exists; otherwise the bot client. Falls back to
    `getClientForAccount` when per-account state hasn't been
    initialised yet.
  * `sendMessage` switches from `getClientForAccount` to
    `getOutboundClient`. Other call sites stay on the bot client
    because Slack's user-scope grant for chat:write covers
    chat.postMessage only — broadening to reactions/pins/files
    requires additional user scopes and is left for a follow-up.

- accounts.test.ts (new, 8 tests):
  * normalizeSlackAccountRole canonical / mixed-case / fallback paths.
  * resolveSlackAccount role resolution from config, env, default,
    and config-beats-env precedence.

Out of scope (separate PR):

- Hydration of `botToken` / `userToken` / `role` from
  ConnectorAccount records persisted by the OAuth callback
  (#7868). The credential-refs read path is not currently
  exposed by ConnectorAccountManager; adding it would mean a
  cross-plugin runtime change.  Today admins who want OWNER
  routing must set the role + userToken in
  character.settings.slack.accounts.<id> (or via the
  SLACK_ACCOUNT_ROLE + SLACK_USER_TOKEN env pair for the default
  account). Once hydration lands, the OWNER routing in this PR
  picks up the OAuth-stored xoxp- automatically.

Verification:

- bunx tsc --noEmit -p plugins/plugin-slack/tsconfig.json: clean
- bunx vitest run plugins/plugin-slack/src/: 17/17 (8 new + 9 existing)

Author: 2-A-M

plugins/plugin-slack/src/accounts.test.ts

@@ -0,0 +1,116 @@
+import type { Character, IAgentRuntime } from "@elizaos/core";
+import { describe, expect, it, vi } from "vitest";
+import {
+  normalizeSlackAccountRole,
+  resolveSlackAccount,
+  type SlackMultiAccountConfig,
+} from "./accounts";
+
+function createRuntime(
+  slackConfig?: SlackMultiAccountConfig,
+  envOverrides?: Record<string, string | undefined>,
+): IAgentRuntime {
+  const character: Partial<Character> = {
+    settings: slackConfig ? { slack: slackConfig } : {},
+  };
+  const env = envOverrides ?? {};
+  const runtime = {
+    agentId: "agent-1",
+    character: character as Character,
+    getSetting: vi.fn((key: string) => env[key]),
+    logger: { info: vi.fn(), debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+  };
+  return runtime as unknown as IAgentRuntime;
+}
+
+describe("normalizeSlackAccountRole", () => {
+  it("returns canonical OWNER / AGENT / TEAM for matching inputs", () => {
+    expect(normalizeSlackAccountRole("OWNER")).toBe("OWNER");
+    expect(normalizeSlackAccountRole("AGENT")).toBe("AGENT");
+    expect(normalizeSlackAccountRole("TEAM")).toBe("TEAM");
+  });
+
+  it("uppercases mixed-case input", () => {
+    expect(normalizeSlackAccountRole("owner")).toBe("OWNER");
+    expect(normalizeSlackAccountRole("Agent")).toBe("AGENT");
+    expect(normalizeSlackAccountRole(" team ")).toBe("TEAM");
+  });
+
+  it("falls back to AGENT for unknown / non-string values", () => {
+    expect(normalizeSlackAccountRole(undefined)).toBe("AGENT");
+    expect(normalizeSlackAccountRole(null)).toBe("AGENT");
+    expect(normalizeSlackAccountRole("")).toBe("AGENT");
+    expect(normalizeSlackAccountRole("admin")).toBe("AGENT");
+    expect(normalizeSlackAccountRole(42)).toBe("AGENT");
+    expect(normalizeSlackAccountRole({ role: "OWNER" })).toBe("AGENT");
+  });
+});
+
+describe("resolveSlackAccount role wiring", () => {
+  it("defaults role to AGENT when no role is configured", () => {
+    const runtime = createRuntime({
+      botToken: "xoxb-bot",
+      appToken: "xapp-app",
+    });
+    const account = resolveSlackAccount(runtime, "default");
+    expect(account.role).toBe("AGENT");
+  });
+
+  it("reads role from per-account character.settings.slack.accounts entry", () => {
+    const runtime = createRuntime({
+      accounts: {
+        owner: {
+          role: "OWNER",
+          botToken: "xoxb-bot",
+          appToken: "xapp-app",
+          userToken: "xoxp-user",
+        },
+      },
+    });
+    const account = resolveSlackAccount(runtime, "owner");
+    expect(account.role).toBe("OWNER");
+    expect(account.userToken).toBe("xoxp-user");
+  });
+
+  it("reads role from SLACK_ACCOUNT_ROLE env for the default account only", () => {
+    const runtime = createRuntime(
+      { botToken: "xoxb-bot", appToken: "xapp-app" },
+      { SLACK_ACCOUNT_ROLE: "OWNER" },
+    );
+    const account = resolveSlackAccount(runtime, "default");
+    expect(account.role).toBe("OWNER");
+  });
+
+  it("does not apply env SLACK_ACCOUNT_ROLE to non-default accounts", () => {
+    const runtime = createRuntime(
+      {
+        accounts: {
+          owner: {
+            botToken: "xoxb-bot",
+            appToken: "xapp-app",
+          },
+        },
+      },
+      { SLACK_ACCOUNT_ROLE: "OWNER" },
+    );
+    const account = resolveSlackAccount(runtime, "owner");
+    // env override only applies to the legacy/default account path, so the
+    // explicit per-account config (no role set) still falls back to AGENT
+    expect(account.role).toBe("AGENT");
+  });
+
+  it("config role wins over env role", () => {
+    const runtime = createRuntime(
+      {
+        botToken: "xoxb-bot",
+        appToken: "xapp-app",
+        accounts: {
+          default: { role: "OWNER" },
+        },
+      },
+      { SLACK_ACCOUNT_ROLE: "AGENT" },
+    );
+    const account = resolveSlackAccount(runtime, "default");
+    expect(account.role).toBe("OWNER");
+  });
+});

plugins/plugin-slack/src/accounts.ts

@@ -1,4 +1,4 @@
-import type { IAgentRuntime } from "@elizaos/core";
+import type { ConnectorAccountRole, IAgentRuntime } from "@elizaos/core";
 
 /**
  * Default account identifier used when no specific account is configured
@@ -81,6 +81,14 @@ export interface SlackAccountConfig {
   name?: string;
   /** If false, do not start this Slack account */
   enabled?: boolean;
+  /**
+   * Account role. AGENT (the default) means outbound API calls are made
+   * with the bot token (xoxb-) and represent the agent identity. OWNER
+   * means outbound calls that have user-token coverage (chat:write user
+   * scope) are made with the xoxp- user token so the agent acts as the
+   * user who installed the integration.
+   */
+  role?: ConnectorAccountRole;
   /** Slack bot token (xoxb-...) */
   botToken?: string;
   /** Slack app-level token (xapp-...) */
@@ -138,6 +146,12 @@ export interface ResolvedSlackAccount {
   accountId: string;
   enabled: boolean;
   name?: string;
+  /**
+   * Role this account represents in OWNER+AGENT terms. Drives outbound
+   * API client selection in the runtime: AGENT → bot token, OWNER →
+   * user token for calls covered by the granted user scopes.
+   */
+  role: ConnectorAccountRole;
   botToken?: string;
   appToken?: string;
   signingSecret?: string;
@@ -190,6 +204,22 @@ export function resolveSlackUserToken(raw?: string | null): string | undefined {
   return normalizeSlackToken(raw, "xoxp-");
 }
 
+/**
+ * Normalises an inbound role string into a `ConnectorAccountRole`.
+ * Unknown values fall back to AGENT — the default for legacy single
+ * bot-token deployments where the agent IS the bot.
+ */
+export function normalizeSlackAccountRole(
+  raw: unknown,
+): ConnectorAccountRole {
+  if (typeof raw !== "string") return "AGENT";
+  const upper = raw.trim().toUpperCase();
+  if (upper === "OWNER" || upper === "AGENT" || upper === "TEAM") {
+    return upper;
+  }
+  return "AGENT";
+}
+
 /**
  * Gets the multi-account configuration from runtime settings
  */
@@ -359,10 +389,20 @@ export function resolveSlackAccount(
   const configUserToken = resolveSlackUserToken(merged.userToken);
   const userToken = configUserToken ?? envUserToken;
 
+  // Resolve role. Precedence: per-account config role > env override
+  // (default account only) > "AGENT". AGENT is the legacy default — the
+  // agent acts as the bot identity. OWNER routes user-scope-covered
+  // outbound calls through the xoxp- user token.
+  const envRole = allowEnv
+    ? (runtime.getSetting("SLACK_ACCOUNT_ROLE") as string | undefined)
+    : undefined;
+  const role = normalizeSlackAccountRole(merged.role ?? envRole);
+
   return {
     accountId: normalizedAccountId,
     enabled,
     name: merged.name?.trim() || undefined,
+    role,
     botToken,
     appToken,
     signingSecret,

plugins/plugin-slack/src/service.ts

@@ -21,7 +21,7 @@ import {
   type World,
 } from "@elizaos/core";
 import { App, LogLevel } from "@slack/bolt";
-import type { WebAPICallResult } from "@slack/web-api";
+import { WebClient as SlackWebClient, type WebAPICallResult } from "@slack/web-api";
 
 type WebClient = App["client"];
 type AccountScopedTargetInfo = TargetInfo & { accountId?: string };
@@ -317,6 +317,14 @@ type SlackAccountRuntime = {
   account: ResolvedSlackAccount;
   app: App;
   client: WebClient;
+  /**
+   * Optional xoxp- user-token client. Present only when the account
+   * has a `userToken` configured. OWNER-role accounts route outbound
+   * calls covered by the granted user scopes (currently `chat:write`)
+   * through this client so the agent acts as the user; AGENT-role
+   * accounts ignore it and keep using the bot client.
+   */
+  userClient: WebClient | null;
   botUserId: string | null;
   teamId: string | null;
   settings: SlackSettings;
@@ -717,11 +725,20 @@ export class SlackService extends Service implements ISlackService {
           : {}),
       });
 
+      // User-token client (xoxp-) is outbound-only; no socket-mode
+      // session is needed. Only constructed when a user token is
+      // configured. Routing decisions in getOutboundClient() consult
+      // account.role to decide which client receives each call.
+      const userClient = account.userToken
+        ? (new SlackWebClient(account.userToken) as unknown as WebClient)
+        : null;
+
       const state: SlackAccountRuntime = {
         accountId,
         account,
         app,
         client: app.client,
+        userClient,
         botUserId: null,
         teamId: null,
         settings: this.loadSettings(account),
@@ -897,6 +914,25 @@ export class SlackService extends Service implements ISlackService {
     return null;
   }
 
+  /**
+   * Returns the client that outbound user-action calls (currently
+   * chat.postMessage) should use for the given account. OWNER-role
+   * accounts with a configured xoxp- user token route through it so
+   * the agent posts as the user; everything else stays on the bot
+   * client. Falls back to `getClientForAccount` when no per-account
+   * state has been initialised yet.
+   */
+  private getOutboundClient(accountId?: string | null): WebClient | null {
+    const state = this.getAccountState(accountId);
+    if (!state) {
+      return this.getClientForAccount(accountId);
+    }
+    if (state.account.role === "OWNER" && state.userClient) {
+      return state.userClient;
+    }
+    return state.client;
+  }
+
   private getSettingsForAccount(accountId?: string | null): SlackSettings {
     return this.getAccountState(accountId)?.settings ?? this.settings;
   }
@@ -2855,7 +2891,7 @@ export class SlackService extends Service implements ISlackService {
     options?: SlackMessageSendOptions,
     accountId?: string | null,
   ): Promise<{ ts: string; channelId: string }> {
-    const client = this.getClientForAccount(accountId);
+    const client = this.getOutboundClient(accountId);
     if (!client) {
       throw new Error("Slack client not initialized");
     }