crewly 1.13.1 → 1.14.0

package/dist/backend/backend/src/services/slack/slack-team-channel.service.js

@@ -0,0 +1,821 @@
+/**
+ * Slack Team Channel Service
+ *
+ * Makes a Crewly team a first-class Slack participant: one Slack channel per
+ * team, backed by one chat-v2 huddle whose roster is the team's members.
+ *
+ *   Slack #team-alpha  ──inbound──▶  chat-v2 huddle  ──dispatcher──▶ every member
+ *          ▲                                                           (@'d must reply)
+ *          └──outbound, posted as the agent (username/icon)──  reply-channel
+ *
+ * Responsibilities:
+ *  - Mapping store (`~/.crewly/slack-team-channels.json`): create/link/unlink.
+ *  - Lifecycle sync via `StorageService.onStorageEvent`: newly created team →
+ *    channel + huddle + welcome (existing teams are opted in from Settings);
+ *    member change → roster; archive/delete → archive both.
+ *  - Inbound routing for mapped channels (called by the orchestrator bridge):
+ *    persist into the huddle with Slack thread correlation, resolve `@name`
+ *    mentions, dispatch, answer typos with "did you mean".
+ *  - Outbound mirror: agent messages recorded in a mapped huddle are posted to
+ *    the Slack thread under the agent's own name and icon.
+ *
+ * Nothing here is orchestrator-specific — the orchestrator keeps handling DMs
+ * and unmapped channels exactly as before.
+ *
+ * @module services/slack/slack-team-channel.service
+ */
+import * as path from 'path';
+import { promises as fs } from 'fs';
+import { getCrewlyHomePath } from '../core/crewly-home.utils.js';
+import { atomicWriteJson, safeReadJson } from '../../utils/file-io.utils.js';
+import { LoggerService } from '../core/logger.service.js';
+import { SLACK_TEAM_CHANNEL_CONSTANTS } from '../../constants.js';
+import { resolveSlackMentions } from './slack-mention-resolver.js';
+const EMPTY_STORE = {
+    version: 1,
+    autoCreate: true,
+    channelPrefix: '',
+    mappings: [],
+};
+/**
+ * Turn a team name into a Slack-legal channel name: lower-case, letters of
+ * any script, digits, `-` and `_`; whitespace and punctuation collapse to
+ * `-`; at most 80 characters.
+ *
+ * @param teamName - The team display name
+ * @param prefix - Optional prefix (e.g. `crew-`), sanitised the same way
+ * @returns The channel name without `#`, never empty
+ *
+ * @example
+ * slackChannelNameFor('Growth Team!', 'crew-') // 'crew-growth-team'
+ */
+export function slackChannelNameFor(teamName, prefix = '') {
+    const clean = (s) => s
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}_-]+/gu, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/^-+|-+$/g, '');
+    const body = clean(teamName) || 'team';
+    const p = clean(prefix);
+    const joined = p ? `${p}-${body}` : body;
+    return joined.slice(0, SLACK_TEAM_CHANNEL_CONSTANTS.MAX_CHANNEL_NAME_LENGTH).replace(/-+$/g, '') || 'team';
+}
+/**
+ * The agents that take part in a team channel: every member except the
+ * orchestrator role (the orc is not a huddle participant — the point of
+ * team channels is talking to the team without it).
+ *
+ * @param team - The team
+ * @returns Members with a session name, orchestrator excluded
+ */
+export function teamChannelMembers(team) {
+    return (team.members ?? []).filter((m) => !!m.sessionName && m.role !== 'orchestrator');
+}
+/**
+ * Pick the Slack identity an agent posts under.
+ *
+ * `username` is the member's display name. The icon is the member avatar
+ * when it is a Slack emoji name (`:rocket:`) or a URL; otherwise a per-role
+ * emoji, then the default robot.
+ *
+ * @param member - The team member, or undefined when the session is unknown
+ * @param sessionName - Fallback display name
+ * @returns The identity fields for SlackOutgoingMessage
+ */
+export function slackIdentityFor(member, sessionName) {
+    const username = member?.name?.trim() || sessionName;
+    const avatar = member?.avatar?.trim() ?? '';
+    if (/^:[a-z0-9_+-]+:$/i.test(avatar)) {
+        return { username, iconEmoji: avatar };
+    }
+    if (/^https?:\/\//i.test(avatar)) {
+        return { username, iconUrl: avatar };
+    }
+    const roleEmoji = member?.role
+        ? SLACK_TEAM_CHANNEL_CONSTANTS.ROLE_ICON_EMOJI[member.role]
+        : undefined;
+    return { username, iconEmoji: roleEmoji ?? SLACK_TEAM_CHANNEL_CONSTANTS.DEFAULT_ICON_EMOJI };
+}
+/**
+ * Service — see module docs.
+ */
+export class SlackTeamChannelService {
+    logger;
+    deps;
+    storePath;
+    store = null;
+    loading = null;
+    unsubscribeStorage = null;
+    unsubscribeIdentity = null;
+    onChatMessage = (dto) => {
+        void this.mirrorOutbound(dto);
+    };
+    started = false;
+    /** Per-team serialisation so two team-saved events cannot create two channels. */
+    inflight = new Map();
+    constructor(deps) {
+        this.deps = deps;
+        this.storePath =
+            deps.storePath ?? path.join(getCrewlyHomePath(), SLACK_TEAM_CHANNEL_CONSTANTS.STORE_FILENAME);
+        this.logger = LoggerService.getInstance().createComponentLogger('SlackTeamChannels');
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * Subscribe to team lifecycle events and chat-v2 agent messages. Idempotent.
+     * Safe to call before Slack is connected — every Slack call is guarded by
+     * `isConnected()` at the time it runs.
+     */
+    async start() {
+        if (this.started)
+            return;
+        await this.load();
+        this.unsubscribeStorage = this.deps.storage.onStorageEvent((event) => this.handleStorageEvent(event));
+        this.deps.chat.on('chat_message', this.onChatMessage);
+        // A freshly installed agent bot gets invited into every channel of a
+        // team it belongs to, so it can post there under its own identity.
+        this.unsubscribeIdentity =
+            this.deps.identities?.onInstalled((record) => {
+                void this.inviteInstalledEverywhere(record.agentSession);
+            }) ?? null;
+        this.started = true;
+        this.logger.info('Slack team channels started', {
+            mappings: this.store?.mappings.length ?? 0,
+            autoCreate: this.store?.autoCreate ?? true,
+        });
+    }
+    /** Undo {@link start}. */
+    stop() {
+        if (!this.started)
+            return;
+        this.unsubscribeStorage?.();
+        this.unsubscribeStorage = null;
+        this.unsubscribeIdentity?.();
+        this.unsubscribeIdentity = null;
+        this.deps.chat.off('chat_message', this.onChatMessage);
+        this.started = false;
+    }
+    // -------------------------------------------------------------------------
+    // Store
+    // -------------------------------------------------------------------------
+    /** Read the store from disk once; later calls return the cached copy. */
+    async load() {
+        if (this.store)
+            return this.store;
+        if (!this.loading) {
+            this.loading = safeReadJson(this.storePath, EMPTY_STORE).then((raw) => {
+                const store = {
+                    version: 1,
+                    autoCreate: raw?.autoCreate !== false,
+                    channelPrefix: typeof raw?.channelPrefix === 'string' ? raw.channelPrefix : '',
+                    mappings: Array.isArray(raw?.mappings) ? raw.mappings.filter(isMapping) : [],
+                };
+                this.store = store;
+                return store;
+            });
+        }
+        return this.loading;
+    }
+    async save() {
+        const store = await this.load();
+        await fs.mkdir(path.dirname(this.storePath), { recursive: true });
+        await atomicWriteJson(this.storePath, store);
+    }
+    /**
+     * Current settings (auto-create + prefix).
+     *
+     * @returns The settings half of the store
+     */
+    async getSettings() {
+        const s = await this.load();
+        return { autoCreate: s.autoCreate, channelPrefix: s.channelPrefix };
+    }
+    /**
+     * Update settings. Only the keys present in `patch` change.
+     *
+     * @param patch - Partial settings
+     * @returns The settings after the update
+     */
+    async updateSettings(patch) {
+        const s = await this.load();
+        if (typeof patch.autoCreate === 'boolean')
+            s.autoCreate = patch.autoCreate;
+        if (typeof patch.channelPrefix === 'string')
+            s.channelPrefix = patch.channelPrefix.trim();
+        await this.save();
+        return this.getSettings();
+    }
+    /**
+     * All mappings, in creation order.
+     *
+     * @returns Copies of every mapping
+     */
+    async listMappings() {
+        const s = await this.load();
+        return s.mappings.map((m) => ({ ...m }));
+    }
+    /**
+     * Mapping for a team, if any. Synchronous read of the cached store — the
+     * bridge calls this on every inbound Slack message.
+     *
+     * @param teamId - Crewly team id
+     * @returns The mapping, or null
+     */
+    findByTeamId(teamId) {
+        return this.store?.mappings.find((m) => m.teamId === teamId) ?? null;
+    }
+    /**
+     * Mapping for a Slack channel, if any (sync, cached store).
+     *
+     * @param slackChannelId - Slack channel id
+     * @returns The mapping, or null
+     */
+    findBySlackChannelId(slackChannelId) {
+        return this.store?.mappings.find((m) => m.slackChannelId === slackChannelId) ?? null;
+    }
+    /**
+     * Mapping for a chat-v2 huddle, if any (sync, cached store).
+     *
+     * @param chatChannelId - chat-v2 channel id
+     * @returns The mapping, or null
+     */
+    findByChatChannelId(chatChannelId) {
+        return this.store?.mappings.find((m) => m.chatChannelId === chatChannelId) ?? null;
+    }
+    /**
+     * Every non-archived team with its mapping (or null). One call for the
+     * Settings UI.
+     *
+     * @returns Teams in storage order
+     */
+    async listTeamsWithMappings() {
+        await this.load();
+        const teams = await this.deps.storage.getTeams();
+        return teams
+            .filter((t) => !t.archived)
+            .map((t) => ({
+            teamId: t.id,
+            teamName: t.name,
+            memberCount: teamChannelMembers(t).length,
+            mapping: this.findByTeamId(t.id),
+        }));
+    }
+    /**
+     * Look a team up by id.
+     *
+     * @param teamId - Crewly team id
+     * @returns The team, or null
+     */
+    async getTeam(teamId) {
+        const teams = await this.deps.storage.getTeams();
+        return teams.find((t) => t.id === teamId) ?? null;
+    }
+    // -------------------------------------------------------------------------
+    // Create / link / unlink
+    // -------------------------------------------------------------------------
+    /**
+     * Make sure `team` has a Slack channel and a huddle. Creates the Slack
+     * channel (or reuses one with the same name) unless `slackChannelId`
+     * names an existing channel to link. Idempotent: an existing mapping is
+     * returned after a roster sync.
+     *
+     * @param team - The team
+     * @param options - `slackChannelId` to link an existing channel instead of creating
+     * @returns The mapping
+     * @throws Error when Slack is not connected or the channel cannot be created/found
+     */
+    async ensureTeamChannel(team, options = {}) {
+        return this.serialised(team.id, async () => {
+            await this.load();
+            const existing = this.findByTeamId(team.id);
+            if (existing) {
+                await this.syncTeamMembers(team, existing);
+                return existing;
+            }
+            if (!this.deps.slack.isConnected()) {
+                throw new Error('Slack is not connected');
+            }
+            let channel;
+            let autoCreated;
+            if (options.slackChannelId) {
+                const info = await this.deps.slack.getChannelInfo(options.slackChannelId);
+                if (!info)
+                    throw new Error(`Slack channel not found: ${options.slackChannelId}`);
+                if (info.isArchived)
+                    throw new Error(`Slack channel is archived: ${info.name}`);
+                await this.deps.slack.joinChannel(info.id).catch((err) => {
+                    // Private channels cannot be joined; the bot must be invited by a human.
+                    this.logger.warn('Could not join linked channel — invite the bot manually', {
+                        channel: info.name,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                });
+                channel = info;
+                autoCreated = false;
+            }
+            else {
+                const store = await this.load();
+                channel = await this.deps.slack.createChannel(slackChannelNameFor(team.name, store.channelPrefix));
+                autoCreated = true;
+                const purpose = team.description?.trim() || `Crewly team "${team.name}"`;
+                await this.deps.slack.setChannelPurpose(channel.id, purpose).catch((err) => {
+                    this.logger.debug('setPurpose failed (non-critical)', {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                });
+            }
+            const members = teamChannelMembers(team);
+            const huddle = this.deps.chat.createHuddle({
+                name: `#${channel.name}`,
+                purpose: `Slack team channel for ${team.name}`,
+                // A brand-new team may have no members yet; keep the huddle valid
+                // with a placeholder that the first roster sync replaces.
+                memberSessions: members.length > 0 ? members.map((m) => m.sessionName) : [`team:${team.id}`],
+                principal: { userId: 'system', source: 'oss' },
+            });
+            const mapping = {
+                teamId: team.id,
+                slackChannelId: channel.id,
+                slackChannelName: channel.name,
+                chatChannelId: huddle.id,
+                createdAt: (this.deps.now?.() ?? new Date()).toISOString(),
+                autoCreated,
+            };
+            const store = await this.load();
+            store.mappings.push(mapping);
+            await this.save();
+            this.logger.info('Team channel ready', {
+                teamId: team.id,
+                teamName: team.name,
+                slackChannel: `#${channel.name}`,
+                huddle: huddle.id,
+                members: members.length,
+                autoCreated,
+            });
+            await this.postWelcome(mapping, team, members);
+            await this.ensureIdentities(team, mapping);
+            return mapping;
+        });
+    }
+    /**
+     * Remove a team's mapping. Optionally archives the Slack channel; the
+     * huddle is always archived (it is Crewly's own object).
+     *
+     * @param teamId - Crewly team id
+     * @param options - `archiveSlackChannel` (default false — leave the humans' channel alone)
+     * @returns True when a mapping existed
+     */
+    async unlinkTeam(teamId, options = {}) {
+        return this.serialised(teamId, async () => {
+            const store = await this.load();
+            const idx = store.mappings.findIndex((m) => m.teamId === teamId);
+            if (idx < 0)
+                return false;
+            const [mapping] = store.mappings.splice(idx, 1);
+            await this.save();
+            this.deps.chat.archiveChannelForBridge(mapping.chatChannelId);
+            if (options.archiveSlackChannel && this.deps.slack.isConnected()) {
+                await this.deps.slack.archiveChannel(mapping.slackChannelId).catch((err) => {
+                    this.logger.warn('Could not archive Slack channel', {
+                        channel: mapping.slackChannelName,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                });
+            }
+            this.logger.info('Team channel unlinked', {
+                teamId,
+                slackChannel: `#${mapping.slackChannelName}`,
+                archivedSlack: !!options.archiveSlackChannel,
+            });
+            return true;
+        });
+    }
+    /**
+     * Reconcile the huddle roster with the team's current members.
+     *
+     * @param team - The team
+     * @param mapping - Its mapping (looked up when omitted)
+     * @returns The roster diff, or null when the team is unmapped
+     */
+    async syncTeamMembers(team, mapping) {
+        await this.load();
+        const m = mapping ?? this.findByTeamId(team.id);
+        if (!m)
+            return null;
+        const sessions = teamChannelMembers(team).map((x) => x.sessionName);
+        if (sessions.length === 0)
+            return { added: [], removed: [] };
+        const diff = this.deps.chat.setHuddleMembers(m.chatChannelId, sessions);
+        if (diff.added.length || diff.removed.length) {
+            this.logger.info('Team channel roster synced', { teamId: team.id, ...diff });
+        }
+        await this.ensureIdentities(team, m);
+        return diff;
+    }
+    // -------------------------------------------------------------------------
+    // Team lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * React to a storage event. Public so the bridge/tests can drive it
+     * directly; `start()` subscribes it.
+     *
+     * @param event - The storage event
+     */
+    async handleStorageEvent(event) {
+        try {
+            if (event.kind === 'team-deleted') {
+                await this.unlinkTeam(event.teamId, { archiveSlackChannel: true });
+                return;
+            }
+            const team = event.team;
+            await this.load();
+            const mapping = this.findByTeamId(team.id);
+            if (team.archived) {
+                if (mapping)
+                    await this.unlinkTeam(team.id, { archiveSlackChannel: true });
+                return;
+            }
+            if (mapping) {
+                await this.syncTeamMembers(team, mapping);
+                return;
+            }
+            // Auto-create only for teams that were just created. Every status
+            // write (activity monitor, registration) also lands here as a
+            // team-saved event; turning each of those into a Slack channel would
+            // carpet the workspace with channels for teams that pre-date this
+            // feature. Existing teams get a channel from Settings → Team Channels.
+            if (!event.created)
+                return;
+            const settings = await this.getSettings();
+            if (!settings.autoCreate || !this.deps.slack.isConnected())
+                return;
+            await this.ensureTeamChannel(team);
+        }
+        catch (err) {
+            this.logger.warn('Team lifecycle sync failed', {
+                kind: event.kind,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Inbound (Slack → huddle)
+    // -------------------------------------------------------------------------
+    /**
+     * Route an inbound Slack message that arrived in a mapped channel.
+     *
+     * 1. Persist into the huddle: a top-level Slack message becomes a chat-v2
+     *    root carrying `slackThreadTs = ts`; a Slack thread reply is filed
+     *    under the root that carries `slackThreadTs = thread_ts` (or becomes
+     *    a root itself when that root predates the mapping).
+     * 2. Resolve `@name` tokens against the team's members → `mentions`.
+     * 3. Dispatch through the chat-v2 dispatcher (`huddle-broadcast`) with
+     *    the thread id and the `reply-channel` hint.
+     * 4. Answer unknown `@names` in-thread with suggestions.
+     *
+     * @param message - The inbound Slack message
+     * @returns The routing result, or null when the channel is not mapped
+     */
+    async routeInbound(message) {
+        await this.load();
+        const mapping = this.findBySlackChannelId(message.channelId);
+        if (!mapping)
+            return null;
+        const channel = this.deps.chat.getChannelForBridge(mapping.chatChannelId);
+        if (!channel || channel.archivedAt) {
+            this.logger.warn('Mapped huddle missing or archived — dropping mapping', {
+                teamId: mapping.teamId,
+                huddle: mapping.chatChannelId,
+            });
+            await this.unlinkTeam(mapping.teamId);
+            return null;
+        }
+        const team = (await this.deps.storage.getTeams()).find((t) => t.id === mapping.teamId);
+        const members = team ? teamChannelMembers(team) : [];
+        if (this.deps.identities)
+            await this.deps.identities.load();
+        const candidates = members.map((m) => ({
+            name: m.name,
+            sessionName: m.sessionName,
+            botUserId: this.deps.identities?.get(m.sessionName)?.botUserId,
+        }));
+        const resolved = resolveSlackMentions(message.text ?? '', candidates);
+        // Thread correlation.
+        const slackThreadTs = message.threadTs || message.ts;
+        let threadId;
+        if (message.threadTs) {
+            const root = this.deps.chat.findSlackThreadRoot(mapping.chatChannelId, message.threadTs);
+            threadId = root?.id;
+        }
+        const senderId = message.user?.name || message.userId || 'slack-user';
+        const { message: persisted } = this.deps.chat.recordTurn({
+            channelId: mapping.chatChannelId,
+            senderType: 'user',
+            senderId,
+            content: message.text ?? '',
+            threadId,
+            mentions: resolved.mentions,
+            metadata: {
+                source: 'slack',
+                slackChannelId: message.channelId,
+                slackThreadTs,
+                slackTs: message.ts,
+                slackUserId: message.userId,
+            },
+        });
+        await this.deps.slack
+            .addReaction(message.channelId, message.ts, SLACK_TEAM_CHANNEL_CONSTANTS.INBOUND_REACTION)
+            .catch(() => undefined);
+        const dispatcher = this.deps.getDispatcher();
+        let dispatch = null;
+        if (dispatcher) {
+            dispatch = await dispatcher.dispatchMessage(channel, persisted, {
+                threadId: threadId ?? persisted.id,
+                replyVia: 'reply-channel',
+            });
+        }
+        else {
+            this.logger.warn('No chat dispatcher wired — message persisted but not delivered', {
+                huddle: mapping.chatChannelId,
+            });
+        }
+        if (resolved.unknown.length > 0) {
+            await this.postUnknownMentionHint(message, resolved.unknown, candidates);
+        }
+        this.logger.info('Slack team message routed', {
+            teamId: mapping.teamId,
+            slackChannel: `#${mapping.slackChannelName}`,
+            mentions: resolved.mentions,
+            unknown: resolved.unknown.map((u) => u.token),
+            strategy: dispatch?.strategy ?? 'none',
+            threaded: !!threadId,
+        });
+        return { mapping, message: persisted, mentions: resolved.mentions, dispatch };
+    }
+    // -------------------------------------------------------------------------
+    // Outbound (huddle → Slack)
+    // -------------------------------------------------------------------------
+    /**
+     * Post an agent's huddle message to the mapped Slack channel under the
+     * agent's identity. Called for every chat-v2 `chat_message`; ignores
+     * anything that is not an agent message in a mapped huddle.
+     *
+     * @param dto - The chat-v2 message
+     * @returns True when a Slack post was attempted
+     */
+    async mirrorOutbound(dto) {
+        try {
+            if (dto.senderType !== 'agent')
+                return false;
+            if (dto.metadata?.source === 'slack')
+                return false;
+            await this.load();
+            const mapping = this.findByChatChannelId(dto.channelId);
+            if (!mapping)
+                return false;
+            if (!this.deps.slack.isConnected())
+                return false;
+            const threadTs = this.resolveOutboundThreadTs(mapping, dto);
+            const team = (await this.deps.storage.getTeams()).find((t) => t.id === mapping.teamId);
+            const member = team?.members.find((m) => m.sessionName === dto.senderId);
+            // A real bot user (Cloud-provisioned identity) beats the cosmetic
+            // username/icon override.
+            const installed = this.deps.identities?.getInstalled(dto.senderId) ?? null;
+            const identity = installed ? { botToken: installed.botToken } : slackIdentityFor(member, dto.senderId);
+            await this.deps.slack.sendMessage({
+                channelId: mapping.slackChannelId,
+                text: dto.content,
+                threadTs,
+                skipChatV2Mirror: true,
+                ...identity,
+            });
+            return true;
+        }
+        catch (err) {
+            this.logger.warn('Outbound mirror to Slack failed', {
+                channelId: dto.channelId,
+                sender: dto.senderId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return false;
+        }
+    }
+    /**
+     * Which Slack thread an agent reply belongs to: its chat-v2 thread root's
+     * `slackThreadTs`; failing that, the latest Slack-origin root in the
+     * huddle; failing that, the channel top level.
+     */
+    resolveOutboundThreadTs(mapping, dto) {
+        if (dto.threadId) {
+            const root = this.deps.chat.getMessageForBridge(dto.threadId);
+            const ts = root?.metadata?.slackThreadTs;
+            if (typeof ts === 'string' && ts)
+                return ts;
+        }
+        const latest = this.deps.chat.findLatestSlackRoot(mapping.chatChannelId);
+        const ts = latest?.metadata?.slackThreadTs;
+        return typeof ts === 'string' && ts ? ts : undefined;
+    }
+    // -------------------------------------------------------------------------
+    // Agent identities (real bot users)
+    // -------------------------------------------------------------------------
+    /**
+     * Give every member of a mapped team a real Slack identity: ask Cloud for
+     * one where missing, announce the owner's install links in the team's
+     * channel (once per agent per channel), and invite installed bots into the
+     * channel (once). Silent no-op when identities are unavailable (no Cloud
+     * login) or the owner has not stored a config token yet.
+     *
+     * @param team - The team
+     * @param mapping - Its channel mapping
+     * @returns Counts, for logging and the REST surface
+     */
+    async ensureIdentities(team, mapping) {
+        const identities = this.deps.identities;
+        const result = { provisioned: 0, announced: 0, invited: 0, skipped: null };
+        if (!identities || !identities.isAvailable()) {
+            result.skipped = 'identities unavailable';
+            return result;
+        }
+        await identities.load();
+        const pendingLinks = [];
+        for (const member of teamChannelMembers(team)) {
+            let record = identities.get(member.sessionName);
+            if (!record || record.status !== 'installed') {
+                try {
+                    record = await identities.provision(member.sessionName, member.name, `${member.name} — ${member.role} on ${team.name} (Crewly)`);
+                    result.provisioned += 1;
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    // A missing/invalid config token stops the whole pass — every
+                    // member would fail the same way. Anything else is per-member.
+                    if (/config_token|not_configured|not_logged_in/i.test(message) || /config(uration)? token/i.test(message)) {
+                        this.logger.info('Agent identities skipped', { reason: message });
+                        result.skipped = message;
+                        break;
+                    }
+                    this.logger.warn('Could not provision Slack identity', { agent: member.sessionName, error: message });
+                    continue;
+                }
+            }
+            if (record.status === 'pending_install' && record.installUrl && !record.announcedIn.includes(mapping.slackChannelId)) {
+                pendingLinks.push({ name: member.name, url: record.installUrl, session: member.sessionName });
+            }
+            if (record.status === 'installed' && record.botUserId && !record.invitedTo.includes(mapping.slackChannelId)) {
+                if (await this.inviteBot(mapping, member.sessionName, record.botUserId))
+                    result.invited += 1;
+            }
+        }
+        if (pendingLinks.length > 0) {
+            const lines = pendingLinks.map((p) => `• *${p.name}* → <${p.url}|安装 ${p.name}>`);
+            await this.deps.slack
+                .sendMessage({
+                channelId: mapping.slackChannelId,
+                text: [
+                    `:id: 给 *${team.name}* 的 ${pendingLinks.length} 位成员创建了 Slack 身份，点一下安装（每个各一次）：`,
+                    ...lines,
+                    '_安装后它们会以自己的名字出现在成员列表里，可以直接 @。_',
+                ].join('\n'),
+                skipChatV2Mirror: true,
+            })
+                .then(async () => {
+                for (const p of pendingLinks)
+                    await identities.markChannel(p.session, { announcedIn: mapping.slackChannelId });
+                result.announced = pendingLinks.length;
+            })
+                .catch((err) => {
+                this.logger.warn('Could not announce install links', { error: err instanceof Error ? err.message : String(err) });
+            });
+        }
+        return result;
+    }
+    /**
+     * Invite a newly installed agent bot into every channel of every team it
+     * belongs to. Runs from the identity service's `onInstalled` hook.
+     *
+     * @param agentSession - The agent that just got its bot user
+     */
+    async inviteInstalledEverywhere(agentSession) {
+        const identities = this.deps.identities;
+        if (!identities)
+            return;
+        const record = identities.get(agentSession);
+        if (!record?.botUserId)
+            return;
+        await this.load();
+        const teams = await this.deps.storage.getTeams();
+        for (const team of teams) {
+            if (!teamChannelMembers(team).some((m) => m.sessionName === agentSession))
+                continue;
+            const mapping = this.findByTeamId(team.id);
+            if (!mapping || record.invitedTo.includes(mapping.slackChannelId))
+                continue;
+            await this.inviteBot(mapping, agentSession, record.botUserId);
+        }
+    }
+    /** Invite one bot user into a mapped channel and remember it. */
+    async inviteBot(mapping, agentSession, botUserId) {
+        try {
+            await this.deps.slack.inviteToChannel(mapping.slackChannelId, [botUserId]);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (!/already_in_channel/.test(message)) {
+                this.logger.warn('Could not invite agent bot into channel', { agentSession, channel: mapping.slackChannelName, error: message });
+                return false;
+            }
+        }
+        await this.deps.identities?.markChannel(agentSession, { invitedTo: mapping.slackChannelId });
+        this.logger.info('Agent bot invited into team channel', { agentSession, channel: `#${mapping.slackChannelName}` });
+        return true;
+    }
+    // -------------------------------------------------------------------------
+    // Slack-side messages
+    // -------------------------------------------------------------------------
+    async postWelcome(mapping, team, members) {
+        const roster = members.length > 0
+            ? members.map((m) => `• *${m.name}* (${m.role}) — \`@${m.name}\``).join('\n')
+            : '_（还没有成员，成员加入后会自动同步）_';
+        const text = [
+            `:tada: 团队 *${team.name}* 的频道已就绪。`,
+            '',
+            '成员：',
+            roster,
+            '',
+            '直接发言，全队都能看到；`@名字` 可以点名某个 agent 必须回复。回复会以各自的名字出现在 thread 里。',
+        ].join('\n');
+        await this.deps.slack
+            .sendMessage({ channelId: mapping.slackChannelId, text, skipChatV2Mirror: true })
+            .catch((err) => {
+            this.logger.debug('Welcome message failed (non-critical)', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        });
+    }
+    async postUnknownMentionHint(message, unknown, candidates) {
+        const lines = unknown.map((u) => u.suggestions.length > 0
+            ? `没有叫 \`@${u.token}\` 的成员，你是想找 ${u.suggestions.map((s) => `\`@${s}\``).join(' / ')} 吗？`
+            : `没有叫 \`@${u.token}\` 的成员。`);
+        const rosterHint = candidates.length > 0
+            ? `本频道的成员：${candidates.map((c) => `\`@${c.name}\``).join(' ')}`
+            : '本频道目前没有成员。';
+        await this.deps.slack
+            .sendMessage({
+            channelId: message.channelId,
+            threadTs: message.threadTs || message.ts,
+            text: `${lines.join('\n')}\n${rosterHint}\n_（消息已经发给全队；只有被正确 @ 的成员会被要求必须回复。）_`,
+            skipChatV2Mirror: true,
+        })
+            .catch(() => undefined);
+    }
+    // -------------------------------------------------------------------------
+    // Helpers
+    // -------------------------------------------------------------------------
+    /** Run `fn` after any in-flight operation for the same team finishes. */
+    serialised(teamId, fn) {
+        const prev = this.inflight.get(teamId) ?? Promise.resolve();
+        const next = prev.catch(() => undefined).then(fn);
+        this.inflight.set(teamId, next);
+        const cleanup = () => {
+            if (this.inflight.get(teamId) === next)
+                this.inflight.delete(teamId);
+        };
+        // `then(cleanup, cleanup)` rather than `finally`: a rejected `next` is
+        // returned to the caller, and a second derived promise must not turn
+        // that same rejection into an unhandled one.
+        next.then(cleanup, cleanup);
+        return next;
+    }
+}
+/** Type guard for persisted mapping rows. */
+function isMapping(value) {
+    const v = value;
+    return (!!v &&
+        typeof v.teamId === 'string' &&
+        typeof v.slackChannelId === 'string' &&
+        typeof v.chatChannelId === 'string');
+}
+// ---------------------------------------------------------------------------
+// Singleton
+// ---------------------------------------------------------------------------
+let instance = null;
+/**
+ * Install the process-wide instance (composition root).
+ *
+ * @param service - The configured service
+ */
+export function setSlackTeamChannelService(service) {
+    instance = service;
+}
+/**
+ * The process-wide instance, or null before the composition root wires it
+ * (e.g. Slack not configured).
+ *
+ * @returns The service or null
+ */
+export function getSlackTeamChannelService() {
+    return instance;
+}
+//# sourceMappingURL=slack-team-channel.service.js.map