crewly 1.20.86 → 1.20.88

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

@@ -215,6 +215,8 @@ export class SlackTeamChannelService {
     unsubscribeIdentity = null;
     /** Slack `channel:ts` of messages already routed → the persisted turn. */
     seenInbound = new Map();
+    /** The last room presence Cloud sent per Slack channel — names for a hand-off. */
+    lastRooms = new Map();
     onChatMessage = (dto) => {
         void this.mirrorOutbound(dto);
     };
@@ -792,12 +794,37 @@ export class SlackTeamChannelService {
             mapping = await this.ensureAdhocChannel(message);
         if (!mapping)
             return null;
+        // Slack delivers a channel message to every app in the channel, so a copy
+        // that arrived through one of our agents' own apps proves that agent is
+        // in the room — whether or not anyone has ever @'d it there. An ad-hoc
+        // roster used to be "agents that were @'d here", which left an agent the
+        // owner had added to a private channel out of it until someone happened
+        // to address it by name.
+        const receiving = await this.localReceivingAgent(message);
+        if (receiving && isAdhocMapping(mapping) && !(mapping.members ?? []).includes(receiving)) {
+            mapping.members = [...(mapping.members ?? []), receiving];
+            this.deps.chat.setHuddleMembers(mapping.chatChannelId, mapping.members);
+            await this.save();
+            this.deps.onRoomsChanged?.();
+        }
+        if (message.room) {
+            this.lastRooms.set(message.channelId, message.room);
+            if (this.lastRooms.size > SLACK_TEAM_CHANNEL_CONSTANTS.SEEN_INBOUND_MAX) {
+                const oldest = this.lastRooms.keys().next().value;
+                if (oldest !== undefined)
+                    this.lastRooms.delete(oldest);
+            }
+        }
+        // A hand-off: the room's router picked one of our agents to answer a
+        // message this machine already has. Deliver it again, addressed to that
+        // agent, instead of dropping it as a repeat.
+        const handoffTo = message.handoffTo && (this.deps.isLocalAgent?.(message.handoffTo) ?? true) ? message.handoffTo : null;
         // One Slack message can reach us twice with different event types
         // (`app_mention` for an @'d agent's app plus `message.channels`); the
         // team must see it once — a second copy is acknowledged, not dispatched.
         const seenKey = `${message.channelId}:${message.ts}`;
         const seen = this.seenInbound.get(seenKey);
-        if (seen) {
+        if (seen && !handoffTo) {
             this.logger.debug('Repeated copy of a team channel message — not dispatched again', { key: seenKey });
             return { mapping, message: seen, mentions: [], dispatch: null, duplicate: true };
         }
@@ -823,6 +850,8 @@ export class SlackTeamChannelService {
             botUserId: this.deps.identities?.get(m.sessionName)?.botUserId,
         }));
         const resolved = resolveSlackMentions(message.text ?? '', candidates);
+        if (handoffTo && !resolved.mentions.includes(handoffTo))
+            resolved.mentions.push(handoffTo);
         // Thread correlation.
         const slackThreadTs = message.threadTs || message.ts;
         let threadId;
@@ -858,80 +887,30 @@ export class SlackTeamChannelService {
                 ...(remoteAgent ? { remoteAgentSession: remoteAgent } : {}),
             },
         };
-        const persisted = localAuthor
-            ? {
-                id: `slack-echo-${message.channelId}-${message.ts}`,
-                channelId: mapping.chatChannelId,
-                seq: 0,
-                senderType: 'user',
-                senderId,
-                content: turn.content,
-                contentType: 'markdown',
-                createdAt: Date.now(),
-                attachments: [],
-                mentions: resolved.mentions,
-                threadId,
-                metadata: turn.metadata,
-            }
-            : this.deps.chat.recordTurn(turn).message;
+        const persisted = handoffTo && seen
+            ? { ...seen, mentions: [...new Set([...(seen.mentions ?? []), handoffTo])] }
+            : localAuthor
+                ? {
+                    id: `slack-echo-${message.channelId}-${message.ts}`,
+                    channelId: mapping.chatChannelId,
+                    seq: 0,
+                    senderType: 'user',
+                    senderId,
+                    content: turn.content,
+                    contentType: 'markdown',
+                    createdAt: Date.now(),
+                    attachments: [],
+                    mentions: resolved.mentions,
+                    threadId,
+                    metadata: turn.metadata,
+                }
+                : this.deps.chat.recordTurn(turn).message;
         this.seenInbound.set(seenKey, persisted);
         if (this.seenInbound.size > SLACK_TEAM_CHANNEL_CONSTANTS.SEEN_INBOUND_MAX) {
             const oldest = this.seenInbound.keys().next().value;
             if (oldest !== undefined)
                 this.seenInbound.delete(oldest);
         }
