@stratusagent/channel-slack 0.11.8 → 0.11.10

package/dist/index.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { lstat, open, readFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { filePathsOf, isLatestTurn, latestTurnReply, MAX_IDEMPOTENCY_KEY_LENGTH, turnFailureFor, turnFilesFor, turnReplyFor, CONVERSATION_METADATA_KEY, SENDER_TRUST_METADATA_KEY, sessionWriteTrust, imageDimensions, isImageAttachmentMediaType, IMAGE_ATTACHMENT_MAX_BYTES, IMAGE_ATTACHMENT_MAX_DIMENSION, IMAGE_ATTACHMENTS_MAX_TOTAL_BYTES, escapeControlCharacters, } from '@stratusagent/core';
+import { filePathsOf, isLatestTurn, latestTurnReply, MAX_IDEMPOTENCY_KEY_LENGTH, turnFailureFor, turnFilesFor, turnReplyFor, CONVERSATION_METADATA_KEY, SENDER_TRUST_METADATA_KEY, sessionWriteTrust, imageDimensions, isImageAttachmentMediaType, IMAGE_ATTACHMENT_MAX_BYTES, IMAGE_ATTACHMENT_MAX_DIMENSION, IMAGE_ATTACHMENTS_MAX_TOTAL_BYTES, escapeControlCharacters, leastTrusted, sessionTrustOf, SESSION_TRUST_METADATA_KEY, } from '@stratusagent/core';
 import { admitsSender, channelSessionKey, senderTrustFor, } from '@stratusagent/channels';
 import { codeRunsOf, toSlackMrkdwn } from "./mrkdwn.js";
 /**
@@ -83,6 +83,23 @@ const ATTENTION_MS = 15 * 60 * 1000;
 const DEFAULT_FILE_DOWNLOAD_TIMEOUT_MS = 30_000;
 /** What a turn that produced no text puts in its message, wherever it is posted from. */
 const NO_REPLY_TEXT = '(no reply)';
+/**
+ * How much of a thread a late arrival is handed: the parent, which is
+ * usually the question, and the newest messages before the mention. A
+ * longer thread is cut in the middle and says so, rather than flooding the
+ * opening turn or dropping the message that started it.
+ */
+const EARLIER_MESSAGE_LIMIT = 40;
+/** The most pages of 200 read from a thread for that: 4,000 replies. */
+const EARLIER_THREAD_PAGES = 20;
+/**
+ * At the top of a channel, how many of its most recent messages a mention
+ * opens with, and how many are read to find them.
+ */
+const EARLIER_CHANNEL_LIMIT = 20;
+const EARLIER_CHANNEL_READ = 100;
+/** The most pages read to find them: 1,000 messages. */
+const EARLIER_CHANNEL_PAGES = 10;
 // Lazy (and CJS-interoperable) so tests with injected fakes never load the
 // real SDK stack.
 const requireModule = createRequire(import.meta.url);
@@ -90,6 +107,37 @@ const defaultSocketClient = (appToken) => {
     const { SocketModeClient } = requireModule('@slack/socket-mode');
     return new SocketModeClient({ appToken });
 };
+/**
+ * Scopes the manifest asks for. An app created before they shipped has
+ * fewer, and some features silently break — threads are answered without
+ * their context, images arrive as names. Checked once at connect, so the
+ * operator finds out at start, not at the first broken thread.
+ *
+ * Events (`message.channels`, `message.groups`, …) cannot be read from a
+ * bot token, so the warning says they are needed too.
+ */
+const REQUIRED_SCOPES = [
+    'app_mentions:read',
+    'channels:history', 'channels:read',
+    'chat:write',
+    'files:read', 'files:write',
+    'groups:history', 'groups:read',
+    'im:history', 'im:read', 'im:write',
+    'mpim:history', 'mpim:read',
+    'users:read',
+];
+const checkBotScopes = (agentId, granted, warn) => {
+    const have = new Set(granted);
+    const missing = REQUIRED_SCOPES.filter((scope) => !have.has(scope));
+    if (missing.length === 0) {
+        return;
+    }
+    warn(`slack: ${agentId}'s app is missing bot scopes: ${missing.join(', ')}. `
+        + 'Add them under OAuth & Permissions, add the matching message.* events '
+        + 'under Event Subscriptions, and reinstall the app to the workspace. '
+        + 'Without them, some features (thread follow-through, image viewing, '
+        + 'channel history) will silently fail.');
+};
 const defaultWebClient = (botToken) => {
     const { WebClient } = requireModule('@slack/web-api');
     return new WebClient(botToken);
@@ -254,6 +302,28 @@ class ReplyRenderer {
      */
     turnId = randomUUID();
     buffer = '';
+    /**
+     * In `final` mode, what the model has said since its last tool call. A
+     * turn that writes "On it, checking the PRs" and then works for an hour
+     * should not leave the thread showing only a loading status: text the
+     * model wrote before calling a tool is posted when the call starts, as a
+     * message of its own, and the finished reply follows it.
+     */
+    interim = '';
+    /** The last interim message posted, so a reply that repeats it is not posted twice. */
+    lastInterim;
+    /** Whether any interim message landed — something said, whatever the reply's fate. */
+    interimPosted = false;
+    /** Every interim message that landed whole, in order: what a hosted-loop reply is stripped of. */
+    interimSaid = [];
+    /**
+     * Told of each interim message as it is queued — before the reply, and
+     * before anything typed while its tool runs — with what of it landed,
+     * once that is known, so the thread's other agents hear it in its place.
+     */
+    onInterim;
+    /** The lowest trust this turn's session was lowered to while it ran (`session.tainted`). */
+    taintedTo;
     turnBreakPending = false;
     toolLine;
     ref;
@@ -376,6 +446,7 @@ class ReplyRenderer {
         this.statusWarned = options.statusWarned ?? { value: false };
         this.after = options.after ?? Promise.resolve();
         this.dmWith = options.dmWith;
+        this.onInterim = options.onInterim;
     }
     /**
      * Show Slack's loading status for this turn, and keep it up until the
@@ -466,6 +537,7 @@ class ReplyRenderer {
             this.pendingEdit = undefined;
         }
         this.buffer = '';
+        this.interim = '';
         this.toolLine = undefined;
         this.runningTool = undefined;
         this.turnBreakPending = false;
@@ -493,6 +565,12 @@ class ReplyRenderer {
         if (this.finalized) {
             return;
         }
+        if (event.type === 'session.tainted') {
+            if (ofThisTurn && this.turnStarted) {
+                this.taintedTo = this.taintedTo === undefined ? event.trust : leastTrusted(this.taintedTo, event.trust);
+            }
+            return;
+        }
         if (event.type === 'provider.delta' && event.delta.type === 'text') {
             // Text from a new provider turn (after tools ran) must not fuse
             // with the previous turn's — "I'll check.The result is…" reads as
@@ -502,6 +580,7 @@ class ReplyRenderer {
             }
             this.turnBreakPending = false;
             this.buffer += event.delta.text;
+            this.interim += event.delta.text;
             this.scheduleEdit();
             return;
         }
@@ -510,12 +589,22 @@ class ReplyRenderer {
             // mid-stream failure): discard everything streamed so far so two
             // attempts never fuse into one message.
             this.buffer = '';
+            this.interim = '';
             this.turnBreakPending = false;
             this.scheduleEdit();
             return;
         }
         if (event.type === 'provider.response') {
             this.turnBreakPending = true;
+            // A provider that answers in one piece streams no deltas: the
+            // response is the only place its words before a tool call appear.
+            // One that streamed them has them already, and is not given them twice.
+            if (this.interim.trim().length === 0) {
+                this.interim = event.parts
+                    .filter((part) => part.type === 'text')
+                    .map((part) => part.text)
+                    .join('');
+            }
             return;
         }
         if (event.type === 'tool.called') {
@@ -527,6 +616,7 @@ class ReplyRenderer {
             this.turnBreakPending = true;
             this.toolLine = `⚙ ${event.call.toolName}…`;
             this.runningTool = event.call.toolName;
+            this.flushInterim(ofThisTurn);
             this.scheduleEdit();
             return;
         }
@@ -538,12 +628,18 @@ class ReplyRenderer {
             this.toolLine = undefined;
             this.runningTool = undefined;
             this.turnBreakPending = true;
+            // Words written before a call that was refused were still said
+            // before a tool, and must not run into the next response's.
+            this.flushInterim(ofThisTurn);
             this.scheduleEdit();
             return;
         }
         if (event.type === 'tool.completed') {
             this.toolLine = undefined;
             this.runningTool = undefined;
+            // Settled here too for a call rejected before it ran, which never
+            // reached `tool.called`; after one that did, this is empty.
+            this.flushInterim(ofThisTurn);
             // Also a boundary, and not only for symmetry: a call rejected before
             // execution settles as tool.completed without ever having emitted
             // tool.called, so this is the only mark that attempt leaves.
@@ -623,6 +719,98 @@ class ReplyRenderer {
         })
             .catch((error) => this.warn(`files.uploadV2 failed for ${filePath}: ${error instanceof Error ? error.message : String(error)}`));
     }
+    /**
+     * Post what the model said before the tool it is now calling, in `final`
+     * mode only: a streaming turn already shows it in its placeholder, and a
+     * turn nobody asked for must not speak before it decides to. Behind the
+     * turn ahead and any handover, on the upload chain, so interim text,
+     * files, and the reply land in the order they happened.
+     */
+    flushInterim(ofThisTurn) {
+        const text = this.interim.trim();
+        this.interim = '';
+        if (this.streaming || this.lazy || !this.turnStarted || !ofThisTurn || text.length === 0) {
+            return;
+        }
+        const handover = this.handover;
+        const after = this.after;
+        let heard = '';
+        let settleLanded;
+        const landedNow = new Promise((resolve) => {
+            settleLanded = resolve;
+        });
+        this.onInterim?.(() => heard, landedNow);
+        this.uploadChain = this.uploadChain
+            .then(() => handover)
+            .then(() => after)
+            .then(async () => {
+            const landed = [];
+            try {
+                for (const chunk of messageChunks(text)) {
+                    const posted = await this.web.chat.postMessage({
+                        channel: this.channel,
+                        text: chunk,
+                        ...(this.threadTs ? { thread_ts: this.threadTs } : {}),
+                    });
+                    this.placeText(posted.ts);
+                    landed.push(chunk);
+                }
+            }
+            finally {
+                // Whatever landed was said, whole or not: it counts as speaking,
+                // and the others hear it. Only a message that landed whole is
+                // stripped from a hosted-loop reply; part of one is left in the
+                // reply, where repeating a few lines beats losing the rest.
+                if (landed.length > 0) {
+                    this.interimPosted = true;
+                    heard = landed.length === messageChunks(text).length ? text : landed.join('\n\n');
+                }
+                settleLanded(landed.length > 0);
+            }
+            this.lastInterim = text;
+            this.interimSaid.push(text);
+            // A post of the app's in this thread takes the status down while
+            // the turn is still working; put it back.
+            this.refreshLoading();
+        })
+            .catch((error) => this.warn(`chat.postMessage failed for an interim message: ${error instanceof Error ? error.message : String(error)}`))
+            // Settled whatever happened above, or the other agents' intake would
+            // wait on it for good. A second settle is a no-op.
+            .finally(() => settleLanded(false));
+    }
+    /**
+     * Everything this turn said in the thread, for its other agents to hear:
+     * the interim messages that landed, then the reply unless it only
+     * repeats the last of them. Read once the turn's posts have landed.
+     */
+    spokenText(reply) {
+        return this.unsaid(reply);
+    }
+    /**
+     * The part of a reply not already posted as interim messages. A provider
+     * that hosts its own loop (codex) returns every message of the turn
+     * joined into one reply, so the interim messages are stripped from its
+     * front in order; one whose last words came before its final tool call
+     * returns just those words, which were posted already.
+     */
+    unsaid(reply) {
+        let rest = reply.trim();
+        // Whole messages only, at the separator the codex provider joins them
+        // with: a reply of its own that merely begins with the same words
+        // ("Sure" then "Sure, the build passes.") is not cut.
+        for (const said of this.interimSaid) {
+            if (rest === said) {
+                rest = '';
+            }
+            else if (rest.startsWith(`${said}\n\n`)) {
+                rest = rest.slice(said.length + 2).trimStart();
+            }
+            else {
+                break;
+            }
+        }
+        return rest === this.lastInterim ? '' : rest;
+    }
     currentText() {
         const parts = [this.buffer.trim(), this.toolLine].filter((part) => Boolean(part && part.length > 0));
         return parts.length > 0 ? parts.join('\n\n') : PLACEHOLDER_TEXT;
@@ -755,6 +943,22 @@ class ReplyRenderer {
             await this.uploadChain;
             return this.outcome(false, this.uploaded);
         }
+        // Interim messages land before the reply is judged: one that already
+        // said what the reply says (the model's last words came before a
+        // tool call) is not posted again, and a turn that said things along
+        // the way is not followed by `(no reply)`.
+        await this.uploadChain;
+        if (this.interimPosted && !this.ref) {
+            reply = this.unsaid(reply);
+        }
+        if (!this.ref && this.interimPosted && reply.trim().length === 0) {
+            // Nothing posts after this to take the status down, so it is cleared.
+            if (hadStatus) {
+                this.setStatus('');
+                await this.statusChain;
+            }
+            return this.outcome(true, true);
+        }
         const text = reply.trim().length > 0 ? reply : NO_REPLY_TEXT;
         const chunks = messageChunks(text);
         // No placeholder — a handover could not open a fresh one — and the
@@ -1031,6 +1235,31 @@ const pastCodePoint = (text, index) => {
     const code = text.charCodeAt(index - 1);
     return code >= 0xd800 && code <= 0xdbff ? index + 1 : index;
 };
+/**
+ * `cut` moved in front of any Slack markup it would land inside — a link
+ * `<https://…>` or `<https://…|label>`, a mention `<@U…>` — when that still
+ * leaves half a message. Cut through, the first message ends on an
+ * unterminated `<https://…` and the next starts with the rest of the
+ * address and a stray `>`, and neither half is a link. Markup is one line,
+ * so only the cut's own line is looked at.
+ */
+const outsideSlackMarkup = (text, cut) => {
+    const open = text.lastIndexOf('<', cut - 1);
+    if (open <= SLACK_MAX_MESSAGE_CHARS / 2) {
+        return cut;
+    }
+    const closedBefore = text.lastIndexOf('>', cut - 1);
+    const lineBreak = text.lastIndexOf('\n', cut - 1);
+    if (closedBefore > open || lineBreak > open) {
+        return cut;
+    }
+    const close = text.indexOf('>', cut);
+    const nextLine = text.indexOf('\n', cut);
+    if (close === -1 || (nextLine !== -1 && nextLine < close)) {
+        return cut;
+    }
+    return open;
+};
 const truncateForSlack = (text) => text.length <= SLACK_MAX_MESSAGE_CHARS
     ? text
     : `${text.slice(0, safeCutIndex(text, SLACK_MAX_MESSAGE_CHARS - 1))}…`;
@@ -1087,8 +1316,9 @@ const splitForSlack = (text) => {
         // point, or the step that guarantees progress lands inside an emoji.
         const fence = run !== undefined && run.closer.startsWith('\n');
         if (run === undefined || !fence || reopen === undefined || reopen.length + run.closer.length > SLACK_MAX_MESSAGE_CHARS / 4 || floor + 2 > budget) {
-            chunks.push(rest.slice(0, cut));
-            rest = rest.slice(cut).replace(/^\n+/, '');
+            const at = run === undefined ? outsideSlackMarkup(rest, cut) : cut;
+            chunks.push(rest.slice(0, at));
+            rest = rest.slice(at).replace(/^\n+/, '');
             continue;
         }
         const inner = rest.lastIndexOf('\n', budget - 1);
@@ -1721,6 +1951,8 @@ const credentialModal = (post, requestId) => ({
  * those were in it receives only `app_mention` and behaves as it always
  * did, which makes the workspace's own grant the switch.
  */
+/** Uncached author names one `message.read` looks up; the rest keep their id. */
+const READ_NAME_LOOKUPS = 10;
 export const createSlackChannelAdapter = (options) => {
     const log = options.log ?? (() => { });
     const warn = options.warn ?? (() => { });
@@ -1934,6 +2166,205 @@ export const createSlackChannelAdapter = (options) => {
         }
         return boundedDisplayName(await displayNameFor(connection, userId));
     };
+    /**
+     * What was said before an agent was mentioned, for the dispatch that
+     * creates its session (`earlier` on the gateway's dispatch). Without it
+     * an agent named partway through a conversation holds one message —
+     * "can you do this?" — and nothing it refers to. In a thread that is the
+     * thread so far: its parent and the newest messages before the mention.
+     * At the top of a channel it is the channel's most recent messages,
+     * which is where a channel-per-client or channel-per-project keeps the
+     * context a mention leans on.
+     *
+     * Each message keeps its own speaker and its own trust, so the session
+     * starts at the least trusted of everyone in it: a principal's mention
+     * cannot carry a stranger's earlier words in under the principal's
+     * label. Under `admit: 'principals'` a sender the operator did not list
+     * gets no place here, as they get none anywhere else. A bot's message —
+     * another agent, an integration — is `unknown`: nothing here can say
+     * what its words were built from. Messages that will not be shown are
+     * dropped before the cap is applied, so they never crowd out ones that
+     * would.
+     *
+     * A read that fails warns and returns nothing: the turn still runs, on
+     * the one message, as it did before this.
+     */
+    const earlierContext = async (connection, channel, thread, before, senderTrust) => {
+        const usable = (message) => {
+            if (message.ts === undefined || !(Number(message.ts) < Number(before))) {
+                return false;
+            }
+            // The agent's own mention is stripped when the message is shown, so
+            // a bare ping is as empty as no text, and takes no slot.
+            const text = (message.text ?? '').replaceAll(`<@${connection.botUserId}>`, '').trim();
+            if (text.length === 0 && (message.files ?? []).length === 0) {
+                return false;
+            }
+            if (message.bot_id !== undefined || message.subtype === 'bot_message') {
+                // Under `admit: 'principals'` an unlisted integration is as kept out
+                // as an unlisted person. This fleet's own agents are not: they are
+                // the conversation the mention joins — an authenticated peer whose
+                // socket failed to start included, since what it said is still its.
+                return admitsSender(connection.config, message.user ?? '')
+                    || (message.user !== undefined && [...botIdentities.values()].some((peer) => peer.teamId === connection.teamId && peer.botUserId === message.user));
+            }
+            return message.user !== undefined
+                && isPersonSpeaking({ type: 'message', ts: message.ts, channel, ...(message.subtype ? { subtype: message.subtype } : {}) })
+                && admitsSender(connection.config, message.user);
+        };
+        let kept = [];
+        let omitted = 0;
+        let more = false;
+        // The channel read stopped at its page bound short of enough messages.
+        let historyCut = false;
+        let firstOfTail = 0;
+        try {
+            if (thread !== undefined) {
+                const replies = connection.web.conversations.replies;
+                if (!replies) {
+                    return [];
+                }
+                // Slack pages a thread oldest first, so the whole thread is walked
+                // and only a bounded tail is held: the newest messages are the
+                // last ones read.
+                let parent;
+                const tail = [];
+                let cursor;
+                let pages = 0;
+                do {
+                    const page = await replies.call(connection.web.conversations, {
+                        channel,
+                        ts: thread,
+                        latest: before,
+                        inclusive: false,
+                        limit: 200,
+                        ...(cursor ? { cursor } : {}),
+                    });
+                    pages += 1;
+                    for (const message of page.messages ?? []) {
+                        if (!usable(message)) {
+                            continue;
+                        }
+                        if (message.ts === thread) {
+                            parent = message;
+                            continue;
+                        }
+                        tail.push(message);
+                        if (tail.length > EARLIER_MESSAGE_LIMIT) {
+                            tail.shift();
+                            omitted += 1;
+                        }
+                    }
+                    // Slack's cursor is the signal, not `has_more`: a short page can
+                    // still have more behind it.
+                    cursor = page.response_metadata?.next_cursor || undefined;
+                } while (cursor && pages < EARLIER_THREAD_PAGES);
+                more = cursor !== undefined;
+                if (more) {
+                    // Past the read bound the newest replies were never reached, and a
+                    // slice from the middle must not pass for them: the parent alone,
+                    // and the note says the rest was not read.
+                    omitted += tail.length;
+                    tail.length = 0;
+                }
+                // The parent takes a slot only when it is shown.
+                while (tail.length > (parent !== undefined ? EARLIER_MESSAGE_LIMIT - 1 : EARLIER_MESSAGE_LIMIT)) {
+                    tail.shift();
+                    omitted += 1;
+                }
+                kept = parent !== undefined ? [parent, ...tail] : tail;
+                firstOfTail = parent !== undefined ? 1 : 0;
+            }
+            else {
+                const history = connection.web.conversations.history;
+                if (!history) {
+                    return [];
+                }
+                // Newest first, paged until enough usable messages are found (joins
+                // and bots' chatter do not count against the limit), then put back
+                // in the order they were said.
+                const recent = [];
+                let cursor;
+                let pages = 0;
+                do {
+                    const page = await history.call(connection.web.conversations, {
+                        channel,
+                        latest: before,
+                        inclusive: false,
+                        limit: EARLIER_CHANNEL_READ,
+                        ...(cursor ? { cursor } : {}),
+                    });
+                    pages += 1;
+                    recent.push(...(page.messages ?? []).filter(usable));
+                    cursor = page.response_metadata?.next_cursor || undefined;
+                } while (cursor && recent.length < EARLIER_CHANNEL_LIMIT && pages < EARLIER_CHANNEL_PAGES);
+                historyCut = cursor !== undefined && recent.length < EARLIER_CHANNEL_LIMIT;
+                kept = recent.slice(0, EARLIER_CHANNEL_LIMIT).reverse();
+            }
+        }
+        catch (error) {
+            warn(`slack: ${connection.config.agentId} could not read the earlier messages in ${channel}, so it sees only the message that named it: `
+                + `${error instanceof Error ? error.message : String(error)} (the history scopes are channels:history, groups:history, and mpim:history)`);
+            return [];
+        }
+        const entries = [];
+        for (const [index, message] of kept.entries()) {
+            const bot = message.bot_id !== undefined || message.subtype === 'bot_message';
+            const text = await humanizeMentions(connection, message.text ?? '');
+            const files = message.files ?? [];
+            const author = bot
+                ? message.user === connection.botUserId
+                    ? 'you'
+                    : boundedDisplayName(message.bot_profile?.name ?? message.username ?? 'a bot')
+                : await authorFor(connection, message.user);
+            const reasons = new Map(files.map((file) => [file, 'not-opened']));
+            let note = '';
+            if (thread === undefined && index === 0) {
+                note = historyCut
+                    ? `[The ${kept.length} messages found in this channel's recent history before you were mentioned, oldest first. Older history was not read; ask for what you need.]\n`
+                    : `[The ${kept.length} most recent messages in this channel before you were mentioned, oldest first:]\n`;
+            }
+            else if (thread !== undefined && index === firstOfTail && omitted > 0 && !more) {
+                note = `[${omitted} earlier messages in this thread are not shown.]\n`;
+            }
+            entries.push({
+                message: `${note}${author}: ${text}${attachmentNote(files, reasons)}`,
+                metadata: {
+                    channel: 'slack',
+                    slackChannel: channel,
+                    ...(thread !== undefined ? { slackThread: thread } : {}),
+                    ...(message.user !== undefined ? { slackUser: message.user } : {}),
+                    [SENDER_TRUST_METADATA_KEY]: bot ? 'unknown' : senderTrustFor(connection.config, message.user),
+                },
+            });
+        }
+        if (historyCut && entries.length === 0) {
+            entries.push({
+                message: '[None of this channel\'s recent history before you were mentioned could be shown, and older history was not read. Ask for what you need.]',
+                // The adapter's own words, nobody else's: they carry the trust of
+                // the message they arrive with, and lower nothing.
+                metadata: { channel: 'slack', slackChannel: channel, [SENDER_TRUST_METADATA_KEY]: senderTrust },
+            });
+        }
+        if (more) {
+            // With no first message to show (unusable, or from someone the room
+            // does not admit), the notice stands alone: an empty backfill would
+            // read as a thread with nothing before the mention. It is the
+            // adapter's own words, so it carries the trust of the message it
+            // arrives with and lowers nothing.
+            const notice = '[This thread is too long to read here: the replies after its first message are not shown. Ask for what you need.]';
+            if (entries.length > 0) {
+                entries[entries.length - 1].message += `\n${notice}`;
+            }
+            else {
+                entries.push({
+                    message: notice,
+                    metadata: { channel: 'slack', slackChannel: channel, ...(thread !== undefined ? { slackThread: thread } : {}), [SENDER_TRUST_METADATA_KEY]: senderTrust },
+                });
+            }
+        }
+        return entries;
+    };
     /**
      * What kind of room a conversation is and how many are in it, for the
      * turn's `conversation` metadata: an agent that did not know told
@@ -1980,6 +2411,7 @@ export const createSlackChannelAdapter = (options) => {
                 kind,
                 ...(kind !== 'direct' && typeof info.num_members === 'number' ? { members: info.num_members } : {}),
                 ...(kind !== 'direct' && (info.is_ext_shared === true || info.is_org_shared === true) ? { shared: true } : {}),
+                ...(kind !== 'direct' && typeof info.id === 'string' ? { id: info.id } : {}),
             };
         }
         catch {
@@ -2009,9 +2441,108 @@ export const createSlackChannelAdapter = (options) => {
         }
         return result.trim();
     };
+    /**
+     * Slack's stored `mrkdwn` as the plain text a read promises
+     * (`ConversationMessage.text`): `<@U…>` mentions, `<#C…|name>` channels,
+     * `<!here>`-style broadcasts, `<!date^…|fallback>` dates, and
+     * `<url|label>` links, then the `&lt; &gt; &amp;` escapes, decoded last
+     * so text someone typed is never read as markup. A mention is named only
+     * for a principal or the agent's own app, for the reason
+     * `humanizeMentions` gives; anyone else stays their stable id.
+     */
+    const nameableMentions = (connection, text) => {
+        const principals = new Set(connection.config.principals ?? []);
+        const ids = new Set();
+        for (const match of text.matchAll(/<@([^|<>]+)(?:\|[^<>]*)?>/g)) {
+            const id = match[1];
+            if (principals.has(id) || id === connection.botUserId) {
+                ids.add(id);
+            }
+        }
+        return [...ids];
+    };
+    /**
+     * `resolved` is the only source of names: the caller has already looked
+     * them up under its own bound (`readConversation`), and a mention it did
+     * not resolve stays an id rather than costing a lookup here.
+     */
+    const plainSlackText = (connection, text, resolved) => {
+        const names = new Map();
+        for (const id of nameableMentions(connection, text)) {
+            const name = resolved.get(id);
+            if (name !== undefined) {
+                names.set(id, boundedDisplayName(name));
+            }
+        }
+        return text
+            .replace(/<([^<>]*)>/g, (_whole, inner) => {
+            const bar = inner.indexOf('|');
+            const target = bar === -1 ? inner : inner.slice(0, bar);
+            const label = bar === -1 ? undefined : inner.slice(bar + 1);
+            if (target.startsWith('@')) {
+                const id = target.slice(1);
+                return `@${names.get(id) ?? id}`;
+            }
+            if (target.startsWith('#')) {
+                return `#${label || target.slice(1)}`;
+            }
+            if (target.startsWith('!')) {
+                const command = target.slice(1);
+                if (command.startsWith('subteam^')) {
+                    return label || `@${command.slice('subteam^'.length)}`;
+                }
+                if (command.startsWith('date^')) {
+                    return label ?? command;
+                }
+                return `@${command}`;
+            }
+            if (label && label !== target) {
+                return `${label} (${target})`;
+            }
+            return target;
+        })
+            .replaceAll('&lt;', '<')
+            .replaceAll('&gt;', '>')
+            .replaceAll('&amp;', '&');
+    };
     const connectionFor = (agentId) => connections.find((candidate) => candidate.config.agentId === agentId);
     /** An agent's configuration, whether or not its socket came up. */
     const agentConfigFor = (agentId) => options.agents.find((candidate) => candidate.agentId === agentId);
+    /**
+     * Which agent each home channel belongs to, keyed `team:channel` because
+     * a channel id is unique only within its workspace. Settled at start,
+     * once every app has authenticated and its team is known. A channel two
+     * agents in one workspace both call home belongs to neither: two agents
+     * answering every message there is the double reply the thread rules
+     * exist to prevent, and picking one would hang on an order the config
+     * file does not reliably carry (JSON objects enumerate integer-like keys
+     * numerically). Both still answer there when mentioned, and a startup
+     * warning says so.
+     */
+    const homeOwners = new Map();
+    const settleHomeOwners = () => {
+        homeOwners.clear();
+        const claims = new Map();
+        for (const agent of options.agents) {
+            const teamId = botIdentities.get(agent.agentId)?.teamId;
+            if (teamId === undefined) {
+                continue;
+            }
+            for (const channelId of agent.homeChannels ?? []) {
+                const key = `${teamId}:${channelId}`;
+                claims.set(key, [...(claims.get(key) ?? []), agent.agentId]);
+            }
+        }
+        for (const [key, claimants] of claims) {
+            const agentIds = [...new Set(claimants)];
+            if (agentIds.length === 1) {
+                homeOwners.set(key, agentIds[0]);
+                continue;
+            }
+            const channelId = key.slice(key.indexOf(':') + 1);
+            warn(`slack: ${channelId} is a home channel for ${agentIds.join(' and ')}; a channel can be home to one agent, so none of them answers there unless mentioned.`);
+        }
+    };
     /**
      * How an agent listens, from its soul — read per message, so a roster
      * reload takes effect on the next one. `thread` when the soul says
@@ -2153,7 +2684,7 @@ export const createSlackChannelAdapter = (options) => {
      */
     const overhearReply = async (speaker, channel, thread, reply, spoken, published) => {
         const gateway = gatewayRef;
-        if (!gateway?.observe || reply.trim().length === 0) {
+        if (!gateway?.observe || (typeof reply === 'string' && reply.trim().length === 0)) {
             return;
         }
         const team = speaker.teamId;
@@ -2163,7 +2694,6 @@ export const createSlackChannelAdapter = (options) => {
             slackChannel: channel,
             slackUser: speaker.botUserId,
             slackThread: thread,
-            [SENDER_TRUST_METADATA_KEY]: sessionWriteTrust(spoken),
         };
         // In the reply's own workspace only, because a session key carries a
         // team — the same reason `resolveFollowUpWinner` stays in-workspace.
@@ -2181,6 +2711,13 @@ export const createSlackChannelAdapter = (options) => {
                     if (!(await published)) {
                         return { observed: undefined };
                     }
+                    // Read now that the posts have landed: what the turn said along
+                    // the way is known only once they have.
+                    const text = typeof reply === 'string' ? reply : reply();
+                    if (text.trim().length === 0) {
+                        return { observed: undefined };
+                    }
+                    const trust = sessionWriteTrust(typeof spoken === 'function' ? await spoken() : spoken);
                     let member;
                     try {
                         member = (await hearer.web.conversations.info({ channel })).channel?.is_member;
@@ -2195,7 +2732,7 @@ export const createSlackChannelAdapter = (options) => {
                     // spoke, by display name. A bot user's is the app's own, set by
                     // whoever installed it.
                     const author = await displayNameFor(hearer, speaker.botUserId);
-                    const observed = gateway.observe?.({ sessionId, agentId: hearer.config.agentId, message: `${author}: ${reply}`, metadata });
+                    const observed = gateway.observe?.({ sessionId, agentId: hearer.config.agentId, message: `${author}: ${text}`, metadata: { ...metadata, [SENDER_TRUST_METADATA_KEY]: trust } });
                     return { observed: observed === undefined ? undefined : placeObserve(sessionId, observed) };
                 });
                 await observed;
@@ -2247,12 +2784,15 @@ export const createSlackChannelAdapter = (options) => {
         }
         const channelId = conversation.id;
         const web = connection.web;
+        // A reply under a message rather than a post beside it. Every chunk of
+        // a long one goes to the same thread, so a split reply stays together.
+        const thread = address.thread?.trim() || undefined;
         return {
             async post(text) {
                 const chunks = messageChunks(text.trim().length > 0 ? text : '(empty message)');
                 let first;
                 for (const chunk of chunks) {
-                    const posted = await web.chat.postMessage({ channel: channelId, text: chunk });
+                    const posted = await web.chat.postMessage({ channel: channelId, text: chunk, ...(thread ? { thread_ts: thread } : {}) });
                     if (!first) {
                         first = { channel: posted.channel ?? channelId, ts: posted.ts ?? '' };
                     }
@@ -2275,6 +2815,130 @@ export const createSlackChannelAdapter = (options) => {
             },
         };
     };
+    /**
+     * The read side of the same boundary `resolveOutbound` draws: a channel
+     * the agent's own app is a member of, public or private. DMs and group
+     * DMs are refused outright, member or not. Their only members are the
+     * people in them, and a read from a conversation elsewhere — a public
+     * thread above all — would carry what they said to people who were never
+     * in the room. A thread in a channel is fine for the same reason the
+     * channel is.
+     */
+    const readConversation = async (request) => {
+        const channel = request.conversation.trim();
+        if (!channel) {
+            throw new Error('slack: a read needs a channel id (C…/G…).');
+        }
+        const connection = connectionFor(request.agentId);
+        if (!connection) {
+            throw new Error(configuredAgents.has(request.agentId)
+                ? `slack: ${request.agentId}'s Slack app is not connected right now, so ${channel} cannot be read.`
+                : `slack: agent ${request.agentId} has no Slack app, so it cannot read Slack at all.`);
+        }
+        let info;
+        try {
+            info = (await connection.web.conversations.info({ channel })).channel;
+        }
+        catch (error) {
+            throw new Error(`slack: ${request.agentId}'s app cannot see ${channel} (${error instanceof Error ? error.message : String(error)}). `
+                + 'Use the channel id, not a name.');
+        }
+        if (!info?.id) {
+            throw new Error(`slack: ${request.agentId}'s app cannot see a conversation ${channel}.`);
+        }
+        if (info.is_im === true || info.is_mpim === true) {
+            throw new Error(`slack: ${channel} is a direct message, and direct messages are never read from outside them.`);
+        }
+        if (info.is_member !== true) {
+            throw new Error(`slack: ${request.agentId}'s app is not a member of ${channel} — invite it there before it can read.`);
+        }
+        const { history, replies } = connection.web.conversations;
+        const fetchPage = request.thread !== undefined
+            ? (replies ? (args) => replies({ ...args, ts: request.thread }) : undefined)
+            : history;
+        if (!fetchPage) {
+            throw new Error(`slack: this Slack client cannot read ${request.thread !== undefined ? 'threads' : 'channel history'}.`);
+        }
+        const base = {
+            channel: info.id,
+            inclusive: false,
+            ...(request.after !== undefined ? { oldest: request.after } : {}),
+            ...(request.before !== undefined ? { latest: request.before } : {}),
+        };
+        const raw = [];
+        let cursor;
+        let more = false;
+        do {
+            const page = await fetchPage({ ...base, limit: Math.min(200, request.limit - raw.length), ...(cursor ? { cursor } : {}) });
+            raw.push(...(page.messages ?? []));
+            cursor = page.response_metadata?.next_cursor || undefined;
+            more = cursor !== undefined || page.has_more === true;
+        } while (cursor && raw.length < request.limit);
+        if (raw.length > request.limit) {
+            raw.length = request.limit;
+            more = true;
+        }
+        // History rarely embeds profiles, so names mostly come from users.info.
+        // Cached names are free; at most READ_NAME_LOOKUPS uncached people —
+        // authors and the mentions in their text together — are looked up per
+        // read, at once, and the rest keep their id, so a read of many strangers
+        // never waits through a rate limit one call at a time.
+        const lookups = new Map();
+        let fresh = 0;
+        const want = (user) => {
+            if (lookups.has(user)) {
+                return;
+            }
+            const cached = displayNames.get(`${connection.teamId}:${user}`);
+            if (cached) {
+                lookups.set(user, Promise.resolve(cached));
+            }
+            else if (fresh < READ_NAME_LOOKUPS) {
+                fresh += 1;
+                lookups.set(user, displayNameFor(connection, user));
+            }
+        };
+        for (const message of raw) {
+            const user = message.user;
+            if (user && !message.user_profile?.display_name && !message.user_profile?.real_name) {
+                want(user);
+            }
+        }
+        for (const message of raw) {
+            for (const id of nameableMentions(connection, message.text ?? '')) {
+                want(id);
+            }
+        }
+        const names = new Map();
+        for (const [user, name] of lookups) {
+            names.set(user, await name);
+        }
+        const messages = [];
+        for (const message of raw) {
+            if (!message.ts) {
+                continue;
+            }
+            const author = message.user ?? message.bot_id ?? 'unknown';
+            const name = message.user_profile?.display_name
+                || message.user_profile?.real_name
+                || message.bot_profile?.name
+                || message.username
+                || (message.user ? names.get(message.user) : undefined);
+            const at = Number.parseFloat(message.ts);
+            const files = (message.files ?? []).map((file) => file.name ?? file.title ?? file.id ?? 'file');
+            messages.push({
+                id: message.ts,
+                author,
+                text: plainSlackText(connection, message.text ?? '', names),
+                ...(name && name !== author ? { authorName: boundedDisplayName(name) } : {}),
+                ...(Number.isFinite(at) ? { at: new Date(at * 1000).toISOString() } : {}),
+                ...(message.thread_ts && message.thread_ts !== message.ts ? { thread: message.thread_ts } : {}),
+                ...(message.reply_count ? { replies: message.reply_count } : {}),
+                ...(files.length > 0 ? { files } : {}),
+            });
+        }
+        return { messages, more };
+    };
     /**
      * Renders one parked call as buttons and remembers where it went.
      *
@@ -3251,6 +3915,24 @@ export const createSlackChannelAdapter = (options) => {
         }
         const first = engaged[0];
         if (!first) {
+            // No agent has a session in this thread, but one may have STARTED
+            // it: a post made through message.send or a schedule's delivery
+            // lands at the top level from some other session, so nothing ties
+            // the thread under it to the agent that wrote it. A reply there is
+            // a reply to that agent. Read off the event, so every connection
+            // reaches the same answer, and after a restart too. Looked up among
+            // authenticated identities, not live sockets: they are all learned
+            // before any socket starts, so an agent whose socket is still coming
+            // up is not judged absent and the memoized verdict cannot drop the
+            // reply when its own socket delivers it.
+            if (parts.parentUser === undefined) {
+                return undefined;
+            }
+            for (const [agentId, identity] of botIdentities) {
+                if (identity.teamId === parts.team && identity.botUserId === parts.parentUser) {
+                    return agentId;
+                }
+            }
             return undefined;
         }
         if (engaged.length === 1) {
@@ -3372,7 +4054,7 @@ export const createSlackChannelAdapter = (options) => {
             ? threadKeyFor({ team, conversation: event.channel, thread })
             : undefined;
         const text = event.text ?? '';
-        const addressed = isDm || mentions(text, connection.botUserId);
+        const mentioned = isDm || mentions(text, connection.botUserId);
         // Who this message hands the thread to — worked out by EVERY connection
         // that sees it, not only by the one being named, and recorded before any
         // of the rejections below. Each agent is its own Socket Mode connection,
@@ -3395,6 +4077,15 @@ export const createSlackChannelAdapter = (options) => {
         // no policy, and nobody's to refuse here, so it admits.
         const handoverTo = agentNamedIn(text, team, (agentId) => admitsSender(agentConfigFor(agentId), sender));
         const named = handoverTo ?? agentNamedIn(text, team);
+        // A new top-level message in this agent's home channel is addressed to
+        // it as surely as a mention would be — unless it names somebody else,
+        // which hands it to them exactly as it would anywhere. Top-level only:
+        // inside a thread the soul's `listens` already says what an untagged
+        // reply is, and the home channel does not overrule it.
+        const homeOwner = !isDm && event.thread_ts === undefined && named === undefined
+            ? homeOwners.get(`${team}:${event.channel}`)
+            : undefined;
+        const addressed = mentioned || homeOwner === connection.config.agentId;
         // The key one Slack MESSAGE is known by, whichever delivery carried
         // it; see the dedupe below for why it is not the event id.
         const eventKey = `${connection.config.agentId}:${event.channel}:${event.ts}`;
@@ -3409,6 +4100,15 @@ export const createSlackChannelAdapter = (options) => {
         if (threadKey && handoverTo) {
             rememberAddressee(threadKey, handoverTo, event.ts);
         }
+        // A home-channel message hands its new thread to the channel's owner
+        // the way a mention would, and is recorded by every socket for the same
+        // reason: a reply in that thread can reach another agent's socket before
+        // the owner's first turn has written any session routing, and without
+        // this record every agent would stand down and the reply would be lost.
+        // On the owner's admission, as a handover is.
+        if (threadKey && homeOwner !== undefined && admitsSender(agentConfigFor(homeOwner), sender)) {
+            rememberAddressee(threadKey, homeOwner, event.ts);
+        }
         // Who may speak at all, judged before anything below remembers this
         // message. The adapter's own checks establish nothing about who is
         // typing; under `admit: 'principals'` the operator's list is the door,
@@ -3448,7 +4148,12 @@ export const createSlackChannelAdapter = (options) => {
                 // place in that queue, and the line is an audit, not a turn; `track`
                 // holds it so `stop()` drains it like any other background work.
                 const thread = event.thread_ts;
-                track(followUpWinner({ team, conversation: event.channel, thread }, event.ts).then((winner) => {
+                track(followUpWinner({
+                    team,
+                    conversation: event.channel,
+                    thread,
+                    ...(event.parent_user_id !== undefined ? { parentUser: event.parent_user_id } : {}),
+                }, event.ts).then((winner) => {
                     if (winner === connection.config.agentId) {
                         log(refusal);
                     }
@@ -3627,7 +4332,12 @@ export const createSlackChannelAdapter = (options) => {
             if (!admitted.settled) {
                 // One verdict for this message, shared with whichever other agents
                 // are asking about it — see `followUpWinner`.
-                const winner = await followUpWinner({ team, conversation: event.channel, thread: event.thread_ts ?? '' }, event.ts);
+                const winner = await followUpWinner({
+                    team,
+                    conversation: event.channel,
+                    thread: event.thread_ts ?? '',
+                    ...(event.parent_user_id !== undefined ? { parentUser: event.parent_user_id } : {}),
+                }, event.ts);
                 if (winner !== connection.config.agentId) {
                     // Not this agent's to answer — and, if it is in the thread,
                     // this agent's to hear, same as the two warm stand-downs.
@@ -3735,6 +4445,29 @@ export const createSlackChannelAdapter = (options) => {
             // if it ever has any — see `ReplyRenderer.lazy`. One the agent's
             // reply mode does not stream opens none at all, and shows the
             // loading status instead — see `ReplyRenderer.streaming`.
+            // Mentioned into a thread partway: hand the new session what was
+            // said before this. Inside the chain, before the placeholder, so the
+            // read cannot reorder this message against the next one.
+            let earlier = [];
+            if (!isDm && thread !== undefined) {
+                // A top-level mention roots its own session, so it is new but for
+                // a redelivery, which the gateway answers without reading this.
+                let exists = false;
+                if (thread !== event.ts && gateway.sessionRouting) {
+                    try {
+                        exists = (await gateway.sessionRouting(sessionId)) !== undefined;
+                    }
+                    catch {
+                        // Unknown is read as new: a session that does exist ignores
+                        // the list, so the cost of guessing wrong is one API read.
+                    }
+                }
+                if (!exists) {
+                    // A mention that starts its own thread follows the channel; one
+                    // inside a thread follows that thread.
+                    earlier = await earlierContext(connection, event.channel, thread === event.ts ? undefined : thread, event.ts, senderTrust);
+                }
+            }
             const streaming = connection.config.replies === 'stream';
             const ahead = streaming ? undefined : replyOrder.get(sessionId);
             const renderer = new ReplyRenderer(connection.web, event.channel, thread, editIntervalMs, warn, {
@@ -3745,6 +4478,25 @@ export const createSlackChannelAdapter = (options) => {
                 statusWarned: connection.statusWarned,
                 ...(ahead ? { after: ahead } : {}),
                 ...(isDm ? { dmWith: userId } : {}),
+                // Each interim message, as it lands, takes its place in the
+                // thread's other agents' sessions — ahead of a follow-up typed
+                // while the tool it preceded is still running. Under the session's
+                // label as stored, lowered by anything that tainted it during this
+                // turn, and the least trusted label where it cannot be read.
+                ...(thread !== undefined
+                    ? {
+                        onInterim: (heard, landed) => {
+                            // Tracked, so a shutdown drains it like any other reaction:
+                            // the text is already in the thread, whatever the turn does.
+                            track(overhearReply(connection, event.channel, thread, heard, async () => {
+                                const routed = await gateway.sessionRouting?.(sessionId).catch(() => undefined);
+                                const stored = routed ? sessionTrustOf(routed) : 'external';
+                                const live = renderer.taintedTo === undefined ? stored : leastTrusted(stored, renderer.taintedTo);
+                                return { metadata: { [SESSION_TRUST_METADATA_KEY]: live } };
+                            }, landed));
+                        },
+                    }
+                    : {}),
             });
             if (!streaming) {
                 replyOrder.set(sessionId, renderer.posted);
@@ -3782,6 +4534,7 @@ export const createSlackChannelAdapter = (options) => {
                 userMessage,
                 ...(images.length > 0 ? { images } : {}),
                 ...(judged ? { addressed: false } : {}),
+                ...(earlier.length > 0 ? { earlier } : {}),
                 turnId: renderer.turnId,
                 metadata,
                 // A redelivery this process no longer remembers (it restarted, or
@@ -3902,8 +4655,17 @@ export const createSlackChannelAdapter = (options) => {
             // rule with the gateway's `sessionRouting`, which posts the same
             // message for a turn this adapter did not start.
             const finalized = renderer.finalize(renderer.lazy ? reply ?? '' : reply ?? NO_REPLY_TEXT);
-            const heard = thread !== undefined && reply !== undefined
-                ? overhearReply(connection, event.channel, thread, reply, session, finalized.then((outcome) => outcome.published))
+            // What the turn said along the way as well as its reply: interim
+            // messages are in the thread, so they are in what the others hear.
+            // Heard once the posts have settled, and the reply only if it landed:
+            // interim messages already in the thread are heard either way.
+            let replyLanded = false;
+            const settled = finalized.then((outcome) => {
+                replyLanded = outcome.published;
+                return true;
+            }, () => true);
+            const heard = thread !== undefined
+                ? overhearReply(connection, event.channel, thread, () => renderer.spokenText(replyLanded ? reply ?? '' : ''), session, settled)
                 : undefined;
             const { spoke, spokeAt } = await finalized;
             if (spoke && threadKey !== undefined) {
@@ -3938,6 +4700,7 @@ export const createSlackChannelAdapter = (options) => {
     return {
         name: 'slack',
         resolveOutbound,
+        readConversation,
         requestCredential,
         async start(gateway) {
             gatewayRef = gateway;
@@ -4072,6 +4835,7 @@ export const createSlackChannelAdapter = (options) => {
                     const auth = await web.auth.test();
                     const botUserId = auth.user_id ?? '';
                     const teamId = auth.team_id ?? '';
+                    checkBotScopes(config.agentId, auth.response_metadata?.scopes ?? [], warn);
                     // Recorded before the socket is even built: an app that never
                     // comes up must still be recognizable when somebody names it.
                     botIdentities.set(config.agentId, { botUserId, teamId });
@@ -4089,6 +4853,7 @@ export const createSlackChannelAdapter = (options) => {
                     warn(`slack: could not connect ${config.agentId}: ${error instanceof Error ? error.message : String(error)}`);
                 }
             }
+            settleHomeOwners();
             for (const connection of authenticated) {
                 const { config, socket } = connection;
                 try {
@@ -4153,6 +4918,7 @@ export const createSlackChannelAdapter = (options) => {
             coldVerdicts.clear();
             pendingObserves.clear();
             botIdentities.clear();
+            homeOwners.clear();
             rendering.clear();
             resolvedWhileRendering.clear();
             credentialsPosting.clear();