Multiplayer agent harness for work.
import { continueInPrivate } from "./private-continuation.ts";
import { externalSlackNamespace, type ExternalSlackAccess } from "./external-access.ts";
import { registerKeychainApprovalActions } from "./keychain-approvals.ts";
import { registerDeployAccessActions } from "./deploy-access.ts";
import { SlackPluginStartCleanupError } from "../surfaces/slack-runtime.ts";
import { createSlackRateLimitNotice } from "./rate-limit-notice.ts";
import { createSlackHistoryReader } from "./history.ts";
import { reportFailure, swallow, swallowAs } from "../util/errors.ts";
import { createEnvelopeStaging } from "./envelope-staging.ts";
import { createSweeper } from "../util/sweeper.ts";
import bolt from "@slack/bolt";
import { WebClient } from "@slack/web-api";
import { createDeduper, createThreadTracker } from "./lib.ts";
import { installDevIntrospection } from "./dev-introspection.ts";
import { setDefaultBotIdentity, createSurfaceHeaderEnsurer, type SurfaceHeaderClient } from "./delivery.ts";
import {
NO_RETRY,
HISTORY_NO_RETRY,
type SlackPluginConfig,
normalizeSlackApiUrl,
slackAccountConfigsFromEnv,
slackPluginConfigFromEnv,
} from "./config.ts";
import { createTurnFlow } from "./turn-flow.ts";
import { createActorGate, createDenyResponder } from "./allow-from.ts";
import { createAckEmojiPicker } from "./ack-emoji.ts";
import { type BotIdentity, createDirectory } from "./directory.ts";
import { createMirror } from "./mirror.ts";
import { createConversationSerializer } from "./conversation-view.ts";
import { createApprovals } from "./approvals.ts";
import { createTurnHandler } from "./turn-handler.ts";
import { registerSlackEvents } from "./events.ts";
import { createSurfaceContextFulfiller } from "./surface-context.ts";
import { createDeliveryPoller } from "./deliveries.ts";
import { createDeferredAckReceiver } from "./deferred-ack.ts";
import { createHttpEventsReceiver } from "./http-events.ts";
import { parseChannelPage, parseLogLevel } from "./payloads.ts";
import type { SlackCoreClient, SurfaceContextRequest } from "../api/slack-core-client.ts";
import type { AuthTestResponse } from "@slack/web-api";
const { App } = bolt;
export type { SlackCoreClient };
export type { SlackPluginConfig };
export { normalizeSlackApiUrl, slackAccountConfigsFromEnv, slackPluginConfigFromEnv };
const slackAccountClients = new Map<
string,
{
client: any;
teamId: string;
policy?: ExternalSlackAccess;
inFlightRuns?: { add(id: string): void; delete(id: string): void };
}
>();
export async function startSlackPlugin(
cfg: SlackPluginConfig,
core: SlackCoreClient,
): Promise<{ stop(): Promise<void> }> {
const EVENTS_MODE = cfg.eventsMode ?? "socket";
if (!cfg.botToken) {
throw new Error("Slack plugin needs botToken (SLACK_BOT_TOKEN, xoxb-…)");
}
if (!cfg.receiverFactory && EVENTS_MODE === "socket" && !cfg.appToken) {
throw new Error("Slack plugin needs appToken (SLACK_APP_TOKEN, xapp-…) in socket events mode");
}
if (!cfg.receiverFactory && EVENTS_MODE === "http" && (!cfg.signingSecret || !cfg.eventsPort)) {
throw new Error(
"Slack plugin needs signingSecret (SLACK_SIGNING_SECRET) and eventsPort (SLACK_EVENTS_PORT) in http events mode",
);
}
const BOT_TOKEN = cfg.botToken;
const APP_TOKEN = cfg.appToken;
const SLACK_API_URL = cfg.apiUrl ? normalizeSlackApiUrl(cfg.apiUrl) : undefined;
const TRUSTED_FILE_HOST = SLACK_API_URL ? new URL(SLACK_API_URL).hostname : undefined;
const CLIENT_OPTIONS = {
...NO_RETRY,
attachOriginalToWebAPIRequestError: false,
...(SLACK_API_URL ? { slackApiUrl: SLACK_API_URL } : {}),
} as const;
const IDENTITY_TOKENS: Record<string, string | undefined> = {
copilot: cfg.copilotBotToken,
};
const identityClients = new Map<string, WebClient>();
function clientForIdentity(identity: string): WebClient {
const token = IDENTITY_TOKENS[identity];
if (!token) throw new Error(`no token for post identity "${identity}" (set its *_BOT_TOKEN env)`);
let c = identityClients.get(identity);
if (!c) {
c = new WebClient(token, { ...CLIENT_OPTIONS });
identityClients.set(identity, c);
}
return c;
}
let stopped = false;
const CORE_SINGLETON = cfg.coreSingleton !== false;
const ACCOUNT_LABEL = cfg.accountId ?? "default";
const ENVELOPE_REPLAY_SWEEP_MS = 60_000;
const ENVELOPE_REPLAY_RETRY_NUM = 99;
const configuredActorGate = createActorGate(cfg.allowFrom);
const allowActor = cfg.externalAccess
? (actor: import("./identity.ts").ActorAssertion) =>
!actor.isExternalGuest && !actor.isBot && (!configuredActorGate || configuredActorGate(actor))
: configuredActorGate;
const denyResponder = allowActor ? createDenyResponder(cfg.denyMessage) : undefined;
const ids: BotIdentity = {
ownTeamId: "",
botUserId: "",
ownBotId: "",
botHandle: "",
ownWorkspaceUrl: "",
identityMode: cfg.identityEmail === "0" ? "slack-id" : "email",
};
const ACK_OVERRIDE_CACHE_MS = 60_000;
let ackOverrideCache: { names: string[] | null; fetchedAt: number } | undefined;
function ackEmojiOverride(): readonly string[] | null {
if (!ackOverrideCache || Date.now() - ackOverrideCache.fetchedAt >= ACK_OVERRIDE_CACHE_MS) {
const prev = ackOverrideCache;
ackOverrideCache = { names: prev?.names ?? null, fetchedAt: Date.now() };
core
.ackEmojiOverride()
.then((names) => {
ackOverrideCache = { names: names?.length ? names : null, fetchedAt: Date.now() };
})
.catch((err) => {
swallow("slack: ack-emoji override read", err);
});
}
return ackOverrideCache.names;
}
const EXTERNAL_PARTICIPANTS_CACHE_MS = 30_000;
let externalParticipantsCache: { on: boolean; fetchedAt: number } | undefined;
async function externalParticipantsEnabled(): Promise<boolean> {
if (cfg.externalAccess) return true;
if (
externalParticipantsCache &&
Date.now() - externalParticipantsCache.fetchedAt < EXTERNAL_PARTICIPANTS_CACHE_MS
) {
return externalParticipantsCache.on;
}
try {
const on = await core.externalSlackParticipants();
externalParticipantsCache = { on, fetchedAt: Date.now() };
return on;
} catch (err) {
swallow("slack: surface-config read", err);
return externalParticipantsCache?.on ?? false;
}
}
const stagingAccount = cfg.installationId ? `${ACCOUNT_LABEL}:${cfg.installationId}` : ACCOUNT_LABEL;
const staging = core.stagedEnvelopes
? createEnvelopeStaging(core.stagedEnvelopes, { account: stagingAccount })
: undefined;
const receiver = () => {
if (cfg.receiverFactory) return cfg.receiverFactory(staging);
return EVENTS_MODE === "http"
? createHttpEventsReceiver({
signingSecret: cfg.signingSecret!,
port: cfg.eventsPort!,
...(cfg.ackCapMs !== undefined ? { capMs: cfg.ackCapMs } : {}),
...(staging ? { staging } : {}),
})
: createDeferredAckReceiver({
appToken: APP_TOKEN!,
...(cfg.logLevel ? { logLevel: cfg.logLevel } : {}),
...(SLACK_API_URL ? { slackApiUrl: SLACK_API_URL } : {}),
...(cfg.ackCapMs !== undefined ? { capMs: cfg.ackCapMs } : {}),
...(staging ? { staging } : {}),
});
};
const app = new App({
token: BOT_TOKEN,
ignoreSelf: false,
receiver: receiver(),
logLevel: parseLogLevel(cfg.logLevel),
clientOptions: { ...CLIENT_OPTIONS },
});
if (cfg.externalAccess)
app.use(async ({ body, next }) => {
const envelope = body as unknown as { team_id?: string; team?: { id?: string } };
const teamId = envelope.team_id ?? envelope.team?.id;
if (!ids.ownTeamId || teamId !== ids.ownTeamId) return;
await next();
});
const replaySweeper = staging
? createSweeper(
() =>
core.holdEnvelopeReplay(stagingAccount, () =>
staging.sweep((body, ackGate) =>
app.processEvent({
body,
ack: async () => {},
retryNum: ENVELOPE_REPLAY_RETRY_NUM,
customProperties: { ackGate },
}),
),
),
ENVELOPE_REPLAY_SWEEP_MS,
{ label: "slack envelope replay" },
)
: undefined;
if (CORE_SINGLETON) setDefaultBotIdentity(cfg.botIdentity);
const devIntrospection = installDevIntrospection(
app,
cfg.devIntrospection ? { enabled: true, port: cfg.devIntrospection.port } : {},
);
const deduper = createDeduper(1000);
const threads = createThreadTracker();
const flow = createTurnFlow(core);
const ackEmoji = createAckEmojiPicker(core, { candidatesOverride: ackEmojiOverride });
const directory = createDirectory({
...(cfg.externalAccess ? { externalAccess: cfg.externalAccess } : {}),
core,
ids,
coreSingleton: CORE_SINGLETON && !cfg.externalAccess,
...(cfg.userSnapshotTtlMs ? { userSnapshotTtlMs: cfg.userSnapshotTtlMs } : {}),
...(cfg.channelMembersTtlMs ? { channelMembersTtlMs: cfg.channelMembersTtlMs } : {}),
...(cfg.maxPrivateChannels ? { maxPrivateChannels: cfg.maxPrivateChannels } : {}),
...(cfg.userCacheTtlMs ? { userCacheTtlMs: cfg.userCacheTtlMs } : {}),
});
const mirror = cfg.externalAccess
? { pushSurfaceEvents: async () => {}, mirrorMessageEvent: async () => {} }
: createMirror({ core, ids, directory, externalParticipantsEnabled });
const historyRateLimitOptions = {
managed: Boolean(cfg.installationId && cfg.sharedServiceUrl?.trim()),
...(cfg.webUiPublicUrl ? { setupUrl: `${cfg.webUiPublicUrl.replace(/\/$/, "")}/admin/?setup=slack` } : {}),
};
const rateLimitNotice = createSlackRateLimitNotice({
...historyRateLimitOptions,
client: new WebClient(BOT_TOKEN, { ...CLIENT_OPTIONS, ...HISTORY_NO_RETRY, timeout: 5000 }),
});
const historyApi = new WebClient(BOT_TOKEN, { ...CLIENT_OPTIONS, ...HISTORY_NO_RETRY });
const historyClient = {
conversations: Object.fromEntries(
(["history", "replies"] as const).map((method) => [
method,
async (args: any) => {
try {
return await historyApi.conversations[method](args);
} catch (error) {
await rateLimitNotice.observe(error);
throw error;
}
},
]),
) as Pick<typeof historyApi.conversations, "history" | "replies">,
};
const readHistory = createSlackHistoryReader({
historyLimit: cfg.historyLimit,
core,
ids,
historyClient,
source: cfg.contextSource ?? "live",
...historyRateLimitOptions,
});
const serializer = createConversationSerializer({
readHistory,
historyRateLimitOptions,
ids,
directory,
externalParticipantsEnabled,
...(cfg.recentMessages ? { recentMessages: cfg.recentMessages } : {}),
});
const approvals = createApprovals({ core, flow, directory, threads, externalAccess: !!cfg.externalAccess });
registerKeychainApprovalActions(app, { core, directory, webUiPublicUrl: cfg.webUiPublicUrl });
registerDeployAccessActions(app, { core, directory });
const ensureHeader = createSurfaceHeaderEnsurer({
headerFacts: (scope) => core.surfaceHeaderFacts(scope as Parameters<typeof core.surfaceHeaderFacts>[0]),
channelPinEnabled: (scope) =>
core.channelHeaderPinEnabled(scope as Parameters<typeof core.channelHeaderPinEnabled>[0]),
webUiPublicUrl: cfg.webUiPublicUrl,
ids,
});
if (CORE_SINGLETON)
core.onScopeModelChanged((scope) => {
const channel = scope.startsWith("channel:") ? scope.slice("channel:".length) : "";
if (channel) ensureHeader(app.client as unknown as SurfaceHeaderClient, channel, scope, "channel");
});
if (CORE_SINGLETON)
core.onChannelHeaderPinChanged((scope) => {
const channel = scope.startsWith("channel:") ? scope.slice("channel:".length) : "";
if (channel) {
ensureHeader(app.client as unknown as SurfaceHeaderClient, channel, scope, "channel", { pinNew: true });
return;
}
if (!scope.startsWith("org:")) return;
// The org-wide default changed: re-ensure every channel the bot is in. The
// ensurer re-reads each scope's effective setting, so explicit per-channel
// overrides come out unchanged.
void (async () => {
try {
for await (const res of app.client.paginate("conversations.list", {
types: "public_channel,private_channel",
exclude_archived: true,
limit: 1000,
})) {
for (const c of parseChannelPage(res)) {
if (!c?.id || !c.is_member) continue;
ensureHeader(app.client as unknown as SurfaceHeaderClient, c.id, `channel:${c.id}`, "channel", {
pinNew: true,
});
}
}
} catch (err) {
reportFailure("slack: channel header default sweep", err);
}
})();
});
const statusClient = new WebClient(BOT_TOKEN, {
...CLIENT_OPTIONS,
timeout: 5_000,
rejectRateLimitedCalls: true,
});
const statusAccount = () => `${ids.ownTeamId}:${ids.botUserId}`;
let statusSync: Promise<void> | undefined;
const reconcileStatus = () => {
statusSync ??= core.sessionStatus
?.reconcile(statusClient, statusAccount())
.catch(swallowAs("slack: session status reconciliation", undefined))
.finally(() => {
statusSync = undefined;
});
return statusSync;
};
const statusSweep = createSweeper(reconcileStatus, 60_000, { label: "slack session status", immediate: true });
const handler = createTurnHandler({
accountId: ACCOUNT_LABEL,
...(cfg.externalAccess ? { externalAccess: cfg.externalAccess } : {}),
continuePrivate: (runId, task) => continueInPrivate(core, runId, task, (id) => slackAccountClients.get(id)),
onEngaged: (runId, channel, threadTs) => {
void core.sessionStatus
?.start(statusClient, statusAccount(), runId, channel, threadTs)
.catch(swallowAs("slack: session status start", undefined))
.finally(() => {
void reconcileStatus();
});
},
onSettled: () => {
void reconcileStatus();
},
rateLimitNotice,
readHistory,
core,
flow,
directory,
mirror,
serializer,
ackEmoji,
ackEmojiCandidates: ackEmojiOverride,
ids,
threads,
deduper,
externalParticipantsEnabled,
...(allowActor ? { allowActor } : {}),
...(devIntrospection ? { markEvent: () => devIntrospection.markEvent() } : {}),
botToken: BOT_TOKEN,
...(TRUSTED_FILE_HOST ? { trustedFileHost: TRUSTED_FILE_HOST } : {}),
ensureHeader,
});
approvals.registerActions(app);
const inboxMessage = (
client: unknown,
msg: {
channel: string;
ts: string;
threadTs?: string;
text?: string;
senderSlackId?: string;
isDirectMessage: boolean;
},
): void => {
void (async () => {
let senderEmail: string | undefined;
if (msg.senderSlackId) {
try {
const actor = await directory.classifyActor(client, msg.senderSlackId);
if (actor.externalId.includes("@")) senderEmail = actor.externalId;
} catch (e) {
swallow("slack: classify inbox message sender", e);
senderEmail = undefined;
}
}
await core.inboxSlackMessage({
channel: msg.channel,
ts: msg.ts,
isDirectMessage: msg.isDirectMessage,
...(msg.threadTs ? { threadTs: msg.threadTs } : {}),
...(msg.text ? { text: msg.text } : {}),
...(senderEmail ? { senderEmail } : {}),
});
})().catch((e) => swallow("slack: forward message to inbox", e));
};
registerSlackEvents(app, {
handler,
mirror,
directory,
ids,
deduper,
...(!cfg.externalAccess ? { inboxMessage } : {}),
...(allowActor ? { allowActor } : {}),
...(denyResponder ? { denyResponder } : {}),
...(cfg.webUiPublicUrl ? { webUiPublicUrl: cfg.webUiPublicUrl } : {}),
...((cfg.contextSource ?? "live") === "mirror"
? { backfillHistory: (client: unknown, channel: string) => readHistory(client, channel) }
: {}),
ensureHeader,
});
const surfaceContext = createSurfaceContextFulfiller({
historyLimit: cfg.historyLimit,
rateLimitNotice,
historyClient,
readHistory,
historyRateLimitOptions,
core,
directory,
serializer,
botToken: BOT_TOKEN,
...(TRUSTED_FILE_HOST ? { trustedFileHost: TRUSTED_FILE_HOST } : {}),
...(cfg.userToken ? { userToken: cfg.userToken } : {}),
clientOptions: CLIENT_OPTIONS,
});
const deliveries = createDeliveryPoller({
clientForAccount: (id, teamId) => {
const account = slackAccountClients.get(id);
if (!account || (teamId && account.teamId !== teamId)) return undefined;
return account.client;
},
externalNamespace: (id) => {
const account = slackAccountClients.get(id);
return account?.policy ? externalSlackNamespace(account.teamId, account.policy) : undefined;
},
continuePrivate: (runId, task) => continueInPrivate(core, runId, task, (id) => slackAccountClients.get(id)),
core,
flow,
threads,
clientForIdentity,
webUiPublicUrl: cfg.webUiPublicUrl,
});
let auth: AuthTestResponse;
try {
auth = await app.client.auth.test();
ids.ownTeamId = auth.team_id ?? "";
ids.botUserId = auth.user_id ?? "";
ids.ownBotId = auth.bot_id ?? "";
ids.botHandle = typeof auth.user === "string" ? auth.user : "";
ids.ownWorkspaceUrl = typeof auth.url === "string" ? auth.url.replace(/\/+$/, "") : "";
if (!ids.ownTeamId || !ids.botUserId) {
throw new Error("auth.test returned no team_id/user_id — refusing to start (cannot classify members safely)");
}
if (!cfg.identityEmail) {
ids.identityMode = await directory.resolveAutoIdentityMode(app.client);
if (ids.identityMode === "slack-id") {
console.warn(
"[slack] no member emails visible (users:read.email scope missing?) — keying principals on Slack ids; add the scope or set SLACK_IDENTITY_EMAIL=1 to force email keying",
);
}
}
await directory.getUserSnapshot(app.client);
if (slackAccountClients.has(ACCOUNT_LABEL)) throw new Error(`Duplicate Slack account id: ${ACCOUNT_LABEL}`);
slackAccountClients.set(ACCOUNT_LABEL, {
client: app.client,
inFlightRuns: flow.inFlightRuns,
teamId: ids.ownTeamId,
...(cfg.externalAccess ? { policy: cfg.externalAccess } : {}),
});
await app.start();
replaySweeper?.start();
} catch (err) {
if (slackAccountClients.get(ACCOUNT_LABEL)?.client === app.client) slackAccountClients.delete(ACCOUNT_LABEL);
stopped = true;
await devIntrospection?.close().catch(swallowAs("slack: dev-introspection close on failed start", undefined));
try {
await app.stop();
} catch (cleanupError) {
throw new SlackPluginStartCleanupError(err, cleanupError, async () => {
await app.stop();
});
}
throw err;
}
devIntrospection?.ready({ connectedAs: auth.user ?? "", botUserId: ids.botUserId, teamId: ids.ownTeamId });
console.log(
`[slack-plugin] account ${ACCOUNT_LABEL} connected as @${auth.user} (bot ${ids.botUserId}) in team ${auth.team} (${ids.ownTeamId}); in-process core`,
);
ackEmoji.refreshAckEmoji(app.client);
ackEmojiOverride();
const EMOJI_CATALOG_REFRESH_MS = 6 * 60 * 60_000;
const publishEmojiCatalog = (): void => {
if (stopped) return;
void Promise.resolve(app.client.emoji.list())
.then((res: { emoji?: Record<string, string> }) => {
const emoji: Record<string, string> = {};
for (const [name, url] of Object.entries(res.emoji ?? {})) {
if (typeof url === "string" && !url.startsWith("alias:")) emoji[name] = url;
}
return core.publishEmojiCatalog(emoji);
})
.catch(swallowAs("slack: emoji catalog publish", undefined));
};
let emojiCatalogTimer: NodeJS.Timeout | undefined;
if (CORE_SINGLETON) {
publishEmojiCatalog();
emojiCatalogTimer = setInterval(publishEmojiCatalog, EMOJI_CATALOG_REFRESH_MS);
}
let deliveriesPollInFlight = false;
let deliveriesPollAgain = false;
let followerRetry: ReturnType<typeof setTimeout> | undefined;
const drainDeliveries = (): void => {
if (stopped) return;
if (deliveriesPollInFlight) {
deliveriesPollAgain = true;
return;
}
deliveriesPollInFlight = true;
void deliveries
.pollDeliveries(app.client)
.then((ranAsLeader) => {
if (!ranAsLeader && !stopped && !followerRetry) {
followerRetry = setTimeout(() => {
followerRetry = undefined;
drainDeliveries();
}, 5_000);
followerRetry.unref?.();
}
})
.catch(swallowAs("slack: delivery drain", undefined))
.finally(() => {
deliveriesPollInFlight = false;
if (deliveriesPollAgain) {
deliveriesPollAgain = false;
drainDeliveries();
}
});
};
statusSweep.start();
let unsubscribeDeliveries = (): void => {};
let deliveriesTimer: NodeJS.Timeout | undefined;
if (CORE_SINGLETON || cfg.externalAccess) {
unsubscribeDeliveries = core.onDeliveryEnqueued(drainDeliveries);
deliveriesTimer = setInterval(drainDeliveries, 60_000);
drainDeliveries();
}
const contextRequestsInFlight = new Set<string>();
const serviceContextRequest = (r: SurfaceContextRequest): void => {
if (stopped || !r?.id || contextRequestsInFlight.has(r.id)) return;
contextRequestsInFlight.add(r.id);
void surfaceContext
.fulfillSurfaceContext(app.client, r)
.catch(swallowAs("slack: context request fulfillment", undefined))
.finally(() => contextRequestsInFlight.delete(r.id));
};
let unsubscribeContextRequests = (): void => {};
if (CORE_SINGLETON) {
unsubscribeContextRequests = core.onContextRequest(serviceContextRequest);
void core
.pendingContextRequests()
.then((pending) => pending.forEach(serviceContextRequest))
.catch(swallowAs("slack: context request drain", undefined));
}
return {
async stop(): Promise<void> {
if (stopped) {
await replaySweeper?.stop();
await app.stop();
return;
}
stopped = true;
if (slackAccountClients.get(ACCOUNT_LABEL)?.client === app.client) slackAccountClients.delete(ACCOUNT_LABEL);
await statusSweep.stop();
await replaySweeper?.stop();
if (deliveriesTimer) clearInterval(deliveriesTimer);
if (emojiCatalogTimer) clearInterval(emojiCatalogTimer);
if (followerRetry) clearTimeout(followerRetry);
unsubscribeDeliveries();
unsubscribeContextRequests();
try {
await app.stop();
} finally {
await devIntrospection?.close();
}
},
};
}