-        // In an ad-hoc (often private) channel the master bot may not be a
-        // member, so an agent's own bot reacts instead.
-        //
-        // Which agent's, though, has to be found out rather than assumed. This
-        // used to take the first installed bot among the @'d agents and the
-        // huddle roster, on the reasoning that a huddle member's bot is "by
-        // definition in the channel". It is not: the roster grows as agents are
-        // @'d and never shrinks, and a bot can be removed from a private channel
-        // afterwards. Pick one that is not in the channel and Slack answers
-        // `channel_not_found` — the message is routed, dispatched and answered,
-        // and the owner sees no eyes at all (#daily-info, 2026-09-22).
-        //
-        // So try them in turn, @'d agents first since one of them is about to
-        // reply, and fall back to the master bot last.
-        const reactorTokens = isAdhocMapping(mapping)
-            ? [
-                ...new Set([...resolved.mentions, ...(mapping.members ?? [])]
-                    .map((m) => this.deps.identities?.getInstalled(m)?.botToken)
-                    .filter((t) => !!t)),
-                undefined,
-            ]
-            : [undefined];
-        // Swallowing this outright cost an evening: the owner saw no eyes and no
-        // placeholder and reasonably concluded nothing had arrived, while the
-        // message was in fact routed, dispatched and answered (2026-09-21).
-        // Cosmetic, so still non-fatal — but never again silent.
-        let reacted = false;
-        let lastError = '';
-        for (const token of reactorTokens) {
-            try {
-                await this.deps.slack.addReaction(message.channelId, message.ts, SLACK_TEAM_CHANNEL_CONSTANTS.INBOUND_REACTION, token);
-                reacted = true;
-                break;
-            }
-            catch (err) {
-                const code = describeSlackError(err).code;
-                lastError = code;
-                // Only a not-a-member failure is worth trying another identity for.
-                // Anything else (already reacted, rate limit, bad message ts) will
-                // fail identically for every bot.
-                if (code !== 'channel_not_found')
-                    break;
-            }
-        }
-        if (!reacted) {
-            this.logger.warn('Could not acknowledge the message with a reaction', {
-                slackChannel: mapping.slackChannelName ?? message.channelId,
-                adhoc: isAdhocMapping(mapping),
-                identitiesTried: reactorTokens.length,
-                error: lastError,
-            });
-        }
         // Ad-hoc channels grow their huddle as new agents get @'d there.
         if (isAdhocMapping(mapping) && resolved.mentions.length > 0) {
             const next = [...new Set([...(mapping.members ?? []), ...resolved.mentions])];
@@ -939,24 +918,50 @@ export class SlackTeamChannelService {
                 mapping.members = next;
                 this.deps.chat.setHuddleMembers(mapping.chatChannelId, next);
                 await this.save();
+                this.deps.onRoomsChanged?.();
             }
         }
-        // @'d agents must reply: show the honest state in the thread for each
-        // one that has its own bot — "waking up…" for an idle agent (a cold
-        // start is 1–2 minutes), "is working on it…" once it holds the message.
-        // Who will be asked to reply: the @'d members, or (nobody @'d, top-level
-        // message) the team leader alone. Mirrors the dispatcher's targeting so
-        // the placeholder matches who actually gets the message.
-        const typingTargets = [];
-        if (this.deps.typing) {
-            let sessions = resolved.mentions;
-            if (sessions.length === 0 && !message.threadTs && team) {
+        // Who will receive this, and who owes a reply — decided by the same rules
+        // delivery uses, but *before* delivery, which can take a minute or two
+        // when an agent has to be cold-started. The owner should not look at an
+        // unacknowledged message for that long.
+        const dispatcherForPlan = this.deps.getDispatcher();
+        const presence = await this.roomStateFor(message, mapping, team ? teamChannelMembers(team) : null);
+        const dispatchOptions = {
+            threadId: threadId ?? persisted.id,
+            replyVia: 'reply-channel',
+            // A local agent's own message (fanned out to the colleagues it @'d)
+            // must not come back to its author.
+            ...(remoteAgent ? { excludeSessions: [remoteAgent] } : {}),
+            ...(presence ? { room: presence.state, ...(presence.line ? { roomPresence: presence.line } : {}) } : {}),
+        };
+        const planned = dispatcherForPlan?.planHuddleTargets
+            ? await dispatcherForPlan.planHuddleTargets(channel, persisted, dispatchOptions).catch(() => null)
+            : null;
+        await this.acknowledgeSeen(message, mapping, resolved.mentions, planned);
+        // Agents that must reply get a placeholder straight away — "waking up…"
+        // for an idle agent (a cold start is 1–2 minutes), "is working on it…"
+        // once it holds the message. Agents that were only told, and may or may
+        // not decide to answer, get none: a placeholder is a promise of a reply,
+        // and they announce their own with `reply-channel --working` if they
+        // take it on. With a plan this covers the case the old heuristic missed —
+        // a bare follow-up in a thread, which the last speaker must answer.
+        let owing;
+        if (planned) {
+            owing = [...planned].filter(([, mode]) => mode === 'required').map(([session]) => session);
+        }
+        else {
+            owing = resolved.mentions;
+            if (owing.length === 0 && !message.threadTs && team) {
                 // Same rule as the dispatcher's huddleLeaderFor: the team leader, else the first member.
                 const leader = members.find((m) => String(m.role) === 'team-leader' || String(m.role) === 'tech-lead') ?? members[0];
                 if (leader)
-                    sessions = [leader.sessionName];
+                    owing = [leader.sessionName];
             }
-            for (const session of sessions) {
+        }
+        const typingTargets = [];
+        if (this.deps.typing) {
+            for (const session of owing) {
                 const member = members.find((m) => m.sessionName === session);
                 const installed = this.deps.identities?.getInstalled(session);
                 // Own bot when installed; otherwise the master bot wearing the agent's
@@ -984,12 +989,8 @@ export class SlackTeamChannelService {
                     .join(' · ');
             }
             dispatch = await dispatcher.dispatchMessage(channel, persisted, {
-                threadId: threadId ?? persisted.id,
-                replyVia: 'reply-channel',
+                ...dispatchOptions,
                 ...(roster ? { channelRoster: roster } : {}),
-                // A local agent's own message (fanned out to the colleagues it @'d)
-                // must not come back to its author.
-                ...(remoteAgent ? { excludeSessions: [remoteAgent] } : {}),
             });
         }
         else {
@@ -1022,19 +1023,258 @@ export class SlackTeamChannelService {
         });
         return { mapping, message: persisted, mentions: resolved.mentions, dispatch };
     }
+    /**
+     * Who in this room is awake, from this machine's point of view.
+     *
+     * Local members are judged by what is running here now; members on other
+     * machines by what Cloud last heard from them. Cloud names the one machine
+     * that wakes someone when nobody is awake. One case it cannot see: it may
+     * believe an agent of ours is awake when that agent has just stopped.
+     * Then nobody would be woken anywhere — every other machine thinks we have
+     * it — so this machine, the only one that knows better, wakes the router.
+     *
+     * @param message - Inbound message (carries Cloud's presence, when any)
+     * @param mapping - Its channel mapping
+     * @param teamMembers - Team channel members, or null for an ad-hoc room
+     * @returns State for the dispatcher and a line for the prompt; null without an awake check
+     */
+    async roomStateFor(message, mapping, teamMembers) {
+        const isAwake = this.deps.isAgentAwake;
+        if (!isAwake)
+            return null;
+        const localMembers = teamMembers ? teamMembers.map((m) => m.sessionName) : (mapping.members ?? []);
+        const awakeHere = localMembers.filter((m) => isAwake(m));
+        const room = message.room;
+        if (!room)
+            return { state: { awakeHere, awakeElsewhere: false } };
+        const me = this.deps.resolveInstanceId ? await this.deps.resolveInstanceId().catch(() => null) : null;
+        const isHere = (m) => me ? m.instanceId === me : (this.deps.isLocalAgent?.(localAgentSession(m.agentSession)) ?? false);
+        const awakeElsewhere = room.members.some((m) => !isHere(m) && m.awake);
+        let wakeWhenAllAsleep = null;
+        if (room.fallback) {
+            const here = me ? room.fallback.instanceId === me : (this.deps.isLocalAgent?.(localAgentSession(room.fallback.agentSession)) ?? false);
+            if (here)
+                wakeWhenAllAsleep = { agentSession: localAgentSession(room.fallback.agentSession), kind: room.fallback.kind };
+        }
+        else if (!awakeElsewhere && awakeHere.length === 0 && room.members.some((m) => isHere(m) && m.awake)) {
+            const leader = teamMembers
+                ? (teamMembers.find((m) => String(m.role) === 'team-leader' || String(m.role) === 'tech-lead') ?? teamMembers[0])
+                : undefined;
+            wakeWhenAllAsleep = leader
+                ? { agentSession: leader.sessionName, kind: 'team-leader' }
+                : { agentSession: CREWLY_CONSTANTS.SESSIONS.ORCHESTRATOR_NAME, kind: 'orchestrator' };
+        }
+        const line = room.members
+            .map((m) => {
+            const here = isHere(m);
+            const awake = here ? awakeHere.includes(localAgentSession(m.agentSession)) : m.awake;
+            return `${m.displayName}（${awake ? '醒着' : '在睡'}，${here ? '本机' : m.deviceName}）`;
+        })
+            .join(' · ');
+        return { state: { awakeHere, awakeElsewhere, wakeWhenAllAsleep }, line };
+    }
+    /**
+     * Hand a room message to one agent, wherever it runs.
+     *
+     * Used by the room's router — the orchestrator of a private room, woken
+     * because nobody in it was awake. Its own bot is usually not in the room,
+     * so it cannot @ the agent there the way a member would. An agent on this
+     * machine gets the message delivered again as if @'d (👀 and a "waking
+     * up…" placeholder from its own bot); one on another machine gets it
+     * through Cloud, which does the same over there.
+     *
+     * @param input - Chat channel, the message to pass on, and who should answer it
+     * @returns Who it went to, or why it could not
+     */
+    async handoffForAgent(input) {
+        await this.load();
+        const mapping = (this.store?.mappings ?? []).find((m) => m.chatChannelId === input.chatChannelId);
+        if (!mapping)
+            return { ok: false, reason: 'not_a_slack_channel' };
+        const source = input.messageId ?? input.threadId;
+        const original = source ? this.deps.chat.getMessageForBridge(source) : null;
+        const meta = (original?.metadata ?? {});
+        const slackTs = typeof meta['slackTs'] === 'string' ? meta['slackTs'] : '';
+        if (!original || meta['source'] !== 'slack' || !slackTs)
+            return { ok: false, reason: 'not_a_slack_message' };
+        const threadTs = typeof meta['slackThreadTs'] === 'string' && meta['slackThreadTs'] !== slackTs ? meta['slackThreadTs'] : undefined;
+        const userId = typeof meta['slackUserId'] === 'string' ? meta['slackUserId'] : '';
+        // Names: everyone Cloud last said is in the room, plus this machine's agents.
+        const wanted = input.name.trim().replace(/^@/, '').toLowerCase();
+        const candidates = [];
+        for (const m of this.lastRooms.get(mapping.slackChannelId)?.members ?? []) {
+            candidates.push({ session: m.agentSession, name: m.displayName });
+        }
+        const localSessions = new Set();
+        for (const team of await this.deps.storage.getTeams()) {
+            for (const m of teamChannelMembers(team)) {
+                candidates.push({ session: m.sessionName, name: m.name });
+                localSessions.add(m.sessionName);
+            }
+        }
+        const hit = candidates.find((c) => c.name.toLowerCase() === wanted || c.session.toLowerCase() === wanted);
+        if (!hit) {
+            return { ok: false, reason: 'unknown_agent', candidates: [...new Set(candidates.map((c) => c.name))].slice(0, 20) };
+        }
+        const local = this.deps.isLocalAgent?.(localAgentSession(hit.session)) ?? localSessions.has(hit.session);
+        if (local) {
+            await this.routeInbound({
+                id: slackTs,
+                type: 'message',
+                text: original.content,
+                userId,
+                channelId: mapping.slackChannelId,
+                ...(threadTs ? { threadTs } : {}),
+                ts: slackTs,
+                teamId: '',
+                eventTs: slackTs,
+                source: 'cloud',
+                handoffTo: localAgentSession(hit.session),
+            });
+            this.logger.info('Room message handed to a local agent', { agentSession: hit.session, slackChannel: mapping.slackChannelName });
+            return { ok: true, agentSession: localAgentSession(hit.session), displayName: hit.name, via: 'here' };
+        }
+        if (!this.deps.handoffViaCloud)
+            return { ok: false, reason: 'cloud_unavailable' };
+        await this.deps.handoffViaCloud({
+            agentSession: hit.session,
+            event: {
+                channel: mapping.slackChannelId,
+                ts: slackTs,
+                ...(threadTs ? { thread_ts: threadTs } : {}),
+                text: original.content,
+                ...(userId ? { user: userId } : {}),
+            },
+        });
+        this.logger.info('Room message handed to an agent on another machine', { agentSession: hit.session, slackChannel: mapping.slackChannelName });
+        return { ok: true, agentSession: hit.session, displayName: hit.name, via: 'cloud' };
+    }
+    /**
+     * The ad-hoc rooms this machine's agents are in, for the Cloud heartbeat —
+     * Cloud builds each room's cross-machine roster from these.
+     *
+     * @returns Slack channel → local member sessions
+     */
+    async listRooms() {
+        await this.load();
+        return (this.store?.mappings ?? [])
+            .filter((m) => isAdhocMapping(m) && (m.members ?? []).length > 0)
+            .map((m) => ({ channelId: m.slackChannelId, agents: [...(m.members ?? [])] }));
+    }
+    /**
+     * The local agent whose own app delivered this copy, if any.
+     *
+     * A direct message is never a room: an agent's DM is handled by the DM
+     * service, and anything that falls through from there belongs to the
+     * orchestrator path, not to an ad-hoc huddle.
+     *
+     * @param message - The inbound message
+     * @returns The agent's session name, or null
+     */
+    async localReceivingAgent(message) {
+        const session = message.receivedVia ?? message.agentSession;
+        if (!session || message.channelId.startsWith('D'))
+            return null;
+        if (this.deps.isLocalAgent)
+            return this.deps.isLocalAgent(session) ? session : null;
+        const teams = await this.deps.storage.getTeams();
+        return teams.some((t) => teamChannelMembers(t).some((m) => m.sessionName === session)) ? session : null;
+    }
+    /**
+     * Put 👀 on the message — one per agent that will receive it.
+     *
+     * It used to be a single reaction meaning "Crewly got this". The owner
+     * reads it as "how many agents saw this", and with several agents in a
+     * room that is the more useful answer: three agents who will each weigh a
+     * message should show three eyes, and an agent that was not handed the
+     * message should show none, so the count is honest rather than "everyone
+     * in the channel". Each agent reacts with its own bot.
+     *
+     * When nobody in particular receives it, or no receiving agent has a bot
+     * of its own, one reaction still goes on so the owner can see the message
+     * arrived — the 2026-09-21 lesson: no eyes reads as nothing arrived.
+     *
+     * @param message - The inbound message
+     * @param mapping - Its channel mapping
+     * @param mentions - Agents @'d in it
+     * @param planned - Who will receive it, from the dispatcher; null when unknown
+     */
+    async acknowledgeSeen(message, mapping, mentions, planned) {
+        const react = (token) => this.deps.slack.addReaction(message.channelId, message.ts, SLACK_TEAM_CHANNEL_CONSTANTS.INBOUND_REACTION, token);
+        let seen = 0;
+        const absent = [];
+        for (const session of planned?.keys() ?? []) {
+            const token = this.deps.identities?.getInstalled(session)?.botToken;
+            if (!token)
+                continue;
+            try {
+                await react(token);
+                seen += 1;
+            }
+            catch (err) {
+                const code = describeSlackError(err).code;
+                if (code === 'channel_not_found' || code === 'not_in_channel')
+                    absent.push(session);
+            }
+        }
+        if (absent.length > 0) {
+            // The agent still gets the message; its bot is just not in the room
+            // (removed from a private channel after it joined the roster, say).
+            this.logger.info('Agent bot not in the channel — no eyes from it', {
+                slackChannel: mapping.slackChannelName ?? message.channelId,
+                agents: absent,
+            });
+        }
+        if (seen > 0)
+            return;
+        // Nobody in particular, or nobody with a bot of their own. In an ad-hoc
+        // (often private) channel the master bot may not be a member, so try the
+        // agents' bots — @'d ones first — and the master bot last. Only a
+        // not-a-member failure is worth another identity: already-reacted, rate
+        // limits and a bad ts fail identically for every bot.
+        const fallback = isAdhocMapping(mapping)
+            ? [
+                ...new Set([...mentions, ...(mapping.members ?? [])]
+                    .map((m) => this.deps.identities?.getInstalled(m)?.botToken)
+                    .filter((t) => !!t)),
+                undefined,
+            ]
+            : [undefined];
+        let lastError = '';
+        for (const token of fallback) {
+            try {
+                await react(token);
+                return;
+            }
+            catch (err) {
+                lastError = describeSlackError(err).code;
+                if (lastError !== 'channel_not_found')
+                    break;
+            }
+        }
+        // Swallowing this outright cost an evening (2026-09-21): cosmetic, so
+        // non-fatal, but never silent.
+        this.logger.warn('Could not acknowledge the message with a reaction', {
+            slackChannel: mapping.slackChannelName ?? message.channelId,
+            adhoc: isAdhocMapping(mapping),
+            identitiesTried: fallback.length,
+            error: lastError,
+        });
+    }
     /**
      * Any Slack channel becomes routable the moment a local agent's bot is
-     * @'d in it (the owner invited agents from different teams into a private
-     * channel, say): a huddle is created for the channel with the @'d agents
-     * as members and mapped under the synthetic team id `adhoc:<channel>`.
-     * Messages that @ nobody local are left to the caller (orchestrator path).
+     * @'d in it, or a message reaches us through a local agent's own app
+     * (Slack only delivers to apps that are members, so that proves the bot
+     * is in the channel). The owner invited agents from different teams into
+     * a private channel, say: a huddle is created for the channel with those
+     * agents as members and mapped under the synthetic team id
+     * `adhoc:<channel>`. Anything else is left to the caller (orchestrator
+     * path).
      *
      * @param message - The inbound message
      * @returns The new mapping, or null when no local agent was @'d
      */
     async ensureAdhocChannel(message) {
-        if (!message.text || !message.text.includes('<@') && !message.text.includes('@'))
-            return null;
         const teams = await this.deps.storage.getTeams();
         const members = teams.flatMap((t) => teamChannelMembers(t));
         if (members.length === 0)
@@ -1049,10 +1289,17 @@ export class SlackTeamChannelService {
         // Only a real Slack mention of an agent's bot user counts here — a bare
         // "@name" in some unrelated channel must not hijack it.
         const botIds = new Set(candidates.map((c) => c.botUserId).filter((id) => !!id));
-        const mentionedBots = [...message.text.matchAll(/<@([A-Z0-9]+)>/g)].map((m) => m[1]).filter((id) => botIds.has(id));
-        if (mentionedBots.length === 0)
-            return null;
+        const text = message.text ?? '';
+        const mentionedBots = [...text.matchAll(/<@([A-Z0-9]+)>/g)].map((m) => m[1]).filter((id) => botIds.has(id));
         const sessions = candidates.filter((c) => c.botUserId && mentionedBots.includes(c.botUserId)).map((c) => c.sessionName);
+        // The copy came through a local agent's own app: that agent's bot is in
+        // this channel, which makes the channel a room it belongs to even if
+        // nobody has addressed it yet.
+        const receiving = await this.localReceivingAgent(message);
+        if (receiving && !sessions.includes(receiving))
+            sessions.push(receiving);
+        if (sessions.length === 0)
+            return null;
         // The master bot is usually not in this channel (private); the name is
         // best-effort and falls back to the id.
         const info = await this.deps.slack.getChannelInfo(message.channelId).catch(() => null);
@@ -1075,6 +1322,7 @@ export class SlackTeamChannelService {
         const store = await this.load();
         store.mappings.push(mapping);
         await this.save();
+        this.deps.onRoomsChanged?.();
         this.logger.info('Ad-hoc Slack channel linked (agents @\'d outside a team channel)', {
             slackChannel: `#${channelName}`,
             huddle: huddle.id,
@@ -1190,6 +1438,51 @@ export class SlackTeamChannelService {
      * `slackThreadTs`; failing that, the latest Slack-origin root in the
      * huddle; failing that, the channel top level.
      */
+    /**
+     * Show "<agent> is working on it…" in the thread, at the agent's request.
+     *
+     * Agents that must answer get this placeholder the moment the message
+     * arrives. Agents that were only *told* — a message nobody addressed to
+     * them, passed along so they can judge whether it concerns them — get none,
+     * because a placeholder promises a reply and most of them will not send
+     * one. When one of them does decide to answer, it calls this, so the owner
+     * sees who has taken the message on: two agents deciding to answer show two
+     * placeholders, which is exactly the signal the owner asked for.
+     *
+     * The key matches the one the reply is mirrored under, so the agent's
+     * actual answer replaces the placeholder rather than landing beside it.
+     *
+     * @param input - Chat channel and thread the agent is answering in
+     * @returns Whether a placeholder is now showing, or why not
+     */
+    async beginWorkingForAgent(input) {
+        const mapping = (this.store?.mappings ?? []).find((m) => m.chatChannelId === input.chatChannelId);
+        if (!mapping)
+            return { ok: false, reason: 'not_a_slack_channel' };
+        if (!this.deps.typing)
+            return { ok: false, reason: 'placeholders_unavailable' };
+        if (!this.deps.slack.isConnected())
+            return { ok: false, reason: 'slack_not_connected' };
+        const threadTs = this.resolveOutboundThreadTs(mapping, {
+            channelId: input.chatChannelId,
+            senderId: input.agentSession,
+            ...(input.threadId ? { threadId: input.threadId } : {}),
+        });
+        const team = (await this.deps.storage.getTeams()).find((t) => (t.members ?? []).some((m) => m.sessionName === input.agentSession));
+        const member = team?.members.find((m) => m.sessionName === input.agentSession);
+        const installed = this.deps.identities?.getInstalled(input.agentSession) ?? null;
+        const displayName = member?.name ?? input.agentSession;
+        const identity = installed
+            ? { botToken: installed.botToken, displayName }
+            : { displayName, ...slackIdentityFor(member, input.agentSession) };
+        await this.deps.typing.begin({ agentSession: input.agentSession, slackChannelId: mapping.slackChannelId, ...(threadTs ? { threadTs } : {}) }, identity, 'typing');
+        this.logger.info('Agent took a message on', {
+            agentSession: input.agentSession,
+            slackChannel: mapping.slackChannelName,
+            threaded: Boolean(threadTs),
+        });
+        return { ok: true, slackChannelId: mapping.slackChannelId, ...(threadTs ? { threadTs } : {}) };
+    }
     /**
      * Put a file into the Slack channel an agent is replying in.
      *