@stratusagent/channel-slack 0.11.5 → 0.11.7

package/dist/index.js

@@ -1,10 +1,10 @@
-import { randomUUID } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
+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, latestTurnReply, 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 { channelSessionKey, } from '@stratusagent/channels';
-import { toSlackMrkdwn } from "./mrkdwn.js";
+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 { admitsSender, channelSessionKey, senderTrustFor, } from '@stratusagent/channels';
+import { codeRunsOf, toSlackMrkdwn } from "./mrkdwn.js";
 /**
  * The longest display name the model is shown. Slack caps profile names
  * well under this; the bound is for a profile that is not a name.
@@ -141,6 +141,68 @@ export const createSlackFileFetcher = (fetchImpl) => async (url, botToken, signa
     return { status: response.status, ...typed, body: Buffer.concat(chunks) };
 };
 const defaultFetchFile = (url, botToken, signal, maxBytes) => createSlackFileFetcher(fetch)(url, botToken, signal, maxBytes);
+/**
+ * The dispatch's idempotency key for a message's dedupe key: the key itself
+ * when it fits the gateway's bound, and a digest of it when it does not —
+ * an agent id is not length-bounded (overlong ids that predate validation
+ * are kept), and a key over the bound would refuse every message for that
+ * agent. Deterministic, so a redelivery after a restart maps to the same.
+ */
+const dispatchKeyFor = (eventKey) => eventKey.length <= MAX_IDEMPOTENCY_KEY_LENGTH ? eventKey : `slack-sha256:${createHash('sha256').update(eventKey).digest('hex')}`;
+const NOTHING_REPORTED = { said: false, landed: [] };
+/**
+ * How far a file's change time may run past the record of the tool result
+ * naming it: the rest of the millisecond the record was stamped in, since
+ * the record is whole milliseconds and the file time is finer. No more,
+ * because any window is one an overwrite fits inside — two seconds was, in
+ * review. A filesystem that rounds file times up, coarser than that, fails
+ * closed: the file is warned about and not uploaded, which a repeat can
+ * afford and a wrong attachment cannot.
+ */
+const PRODUCED_AT_SLACK_MS = 1;
+/**
+ * A file a finished turn produced, read for a repeat of it — refused unless
+ * it is provably the file the turn left there. The transcript keeps a path,
+ * not the bytes, and a repeat can come after a later turn or another
+ * process has written the same path; uploading what is there now would
+ * answer the old message with a different file, or a sensitive one.
+ *
+ * The change time, not the modification time, is what is compared: it
+ * moves on every write, on a rename into the path, and on `utimes` itself,
+ * so neither an older file renamed in nor a backdated one passes. Then the
+ * path has to name the same file before and after it is opened — the open
+ * handle's file, when it is not a link — and the handle has to be unchanged
+ * after the read, so a swap or a write landing between the checks and the
+ * read is caught rather than uploaded.
+ */
+const readUnchangedSince = async (filePath, producedAt) => {
+    // Exclusive: a change time at or past it was a change after the record.
+    const writtenBefore = producedAt + PRODUCED_AT_SLACK_MS;
+    const changed = () => new Error('it was changed after the turn that produced it, so it may hold another file now; it was not uploaded.');
+    const named = await lstat(filePath);
+    if (named.ctimeMs >= writtenBefore) {
+        throw changed();
+    }
+    const handle = await open(filePath, 'r');
+    try {
+        const opened = await handle.stat();
+        const stillNamed = await lstat(filePath);
+        const samePath = stillNamed.ino === named.ino && stillNamed.dev === named.dev && stillNamed.ctimeMs === named.ctimeMs;
+        const sameFile = named.isSymbolicLink() || (opened.ino === named.ino && opened.dev === named.dev);
+        if (!samePath || !sameFile || opened.ctimeMs >= writtenBefore) {
+            throw changed();
+        }
+        const data = await handle.readFile();
+        const after = await handle.stat();
+        if (after.ctimeMs !== opened.ctimeMs || after.size !== data.length) {
+            throw changed();
+        }
+        return data;
+    }
+    finally {
+        await handle.close();
+    }
+};
 /**
  * A clock reading as a Slack timestamp, for a file whose upload answered
  * with no share ts. Slack timestamps are epoch seconds with six decimals,
@@ -205,6 +267,15 @@ class ReplyRenderer {
      * writes into the fresh one rather than over the reply it was given to.
      */
     handover = Promise.resolve();
+    /**
+     * The report of a turn nobody was rendering, made ahead of this renderer
+     * while it waited — through its placeholder or as messages of their own
+     * — resolving to what of that outcome reached the thread. Set when the
+     * report is claimed, before the turn it reports lets this renderer's
+     * dispatch go, so a repeat resolving after it can tell its own turn was
+     * that one, and post only what the report did not.
+     */
+    outcomeReportedAhead;
     /**
      * Bumped by a handover. An edit scheduled before it carries the text of
      * the turn that was handed over — the recovery's stream, routed to this
@@ -280,6 +351,13 @@ class ReplyRenderer {
     /** The tool the turn is running, for the status line; the streamed `toolLine` is the other mode's. */
     runningTool;
     web;
+    /**
+     * The one person in the conversation when this turn is a DM: whoever sent
+     * the message. Undefined in a channel, where who can see a thread is
+     * Slack's membership to answer, not this turn's.
+     */
+    dmWith;
+    /** The conversation, and the thread in it, this turn replies into. */
     channel;
     threadTs;
     editIntervalMs;
@@ -297,6 +375,7 @@ class ReplyRenderer {
         this.statusThread = options.statusThread ?? threadTs;
         this.statusWarned = options.statusWarned ?? { value: false };
         this.after = options.after ?? Promise.resolve();
+        this.dmWith = options.dmWith;
     }
     /**
      * Show Slack's loading status for this turn, and keep it up until the
@@ -309,10 +388,12 @@ class ReplyRenderer {
             return;
         }
         this.loading = true;
-        // A thread has one status per app, so a turn queued behind another
-        // must not publish its own: it would overwrite what the running turn
-        // says it is doing. It publishes when it reaches the head (`beginTurn`,
-        // or `refreshLoading` once the turn ahead has posted).
+        // A thread has one status per app, so a turn queued behind another in
+        // the same thread must not publish its own: it would overwrite what the
+        // running turn says it is doing. It publishes when it reaches the head
+        // (`beginTurn`, or `refreshLoading` once the turn ahead has posted).
+        // The caller passes `head` for a queued turn whose status lives on a
+        // key of its own — every DM message is — since it overwrites nothing.
         if (head) {
             this.publishLoading();
         }
@@ -482,11 +563,21 @@ class ReplyRenderer {
             }
         }
     }
+    /**
+     * Upload files a turn produced that no event delivered: a repeat of a
+     * finished turn has only the session to read them from (`turnFilesFor`),
+     * and a path written since then is refused (see `readUnchangedSince`).
+     */
+    queueFiles(files) {
+        for (const file of files) {
+            this.queueUpload(file.path, Date.parse(file.producedAt));
+        }
+    }
     // Tool results that reference local output files (a screenshot, a
     // generated report) become real attachments in the conversation — the
     // channel contract's upload operation. Uploads chain so they land in
     // order and finalize() waits for them.
-    queueUpload(filePath) {
+    queueUpload(filePath, producedAt) {
         // Behind a handover in progress, for the same reason edits and the
         // finalize are: the turn being handed the placeholder has its own
         // attachments to put in the thread first, and an upload is a message
@@ -504,7 +595,7 @@ class ReplyRenderer {
             // not a path, and a missing file surfaces as this upload's own
             // failure instead of an unhandled stream error.
             .then(async () => {
-            const data = await readFile(filePath);
+            const data = producedAt === undefined ? await readFile(filePath) : await readUnchangedSince(filePath, producedAt);
             // Where the file will sit is Slack's to say — the ts of the
             // message it becomes, in the shares the upload answers with. When
             // the answer carries none, the clock stands in, read BEFORE the
@@ -755,6 +846,44 @@ class ReplyRenderer {
         this.textAt = undefined;
         return true;
     }
+    /**
+     * Stand down without saying anything: the message this renderer was
+     * opened for repeated one whose turn another delivery in this process
+     * is still waiting on, and that delivery posts the answer. Whatever this
+     * renderer put up — a placeholder, a loading status — comes down, so a
+     * redelivery leaves no trace.
+     */
+    async withdraw() {
+        try {
+            await this.handover;
+            const hadStatus = this.statusTimer !== undefined;
+            this.stopLoading();
+            this.finalized = true;
+            // The barrier `finalizeInOrder` takes, for the same reason: the turn
+            // queued behind this one waits on `posted`, and settling it before
+            // the reply ahead has posted would let that turn's reply overtake it.
+            if (!this.streaming) {
+                await this.after;
+                await this.statusChain;
+            }
+            if (this.pendingEdit) {
+                clearTimeout(this.pendingEdit);
+                this.pendingEdit = undefined;
+            }
+            await this.editChain;
+            // A repeat can queue files the report ahead of it could not post
+            // and then stand down: they land before it settles.
+            await this.uploadChain;
+            await this.retract();
+            if (hadStatus) {
+                this.setStatus('');
+                await this.statusChain;
+            }
+        }
+        finally {
+            this.settle();
+        }
+    }
     async fail(message) {
         // The same wait `finalize` takes, for the same reason: a lazy turn's
         // first text may be opening its placeholder right now, and a failure
@@ -894,9 +1023,23 @@ const safeCutIndex = (text, index) => {
     const code = text.charCodeAt(index - 1);
     return code >= 0xd800 && code <= 0xdbff ? index - 1 : index;
 };
+/** `index` moved forward, never back, off the middle of a surrogate pair. */
+const pastCodePoint = (text, index) => {
+    const code = text.charCodeAt(index - 1);
+    return code >= 0xd800 && code <= 0xdbff ? index + 1 : index;
+};
 const truncateForSlack = (text) => text.length <= SLACK_MAX_MESSAGE_CHARS
     ? text
     : `${text.slice(0, safeCutIndex(text, SLACK_MAX_MESSAGE_CHARS - 1))}…`;
+/**
+ * Text as however many messages Slack's limit makes it, never leaving a
+ * code block broken across the cut. A cut blind to fences ended one
+ * message on an unterminated block and started the next mid-block, where
+ * Slack read the rest of somebody's log as prose — every `*` and `_` in it
+ * formatting. So a cut that would land inside a code run moves in front of
+ * it when that still leaves a message worth sending, and otherwise closes
+ * the run at the cut and reopens it in the next.
+ */
 const splitForSlack = (text) => {
     if (text.length <= SLACK_MAX_MESSAGE_CHARS) {
         return [text];
@@ -906,11 +1049,49 @@ const splitForSlack = (text) => {
     while (rest.length > SLACK_MAX_MESSAGE_CHARS) {
         // Prefer a newline break inside the window; fall back to a hard cut.
         const window = rest.slice(0, SLACK_MAX_MESSAGE_CHARS);
-        const breakAt = window.lastIndexOf('\n') > SLACK_MAX_MESSAGE_CHARS / 2
-            ? window.lastIndexOf('\n')
-            : safeCutIndex(rest, SLACK_MAX_MESSAGE_CHARS);
-        chunks.push(rest.slice(0, breakAt));
-        rest = rest.slice(breakAt).replace(/^\n+/, '');
+        const newline = window.lastIndexOf('\n');
+        const cut = newline > SLACK_MAX_MESSAGE_CHARS / 2 ? newline : safeCutIndex(rest, SLACK_MAX_MESSAGE_CHARS);
+        // Scanned two messages deep, not to the end: rescanning the whole rest
+        // for every chunk made a megabyte reply quadratic on the event loop. A
+        // fence that closes past the window still reads as open to its end,
+        // which is what it is here; an inline span that does is longer than a
+        // message, and is cut as text either way.
+        const run = codeRunsOf(rest.slice(0, SLACK_MAX_MESSAGE_CHARS * 2))
+            .find((candidate) => candidate.start < cut && cut < candidate.end);
+        if (run !== undefined && run.start > SLACK_MAX_MESSAGE_CHARS / 4) {
+            chunks.push(rest.slice(0, run.start).replace(/\n+$/, ''));
+            rest = rest.slice(run.start);
+            continue;
+        }
+        // The run is most of the message, so it is cut itself — at its last
+        // newline that leaves room for the closer, and past its opener so the
+        // continuation always makes progress. A continuation reopens with the
+        // info string only while it is short: a two-thousand-character info
+        // line repeated on every part would crowd out the code it labels.
+        const budget = SLACK_MAX_MESSAGE_CHARS - (run?.closer.length ?? 0);
+        const floor = run === undefined ? 0 : run.start + run.opener.length;
+        const reopen = run === undefined || run.opener.length <= SLACK_MAX_MESSAGE_CHARS / 8
+            ? run?.opener
+            : run.opener.endsWith('\n') ? `${run.closer.slice(1)}\n` : run.opener;
+        // A delimiter too long to close and reopen inside one message — a fence
+        // of a thousand backticks, an opening line that fills the window — is
+        // cut raw, as before this existed. Reopening it would send a message
+        // over the limit, and consume a character a message after that.
+        // Only a fence is reopened. Its closer and opener sit on lines of their
+        // own, so they can never run into a backtick of the code; an inline
+        // span's would, and `x` + `` would read as a different delimiter.
+        // `floor + 2`: the first cut past the opener has to fit a whole code
+        // 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+/, '');
+            continue;
+        }
+        const inner = rest.lastIndexOf('\n', budget - 1);
+        const within = inner > Math.max(floor, SLACK_MAX_MESSAGE_CHARS / 2) ? inner : Math.max(safeCutIndex(rest, budget), pastCodePoint(rest, floor + 1));
+        chunks.push(`${rest.slice(0, within)}${run.closer}`);
+        rest = `${reopen}${rest.slice(within).replace(/^\n/, '')}`;
     }
     if (rest.length > 0) {
         chunks.push(rest);
@@ -932,9 +1113,6 @@ const messageText = (text) => truncateForSlack(toSlackMrkdwn(text));
  * no rewrite is ever asked to span a boundary.
  */
 const messageChunks = (text) => splitForSlack(toSlackMrkdwn(text));
-// One rule with the gateway's `sessionRouting`, which posts the same
-// message for a turn this adapter did not start.
-const lastAssistantReply = (session) => latestTurnReply(session) ?? NO_REPLY_TEXT;
 const APPROVAL_ACTIONS = {
     stratus_approve_once: 'once',
     stratus_approve_always: 'always',
@@ -1028,21 +1206,37 @@ const HUMAN_MESSAGE_SUBTYPES = new Set(['file_share', 'me_message', 'thread_broa
 const isPersonSpeaking = (event) => event.subtype === undefined || HUMAN_MESSAGE_SUBTYPES.has(event.subtype);
 /** At most this many attachment names are listed; the rest are counted. */
 const MAX_LISTED_ATTACHMENTS = 5;
+const UNREAD_REASON_TEXT = {
+    unsupported: 'not a kind of file that can be read here',
+    'too-large': 'too large to read here',
+    failed: 'could not be downloaded',
+    'timed-out': 'not downloaded in time',
+    unreadable: 'not readable as text or as an image',
+    'not-opened': 'not opened, since this message was not addressed to you',
+};
 /**
- * What a message's attachments are called, for a turn that cannot open
- * them. Without this the agent is handed "here's the log" and no log, and
- * answers as though it had read something — the note is what lets it say
- * the true thing instead. Images the model was actually shown are not
- * listed here: they travel on the dispatch, name included.
+ * What a message's attachments are called, and why each was not read, for
+ * a turn that cannot open them. Without this the agent is handed "here's
+ * the log" and no log, and answers as though it had read something; the
+ * note is what lets it say the true thing instead. Images the model was
+ * actually shown are not listed here: they travel on the dispatch, name
+ * included. A file with no recorded reason is one no reader was handed,
+ * which is `unsupported`.
  */
-const attachmentNote = (files) => {
+const attachmentNote = (files, reasons) => {
     if (files.length === 0) {
         return '';
     }
-    const names = files.slice(0, MAX_LISTED_ATTACHMENTS).map((file) => file.name ?? file.title ?? 'an unnamed file');
-    const rest = files.length - names.length;
-    const listed = rest > 0 ? `${names.join(', ')}, and ${rest} more` : names.join(', ');
-    return `\n[Attached: ${listed}. Attachment contents cannot be read here — say so rather than guessing at them.]`;
+    const listed = files.slice(0, MAX_LISTED_ATTACHMENTS);
+    const groups = new Map();
+    for (const file of listed) {
+        const reason = reasons.get(file) ?? 'unsupported';
+        groups.set(reason, [...(groups.get(reason) ?? []), file.name ?? file.title ?? 'an unnamed file']);
+    }
+    const parts = [...groups].map(([reason, names]) => `${names.join(', ')} (${UNREAD_REASON_TEXT[reason]})`);
+    const rest = files.length - listed.length;
+    const all = rest > 0 ? `${parts.join('; ')}; and ${rest} more` : parts.join('; ');
+    return `\n[Attached, name only: ${all}. You have only the names, so say so rather than guessing at what is in them.]`;
 };
 /** What Slack calls a file, in a warning about it. */
 const fileLabel = (file) => file.name ?? file.title ?? file.id ?? 'an unnamed file';
@@ -1057,15 +1251,19 @@ const fileLabel = (file) => file.name ?? file.title ?? file.id ?? 'an unnamed fi
  * fix — the warning here names the scope instead, and the file falls back
  * to the by-name note like any other attachment the turn cannot open.
  */
-const readImageAttachments = async (files, botToken, fetchFile, timeoutMs, warn) => {
+const readImageAttachments = async (files, botToken, fetchFile, timeoutMs, warn, reasons, deadline = AbortSignal.timeout(timeoutMs)) => {
     // Decided from the last file back, the way the replay window is spent:
     // when a message's images do not all fit, the ones kept are the ones it
     // listed last, so intake and replay agree about which survive. Delivered
     // in the message's own order, because that is how the person sees them.
     const kept = new Map();
     const dropped = new Set();
-    // The message's one deadline, shared by every download in it.
-    const deadline = AbortSignal.timeout(timeoutMs);
+    // Recorded beside the drop, so the note says why and never guesses. A
+    // non-image goes on to the text reader with no reason: it decides.
+    const drop = (position, reason) => {
+        dropped.add(position);
+        reasons.set(files[position], reason);
+    };
     // Decoded bytes accepted so far. Checked against Slack's reported size
     // before a download and the real length after it, because the message
     // as a whole has a budget the per-image cap alone cannot keep.
@@ -1090,19 +1288,23 @@ const readImageAttachments = async (files, botToken, fetchFile, timeoutMs, warn)
     for (let position = files.length - 1; position >= 0; position -= 1) {
         const file = files[position];
         const url = file.url_private_download ?? file.url_private;
-        if (!isImageAttachmentMediaType(file.mimetype) || url === undefined) {
+        if (!isImageAttachmentMediaType(file.mimetype)) {
             dropped.add(position);
             continue;
         }
+        if (url === undefined) {
+            drop(position, 'failed');
+            continue;
+        }
         if (windowClosed) {
             warn(`slack: ${fileLabel(file)} was not taken: an image listed after it already filled what this message's images can carry; the turn is told it cannot be read.`);
-            dropped.add(position);
+            drop(position, 'too-large');
             continue;
         }
         const tooBig = file.size === undefined ? undefined : overLimit(fileLabel(file), file.size);
         if (tooBig !== undefined) {
             warn(tooBig);
-            dropped.add(position);
+            drop(position, 'too-large');
             continue;
         }
         // What this image may weigh: the per-image cap, or what is left of the
@@ -1111,7 +1313,7 @@ const readImageAttachments = async (files, botToken, fetchFile, timeoutMs, warn)
         const maxBytes = Math.min(IMAGE_ATTACHMENT_MAX_BYTES, IMAGE_ATTACHMENTS_MAX_TOTAL_BYTES - total);
         if (deadline.aborted) {
             warn(`slack: ${fileLabel(file)} was not downloaded: this message's downloads had already taken longer than ${timeoutMs}ms. The turn is told it cannot be read.`);
-            dropped.add(position);
+            drop(position, 'timed-out');
             continue;
         }
         let download;
@@ -1123,7 +1325,7 @@ const readImageAttachments = async (files, botToken, fetchFile, timeoutMs, warn)
                 ? `this message's downloads took longer than ${timeoutMs}ms`
                 : (error instanceof Error ? error.message : String(error));
             warn(`slack: could not download ${fileLabel(file)}: ${reason}. The turn is told it cannot be read.`);
-            dropped.add(position);
+            drop(position, error instanceof Error && error.name === 'TimeoutError' ? 'timed-out' : 'failed');
             continue;
         }
         // Refused on what Slack sends when it will not serve the file — a
@@ -1133,7 +1335,7 @@ const readImageAttachments = async (files, botToken, fetchFile, timeoutMs, warn)
         const contentType = download.contentType?.split(';')[0]?.trim().toLowerCase() ?? '';
         if (download.status !== 200 || contentType.startsWith('text/')) {
             warn(`slack: ${fileLabel(file)} came back as ${contentType || 'no content type'} (HTTP ${download.status}) rather than an image. This is what a bot token without the files:read scope gets — add the scope under OAuth & Permissions and reinstall the app.`);
-            dropped.add(position);
+            drop(position, 'failed');
             continue;
         }
         if (download.truncated === true) {
@@ -1144,13 +1346,13 @@ const readImageAttachments = async (files, botToken, fetchFile, timeoutMs, warn)
                 windowClosed = true;
             }
             warn(`slack: ${fileLabel(file)} is larger than the ${maxBytes} bytes this message could still take for an image; the download was abandoned and the turn is told it cannot be read.`);
-            dropped.add(position);
+            drop(position, 'too-large');
             continue;
         }
         const stillTooBig = overLimit(fileLabel(file), download.body.length);
         if (stillTooBig !== undefined) {
             warn(stillTooBig);
-            dropped.add(position);
+            drop(position, 'too-large');
             continue;
         }
         // Read from the bytes, not from Slack's metadata: an image the model
@@ -1159,12 +1361,12 @@ const readImageAttachments = async (files, botToken, fetchFile, timeoutMs, warn)
         const dimensions = imageDimensions(download.body, file.mimetype);
         if (dimensions === undefined) {
             warn(`slack: ${fileLabel(file)} is not a complete ${file.mimetype} — its header or trailer is missing; the turn is told it cannot be read.`);
-            dropped.add(position);
+            drop(position, 'unreadable');
             continue;
         }
         if (dimensions.width > IMAGE_ATTACHMENT_MAX_DIMENSION || dimensions.height > IMAGE_ATTACHMENT_MAX_DIMENSION) {
             warn(`slack: ${fileLabel(file)} is ${dimensions.width}×${dimensions.height}, over the ${IMAGE_ATTACHMENT_MAX_DIMENSION}-pixel side the model can take; the turn is told it cannot be read.`);
-            dropped.add(position);
+            drop(position, 'too-large');
             continue;
         }
         total += download.body.length;
@@ -1188,6 +1390,126 @@ const readImageAttachments = async (files, botToken, fetchFile, timeoutMs, warn)
     });
     return { images, unread };
 };
+/** The most one text attachment may weigh to be read into the message. */
+const TEXT_ATTACHMENT_MAX_BYTES = 100 * 1024;
+/**
+ * The most one message's text attachments may weigh together. Read text
+ * joins the transcript and is sent again on every later turn, so the cap
+ * is a cost decision as much as a context one.
+ */
+const TEXT_ATTACHMENTS_MAX_TOTAL_BYTES = 200 * 1024;
+const TEXT_APPLICATION_TYPES = new Set([
+    'application/json',
+    'application/xml',
+    'application/yaml',
+    'application/x-yaml',
+    'application/toml',
+    'application/javascript',
+    'application/x-sh',
+    'application/sql',
+]);
+const TEXT_EXTENSIONS = /\.(md|markdown|txt|text|csv|tsv|json|ya?ml|toml|xml|log|ini|conf)$/i;
+/**
+ * Whether a file is text the model can be handed as it is. Slack's
+ * mimetype comes from the uploader's client and a Markdown file can arrive
+ * as `text/markdown`, `text/plain`, or an octet stream, so an unhelpful
+ * type falls back to the name. HTML is left out: a sign-in page is HTML
+ * too, and a file of it could not be told apart from Slack refusing one.
+ */
+const isTextAttachment = (file) => {
+    const mimetype = file.mimetype?.toLowerCase();
+    if (mimetype === 'text/html') {
+        return false;
+    }
+    if (mimetype !== undefined && (mimetype.startsWith('text/') || TEXT_APPLICATION_TYPES.has(mimetype))) {
+        return true;
+    }
+    const name = file.name ?? file.title;
+    return (mimetype === undefined || mimetype === 'application/octet-stream') && name !== undefined && TEXT_EXTENSIONS.test(name);
+};
+/**
+ * The text files among a message's attachments, read so the turn gets
+ * their contents rather than their names. A Markdown plan attached in a
+ * DM reached the agent as a filename, and it told the person it had no
+ * way to read Slack at all. Anything that is not UTF-8 text, is over the
+ * caps, or comes back as a page stays in `unread` and is named in the
+ * note, exactly as before; the warning says why.
+ */
+const readTextAttachments = async (files, botToken, fetchFile, timeoutMs, deadline, warn, reasons) => {
+    const texts = [];
+    const unread = [];
+    const skip = (file, reason) => {
+        unread.push(file);
+        reasons.set(file, reason);
+    };
+    let total = 0;
+    for (const file of files) {
+        const url = file.url_private_download ?? file.url_private;
+        if (!isTextAttachment(file)) {
+            // An image the image reader already refused keeps its own reason.
+            unread.push(file);
+            if (!reasons.has(file)) {
+                reasons.set(file, 'unsupported');
+            }
+            continue;
+        }
+        if (url === undefined) {
+            skip(file, 'failed');
+            continue;
+        }
+        const maxBytes = Math.min(TEXT_ATTACHMENT_MAX_BYTES, TEXT_ATTACHMENTS_MAX_TOTAL_BYTES - total);
+        if (file.size !== undefined && file.size > maxBytes) {
+            warn(`slack: ${fileLabel(file)} is ${file.size} bytes, over the ${maxBytes} bytes of text this message could still take; the turn is told it cannot be read. Paste the part that matters, or split the file.`);
+            skip(file, 'too-large');
+            continue;
+        }
+        if (deadline.aborted) {
+            warn(`slack: ${fileLabel(file)} was not downloaded: this message's downloads had already taken longer than ${timeoutMs}ms. The turn is told it cannot be read.`);
+            skip(file, 'timed-out');
+            continue;
+        }
+        let download;
+        try {
+            download = await fetchFile(url, botToken, deadline, maxBytes);
+        }
+        catch (error) {
+            const reason = error instanceof Error && error.name === 'TimeoutError'
+                ? `this message's downloads took longer than ${timeoutMs}ms`
+                : (error instanceof Error ? error.message : String(error));
+            warn(`slack: could not download ${fileLabel(file)}: ${reason}. The turn is told it cannot be read.`);
+            skip(file, error instanceof Error && error.name === 'TimeoutError' ? 'timed-out' : 'failed');
+            continue;
+        }
+        // HTML is never a file read here (see isTextAttachment), so an HTML
+        // body is Slack's sign-in page: what a token without files:read gets.
+        const contentType = download.contentType?.split(';')[0]?.trim().toLowerCase() ?? '';
+        const head = download.body.subarray(0, 64).toString('utf8').trimStart().toLowerCase();
+        if (download.status !== 200 || contentType === 'text/html' || head.startsWith('<!doctype html') || head.startsWith('<html')) {
+            warn(`slack: ${fileLabel(file)} came back as ${contentType || 'no content type'} (HTTP ${download.status}) rather than the file. This is what a bot token without the files:read scope gets — add the scope under OAuth & Permissions and reinstall the app.`);
+            skip(file, 'failed');
+            continue;
+        }
+        if (download.truncated === true || download.body.length > maxBytes) {
+            warn(`slack: ${fileLabel(file)} is larger than the ${maxBytes} bytes of text this message could still take; the download was abandoned and the turn is told it cannot be read.`);
+            skip(file, 'too-large');
+            continue;
+        }
+        let text;
+        try {
+            text = new TextDecoder('utf-8', { fatal: true }).decode(download.body);
+        }
+        catch {
+            warn(`slack: ${fileLabel(file)} is not UTF-8 text; the turn is told it cannot be read.`);
+            skip(file, 'unreadable');
+            continue;
+        }
+        total += download.body.length;
+        texts.push({ name: fileLabel(file), text });
+    }
+    return { texts, unread };
+};
+/** Read text attachments, set into the message after what was said. */
+const textAttachmentBlocks = (texts) => texts.map(({ name, text }) => `\n[Attached: ${name}. Its contents follow.]\n${text.replace(/\s+$/, '')}\n[End of ${name}]`).join('');
 /**
  * Whether `text` addresses a bot user by name. Slack writes a mention as
  * `<@U123>` markup whoever typed it, so this is the same question for an
@@ -1294,6 +1616,87 @@ const approvalBlocks = (agentName, toolName, risk, requestId, input, origin, one
         },
     ];
 };
+const CREDENTIAL_ADD_ACTION = 'stratus_credential_add';
+const CREDENTIAL_VIEW = 'stratus_credential';
+const CREDENTIAL_BLOCK = 'credential_value';
+const CREDENTIAL_INPUT = 'value';
+// Under Slack's three-second acknowledgement window, with room for the ack
+// itself to travel.
+const CREDENTIAL_ACK_MS = 2500;
+// A reason is the agent's own text, shown to a person deciding whether to
+// hand over a key; long enough to explain, short enough to read.
+const CREDENTIAL_REASON_LIMIT = 300;
+const credentialWhose = (agentName, scope) => scope === 'agent'
+    ? `for ${agentName} only`
+    : `stored for the whole fleet, granted to ${agentName} (other agents need it in their own soul)`;
+/**
+ * The request as it appears in the conversation. What it says about the
+ * value is the promise the form keeps: straight to the credential store,
+ * never into the thread, and never over a key already there.
+ */
+const credentialRequestBlocks = (agentName, name, scope, reason, requestId) => {
+    const shortReason = reason !== undefined && reason.length > CREDENTIAL_REASON_LIMIT
+        ? `${reason.slice(0, CREDENTIAL_REASON_LIMIT)}…`
+        : reason;
+    return [
+        {
+            type: 'section',
+            text: {
+                type: 'mrkdwn',
+                text: `*${escapeSlackText(agentName)}* is asking for a credential: \`${escapeSlackText(name)}\`, ${credentialWhose(escapeSlackText(agentName), scope)}.`,
+            },
+        },
+        ...(shortReason !== undefined
+            ? [{ type: 'section', text: { type: 'mrkdwn', text: `_${escapeSlackText(agentName)} says:_ ${escapeSlackText(shortReason)}` } }]
+            : []),
+        {
+            type: 'context',
+            elements: [{
+                    type: 'mrkdwn',
+                    text: 'Only an approver can add it. The value goes straight to the credential store, never into this conversation, and a key already stored is never replaced from here.',
+                }],
+        },
+        {
+            type: 'actions',
+            elements: [{
+                    type: 'button',
+                    action_id: CREDENTIAL_ADD_ACTION,
+                    style: 'primary',
+                    value: requestId,
+                    text: { type: 'plain_text', text: 'Add credential' },
+                }],
+        },
+    ];
+};
+/**
+ * The form. `private_metadata` carries only the request id: where the key
+ * goes, and for whom, is the gateway's record of the request, never
+ * something a submission can say about itself.
+ */
+const credentialModal = (post, requestId) => ({
+    type: 'modal',
+    callback_id: CREDENTIAL_VIEW,
+    private_metadata: requestId,
+    title: { type: 'plain_text', text: 'Add a credential' },
+    submit: { type: 'plain_text', text: 'Add' },
+    close: { type: 'plain_text', text: 'Cancel' },
+    blocks: [
+        {
+            type: 'section',
+            text: {
+                type: 'mrkdwn',
+                text: `\`${escapeSlackText(post.name)}\`, ${credentialWhose(escapeSlackText(post.agentName), post.scope)}. `
+                    + `It is stored add-only and granted to ${escapeSlackText(post.agentName)}; it never appears in the conversation.`,
+            },
+        },
+        {
+            type: 'input',
+            block_id: CREDENTIAL_BLOCK,
+            label: { type: 'plain_text', text: `Value for ${post.name}` },
+            element: { type: 'plain_text_input', action_id: CREDENTIAL_INPUT },
+        },
+    ],
+});
 /**
  * The Slack channel adapter. One Slack app per agent — Slack has no way to
  * give a single bot several identities with real avatars, presence, and
@@ -1428,6 +1831,12 @@ export const createSlackChannelAdapter = (options) => {
     // Rendered approval requests, keyed by the gateway's request id — the
     // same id the buttons carry back.
     const approvalPosts = new Map();
+    // Credential requests whose post is in flight: Slack can show the message,
+    // and take a click on it, before postMessage resolves here. The same
+    // window `rendering` covers for approvals, and bounded the same way.
+    const credentialsPosting = new Set();
+    // Credential requests with a live button, keyed by the gateway's request id.
+    const credentialPosts = new Map();
     // Requests whose message is mid-post. A request can settle — expire, or
     // its turn be cancelled — while the postMessage that announces it is
     // still in flight, and the retraction would then find nothing to retract
@@ -1522,6 +1931,58 @@ export const createSlackChannelAdapter = (options) => {
         }
         return boundedDisplayName(await displayNameFor(connection, userId));
     };
+    /**
+     * 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
+     * someone in a DM they were "talking on the terminal", and answers the same
+     * way whether one person or a thousand will read it. Never the channel's
+     * name, which whoever made the channel chose (`ConversationContext`).
+     *
+     * Looked up on every turn outside a DM, and never cached: who can read a
+     * channel is the point, and a cached answer described a channel made
+     * public, or shared with another workspace, as it was before. Lookups
+     * for one conversation that overlap share one call. A lookup that fails
+     * (an app missing the read scopes) leaves the kind the event gave, or
+     * nothing: the prompt then says only that the conversation is in Slack,
+     * as it always did.
+     */
+    const roomLookups = new Map();
+    const KIND_BY_CHANNEL_TYPE = { im: 'direct', mpim: 'group', group: 'private', channel: 'public' };
+    const roomFor = async (connection, channel, channelType) => {
+        const fromEvent = channelType !== undefined ? KIND_BY_CHANNEL_TYPE[channelType] : undefined;
+        // A DM is two people, the app and the sender: nothing to look up.
+        if (fromEvent === 'direct') {
+            return { kind: 'direct' };
+        }
+        const key = `${connection.config.agentId}:${channel}`;
+        let lookup = roomLookups.get(key);
+        if (!lookup) {
+            lookup = lookupRoom(connection, channel).finally(() => roomLookups.delete(key));
+            roomLookups.set(key, lookup);
+        }
+        return (await lookup) ?? (fromEvent !== undefined ? { kind: fromEvent } : undefined);
+    };
+    const lookupRoom = async (connection, channel) => {
+        try {
+            const info = (await connection.web.conversations.info({ channel, include_num_members: true })).channel;
+            if (info === undefined) {
+                return undefined;
+            }
+            const kind = info.is_im === true
+                ? 'direct'
+                : info.is_mpim === true
+                    ? 'group'
+                    : info.is_private === true ? 'private' : 'public';
+            return {
+                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 } : {}),
+            };
+        }
+        catch {
+            return undefined;
+        }
+    };
     // Mentions arrive as <@U123> markup; the model should read names.
     /**
      * `<@U…>` mentions become `@name` — for principals only. A display name
@@ -1548,17 +2009,6 @@ export const createSlackChannelAdapter = (options) => {
     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);
-    /**
-     * Whether an agent takes a message from this sender at all — judged on
-     * its configuration, not on a live connection: an agent whose socket
-     * failed to start is still recognizable in a mention, and its door is
-     * still its own. An agent this adapter was never configured for is
-     * nobody's to refuse here, so it admits — the answer from before the
-     * door existed.
-     */
-    const admitsSender = (config, userId) => config === undefined
-        || config.admit !== 'principals'
-        || (config.principals ?? []).includes(userId);
     /**
      * 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
@@ -1985,7 +2435,7 @@ export const createSlackChannelAdapter = (options) => {
             });
         }
         catch (error) {
-            warn(`slack: could not retire an orphaned approval request: ${error instanceof Error ? error.message : String(error)}`);
+            warn(`slack: could not retire an orphaned request: ${error instanceof Error ? error.message : String(error)}`);
         }
     };
     const retractApprovalRequest = async (event) => {
@@ -2100,6 +2550,11 @@ export const createSlackChannelAdapter = (options) => {
     };
     /** Post the files an unrendered turn produced into its thread, in order. */
     const uploadUnrenderedFiles = async (connection, channel, thread, paths) => {
+        // Which files landed: a redelivery waiting behind this report posts
+        // the rest (`outcomeReportedAhead`), since a file that did not land is
+        // one only it can still post — and only the rest, or it would post
+        // twice the ones that did.
+        const landed = [];
         for (const filePath of paths) {
             try {
                 const data = await readFile(filePath);
@@ -2109,16 +2564,18 @@ export const createSlackChannelAdapter = (options) => {
                     filename: path.basename(filePath),
                     ...(thread ? { thread_ts: thread } : {}),
                 });
+                landed.push(filePath);
             }
             catch (error) {
                 warn(`files.uploadV2 failed for ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
+        return landed;
     };
     const reportUnrenderedFailure = async (event, behind, files) => {
         const gateway = gatewayRef;
         if (!gateway?.sessionRouting) {
-            return;
+            return NOTHING_REPORTED;
         }
         let routing;
         try {
@@ -2129,17 +2586,17 @@ export const createSlackChannelAdapter = (options) => {
             // the turn is already failed — there is nothing here to salvage
             // beyond saying why the thread stayed quiet.
             warn(`slack: could not read the routing for a failed turn: ${error instanceof Error ? error.message : String(error)}`);
-            return;
+            return NOTHING_REPORTED;
         }
         const metadata = routing?.metadata;
         // Another surface's session, or one with no conversation to speak
         // into. Not this adapter's to answer either way.
         if (!routing || metadata?.channel !== 'slack' || typeof metadata.slackChannel !== 'string') {
-            return;
+            return NOTHING_REPORTED;
         }
         const connection = connectionFor(routing.agentId);
         if (!connection) {
-            return;
+            return NOTHING_REPORTED;
         }
         const channel = metadata.slackChannel;
         const thread = typeof metadata.slackThread === 'string' ? metadata.slackThread : undefined;
@@ -2160,10 +2617,13 @@ export const createSlackChannelAdapter = (options) => {
             // interruption it existed to avoid; a line left standing happens
             // only to a turn that had already chosen to speak.
             warn(`slack: a turn nobody asked for failed before saying anything: ${event.error}`);
-            await uploadUnrenderedFiles(connection, channel, thread, files);
-            return;
+            return { said: true, landed: await uploadUnrenderedFiles(connection, channel, thread, files) };
         }
-        await postAheadOf(behind, connection, channel, thread, messageChunks(`Something went wrong: ${event.error}`), () => uploadUnrenderedFiles(connection, channel, thread, files));
+        let landed = [];
+        const said = await postAheadOf(behind, connection, channel, thread, messageChunks(`Something went wrong: ${event.error}`), async () => {
+            landed = await uploadUnrenderedFiles(connection, channel, thread, files);
+        });
+        return { said, landed };
     };
     /**
      * The other half of `reportUnrenderedFailure`: a turn nobody here was
@@ -2177,7 +2637,7 @@ export const createSlackChannelAdapter = (options) => {
     const reportUnrenderedReply = async (event, behind, files) => {
         const gateway = gatewayRef;
         if (!gateway?.sessionRouting) {
-            return;
+            return NOTHING_REPORTED;
         }
         let routing;
         try {
@@ -2185,15 +2645,15 @@ export const createSlackChannelAdapter = (options) => {
         }
         catch (error) {
             warn(`slack: could not read the routing for a finished turn: ${error instanceof Error ? error.message : String(error)}`);
-            return;
+            return NOTHING_REPORTED;
         }
         const metadata = routing?.metadata;
         if (!routing || metadata?.channel !== 'slack' || typeof metadata.slackChannel !== 'string') {
-            return;
+            return NOTHING_REPORTED;
         }
         const connection = connectionFor(routing.agentId);
         if (!connection) {
-            return;
+            return NOTHING_REPORTED;
         }
         const channel = metadata.slackChannel;
         const thread = typeof metadata.slackThread === 'string' ? metadata.slackThread : undefined;
@@ -2206,10 +2666,16 @@ export const createSlackChannelAdapter = (options) => {
         // order to keep and nothing to say, so the files go on their own.
         const chunks = routing.reply ? messageChunks(routing.reply) : [];
         const posting = chunks.length > 0 ? chunks : (behind && files.length > 0 ? [NO_REPLY_TEXT] : []);
-        const uploads = () => uploadUnrenderedFiles(connection, channel, thread, files);
+        let landed = [];
+        const uploads = async () => {
+            landed = await uploadUnrenderedFiles(connection, channel, thread, files);
+        };
         if (posting.length === 0) {
             await uploads();
-            return;
+            // Nothing was said. A turn nobody asked for chose that; an addressed
+            // one is owed `(no reply)`, which a rendered turn would have posted,
+            // so a redelivery waiting behind this report is left to post it.
+            return { said: routing.unaddressed === true, landed };
         }
         // A reply the thread's other agents hear like any other, taking their
         // place for it before the post, as `handleInbound` does.
@@ -2217,11 +2683,288 @@ export const createSlackChannelAdapter = (options) => {
         const heard = routing.reply !== undefined && thread !== undefined
             ? overhearReply(connection, channel, thread, routing.reply, routing, published)
             : undefined;
-        await published;
+        const delivered = await published;
         await heard;
         log(`slack: posted the reply of a turn finished after a restart to ${channel}`);
+        return { said: delivered, landed };
+    };
+    /**
+     * Whether an approver can see a conversation: any public channel, or a
+     * private one with an approver among its members. Rejects, with the
+     * reason, when Slack will not say, so the caller refuses rather than
+     * guesses.
+     */
+    const approverCanSee = async (connection, channel, approvers) => {
+        try {
+            const info = (await connection.web.conversations.info({ channel })).channel;
+            if (info?.is_private !== true && info?.is_mpim !== true) {
+                return true;
+            }
+            let cursor;
+            do {
+                const page = await connection.web.conversations.members({ channel, limit: 200, ...(cursor ? { cursor } : {}) });
+                if ((page.members ?? []).some((member) => approvers.has(member))) {
+                    return true;
+                }
+                cursor = page.response_metadata?.next_cursor || undefined;
+            } while (cursor !== undefined);
+            return false;
+        }
+        catch (error) {
+            throw new Error(`Slack would not say who can see this conversation (${error instanceof Error ? error.message : String(error)}), so the form was not posted. `
+                + 'The app needs the conversations read scopes (channels:read, groups:read, mpim:read); see the app manifest.');
+        }
+    };
+    /**
+     * The channel contract's `requestCredential`: posts the form and resolves
+     * only once it is up with a button an approver can press. Every refusal
+     * rejects with a sentence for the agent, which the gateway hands it in
+     * place of "your operator was asked": a request nobody can answer would
+     * otherwise sit pending while the agent says it is waiting on someone.
+     */
+    const requestCredential = async (request) => {
+        const gateway = gatewayRef;
+        const connection = connectionFor(request.agentId);
+        if (!gateway || !connection) {
+            throw new Error(configuredAgents.has(request.agentId)
+                ? `${request.agentId}'s Slack app is not connected right now.`
+                : `${request.agentId} has no Slack app.`);
+        }
+        // Only in the conversation the agent asked in, and only for a turn this
+        // adapter dispatched from a Slack message: where to post comes from
+        // that turn's renderer, never from the session's metadata, which an
+        // HTTP caller can write (`channel: slack`, any `slackChannel`) to put a
+        // request nobody made in that conversation in front of its approvers.
+        // Unlike an approval there is no fallback channel: the person who can
+        // answer is the one the agent is talking to.
+        const active = gateway.activeTurnId?.(request.sessionId);
+        const turn = active === undefined
+            ? undefined
+            : (renderers.get(request.sessionId) ?? []).find((renderer) => renderer.turnId === active);
+        if (!turn) {
+            throw new Error('This turn did not come from a Slack message, so there is nobody in Slack to show the form to.');
+        }
+        const channel = turn.channel;
+        const thread = turn.threadTs;
+        const unseen = `Nobody who can add it can see this conversation`;
+        const approvers = new Set((connection.config.approvers ?? []).filter((id) => id.length > 0));
+        const agentName = gateway.agents().find((agent) => agent.id === request.agentId)?.name ?? request.agentId;
+        if (approvers.size === 0 || gateway.provideCredential === undefined) {
+            throw new Error(`Nobody can add it from Slack, because no approver is configured for ${agentName} (approvals.slackApprovers).`);
+        }
+        // A DM has one person in it besides the app. Posted there for someone
+        // who is not an approver, the form is a button only they can see and
+        // only approvers can press, which is a request nobody can answer.
+        const elsewhere = 'Ask in a channel an approver is in, or ask one of them directly.';
+        if (turn.dmWith !== undefined && !approvers.has(turn.dmWith)) {
+            throw new Error(`${unseen}: it is a direct message with someone who is not an approver for ${agentName}. ${elsewhere}`);
+        }
+        // A private channel or group DM shows the button only to its members,
+        // so one with no approver in it is the DM case again with more people.
+        // A public channel is open to anyone in the workspace, approvers
+        // included, and is not checked. Unknown is refused, not assumed fine:
+        // a form posted where nobody can answer it waits forever.
+        if (turn.dmWith === undefined && !(await approverCanSee(connection, channel, approvers))) {
+            throw new Error(`${unseen}: none of ${agentName}'s approvers is a member of this private conversation. ${elsewhere}`);
+        }
+        let posted;
+        credentialsPosting.add(request.requestId);
+        try {
+            posted = await connection.web.chat.postMessage({
+                channel,
+                text: escapeSlackText(`${agentName} is asking for a credential: ${request.name}, ${credentialWhose(agentName, request.scope)}.`),
+                ...(thread ? { thread_ts: thread } : {}),
+                blocks: credentialRequestBlocks(agentName, request.name, request.scope, request.reason, request.requestId),
+            });
+        }
+        catch (error) {
+            credentialsPosting.delete(request.requestId);
+            warn(`slack: could not post a credential request for ${request.agentId} to ${channel} (${error instanceof Error ? error.message : String(error)})`);
+            throw new Error(`Slack refused the post (${error instanceof Error ? error.message : String(error)}).`);
+        }
+        credentialsPosting.delete(request.requestId);
+        if (!posted.ts) {
+            throw new Error('Slack accepted the post but returned no message to attach the form to.');
+        }
+        credentialPosts.set(request.requestId, {
+            connection,
+            channel: posted.channel ?? channel,
+            ...(thread !== undefined ? { thread } : {}),
+            ts: posted.ts,
+            agentId: request.agentId,
+            agentName,
+            name: request.name,
+            scope: request.scope,
+            approvers,
+        });
+    };
+    const settleCredentialPost = async (event) => {
+        const post = credentialPosts.get(event.requestId);
+        if (!post) {
+            return;
+        }
+        credentialPosts.delete(event.requestId);
+        const whose = event.scope === 'agent'
+            ? `for ${escapeSlackText(post.agentName)} only`
+            : `as a shared credential, granted to ${escapeSlackText(post.agentName)}`;
+        const by = event.actor !== undefined && post.approvers.has(event.actor) ? `, by <@${event.actor}>` : '';
+        const text = event.grantError === undefined
+            ? `Added \`${escapeSlackText(post.name)}\` ${whose}${by}. ${escapeSlackText(post.agentName)} can use it from its next reply; the value is in the credential store, not here.`
+            : `Stored \`${escapeSlackText(post.name)}\` ${event.scope === 'agent' ? `for ${escapeSlackText(post.agentName)}` : 'as a shared credential'}${by}, `
+                + `but it could not be added to ${escapeSlackText(post.agentName)}'s soul (${escapeSlackText(event.grantError)}), so ${escapeSlackText(post.agentName)} cannot use it yet. `
+                + 'Add the name to the credentials list in its soul on the machine.';
+        try {
+            await post.connection.web.chat.update({ channel: post.channel, ts: post.ts, text, blocks: [{ type: 'section', text: { type: 'mrkdwn', text } }] });
+        }
+        catch (error) {
+            warn(`slack: could not update the credential request for ${post.agentId} (${error instanceof Error ? error.message : String(error)})`);
+        }
+    };
+    /**
+     * Takes down a request no answer can land on any more, so its button stops
+     * inviting submissions that can only be refused the same way. A request
+     * `credential.provided` already settled is left to what that wrote, which
+     * says more (a key stored but not granted).
+     */
+    const retireCredentialPost = async (requestId, post, reason) => {
+        if (credentialPosts.get(requestId) !== post) {
+            return;
+        }
+        credentialPosts.delete(requestId);
+        const text = `\`${escapeSlackText(post.name)}\` was not added: ${escapeSlackText(reason)}`;
+        try {
+            await post.connection.web.chat.update({ channel: post.channel, ts: post.ts, text, blocks: [{ type: 'section', text: { type: 'mrkdwn', text } }] });
+        }
+        catch (error) {
+            warn(`slack: could not retire the credential request for ${post.agentId} (${error instanceof Error ? error.message : String(error)})`);
+        }
+    };
+    const handleCredentialClick = async (connection, args, requestId) => {
+        await args.ack();
+        const post = credentialPosts.get(requestId);
+        if (!post && credentialsPosting.has(requestId)) {
+            // Live, with the index not caught up yet: retiring it here would
+            // strip the button from a request about to be registered as pending.
+            await tellClicker(connection, args, 'That credential request is still being posted. Try the button again in a moment.');
+            return;
+        }
+        if (!post || post.connection !== connection) {
+            await tellClicker(connection, args, 'That credential request is no longer pending. Ask the agent to request it again.');
+            // A daemon restart forgets every request, and the buttons it posted
+            // stay live for everyone else in the thread: take this one down the
+            // way an orphaned approval is, from the click's own copy.
+            if (!post) {
+                await retireOrphanedPrompt(connection, args);
+            }
+            return;
+        }
+        // By actor, as approvals are: the request sits in a thread anyone in
+        // it can read, and a key is a bigger thing to hand over than a click.
+        const clicker = args.body?.user?.id;
+        if (!clicker || !post.approvers.has(clicker)) {
+            await tellClicker(connection, args, `You are not an approver for ${post.agentName}, so you cannot add its credentials.`);
+            return;
+        }
+        const triggerId = args.body?.trigger_id;
+        if (!connection.web.views || !triggerId) {
+            await tellClicker(connection, args, 'Slack did not hand over a way to open the form. Try the button again.');
+            return;
+        }
+        try {
+            await connection.web.views.open({ trigger_id: triggerId, view: credentialModal(post, requestId) });
+        }
+        catch (error) {
+            warn(`slack: could not open the credential form for ${post.agentId} (${error instanceof Error ? error.message : String(error)})`);
+            await tellClicker(connection, args, 'The form could not be opened. Try the button again.');
+        }
+    };
+    /**
+     * The form's answer. Acked last rather than first, because the ack is how
+     * a refusal reaches the form: `errors` keeps it open with the reason
+     * beside the field, so a person told "already stored" or "no longer
+     * pending" learns it where they typed. The value is read here, handed to
+     * the gateway, and touched nowhere else: not logged, not posted.
+     */
+    const handleCredentialSubmission = async (connection, args) => {
+        const refuse = (message) => args.ack({ response_action: 'errors', errors: { [CREDENTIAL_BLOCK]: message } });
+        const view = args.body?.view;
+        const requestId = view?.private_metadata ?? '';
+        const post = credentialPosts.get(requestId);
+        const gateway = gatewayRef;
+        if (!post || post.connection !== connection || !gateway?.provideCredential) {
+            await refuse('That credential request is no longer pending. Ask the agent to request it again.');
+            return;
+        }
+        // Checked again on the answer, not only on the click: the form is a
+        // separate interaction, and the click is not what stores anything.
+        const submitter = args.body?.user?.id;
+        if (!submitter || !post.approvers.has(submitter)) {
+            await refuse(`You are not an approver for ${post.agentName}, so you cannot add its credentials.`);
+            return;
+        }
+        const value = view?.state?.values?.[CREDENTIAL_BLOCK]?.[CREDENTIAL_INPUT]?.value ?? '';
+        const answer = gateway.provideCredential({ requestId, value, actor: submitter }).catch((error) => ({
+            ok: false,
+            message: `It could not be stored: ${error instanceof Error ? error.message : String(error)}`,
+        }));
+        // Slack wants the submission acked within three seconds, and storing
+        // is two locked file writes and every bus subscriber: usually far
+        // inside that, not always. An answer in time keeps the form open with
+        // a refusal beside the field; a late one closes the form first and
+        // tells the submitter privately, rather than letting Slack time out
+        // and retry a submission the first attempt may already have stored.
+        let timer;
+        const deadline = new Promise((resolve) => {
+            timer = setTimeout(() => resolve('late'), CREDENTIAL_ACK_MS);
+        });
+        const first = await Promise.race([answer, deadline]);
+        clearTimeout(timer);
+        if (first !== 'late') {
+            // A plain ack closes the form. The message is rewritten from
+            // `credential.provided`, the one path every way of answering goes
+            // through.
+            await (first.ok ? args.ack() : refuse(first.message));
+            if (!first.ok && first.retired === true) {
+                track(retireCredentialPost(requestId, post, first.message));
+            }
+            return;
+        }
+        await args.ack();
+        track(answer.then(async (result) => {
+            if (result.ok) {
+                return;
+            }
+            if (result.retired === true) {
+                await retireCredentialPost(requestId, post, result.message);
+            }
+            try {
+                await connection.web.chat.postEphemeral({
+                    channel: post.channel,
+                    user: submitter,
+                    text: `${post.name} was not added: ${result.message}`,
+                    ...(post.thread !== undefined ? { thread_ts: post.thread } : {}),
+                });
+            }
+            catch (error) {
+                warn(`slack: could not tell ${submitter} a credential was not added (${error instanceof Error ? error.message : String(error)})`);
+            }
+        }));
     };
     const handleInteractive = async (connection, args) => {
+        if (args.body?.type === 'view_submission') {
+            if (args.body.view?.callback_id === CREDENTIAL_VIEW) {
+                await handleCredentialSubmission(connection, args);
+            }
+            else {
+                await args.ack();
+            }
+            return;
+        }
+        const first = args.body?.actions?.[0];
+        if (first?.action_id === CREDENTIAL_ADD_ACTION && first.value) {
+            await handleCredentialClick(connection, args, first.value);
+            return;
+        }
         // Ack first and unconditionally: Slack retries an unacked interaction,
         // and a redelivered click on a request that is no longer pending would
         // read as a second, rejected decision.
@@ -2442,11 +3185,40 @@ export const createSlackChannelAdapter = (options) => {
      * a reply nobody answers. The agent alone in its thread, which is nearly
      * every thread, is answered without the question arising.
      */
-    const resolveFollowUpWinner = async (parts) => {
+    const resolveFollowUpWinner = async (parts, ts) => {
         const gateway = gatewayRef;
         if (!gateway?.sessionRouting || !parts.thread) {
             return undefined;
         }
+        // A message an agent already accepted is that agent's, whoever has spoken
+        // since. Nothing in memory says so after a restart, and the order below
+        // would hand a redelivery to the newer speaker — whose session holds no
+        // key for it, so it would run the message as new. Asked of every
+        // configured agent, whatever it listens to now and whether or not it is
+        // connected, unlike the order below: what counts is that it took the
+        // message as addressed to it (a judging agent's turn nobody asked for
+        // does not), an operator may have changed how it listens since, and an
+        // owner whose app failed to come back after the restart still started
+        // that turn — the live agents stand down for it rather than run it again.
+        // Its workspace is the one it last authenticated in, when known.
+        if (gateway.holdsMessage) {
+            for (const agentId of configuredAgents) {
+                const teamId = botIdentities.get(agentId)?.teamId;
+                if (teamId !== undefined && teamId !== parts.team) {
+                    continue;
+                }
+                const sessionId = channelSessionKey({
+                    channel: 'slack',
+                    agentId,
+                    team: parts.team,
+                    conversation: parts.conversation,
+                    thread: parts.thread,
+                });
+                if (await gateway.holdsMessage(sessionId, dispatchKeyFor(`${agentId}:${parts.conversation}:${ts}`))) {
+                    return agentId;
+                }
+            }
+        }
         const engaged = [];
         // Live connections in this message's OWN workspace. Live, because an
         // agent whose app failed to connect cannot answer anything, and leaving
@@ -2525,7 +3297,7 @@ export const createSlackChannelAdapter = (options) => {
         if (existing) {
             return existing.verdict;
         }
-        const entry = { verdict: resolveFollowUpWinner(parts), settled: false };
+        const entry = { verdict: resolveFollowUpWinner(parts, ts), settled: false };
         coldVerdicts.set(key, entry);
         void entry.verdict.then(() => {
             entry.settled = true;
@@ -2614,6 +3386,10 @@ export const createSlackChannelAdapter = (options) => {
         // answer it and hold the thread. One naming only agents that refuse
         // the sender is still theirs and not this agent's to answer — so the
         // refusing agent stays `named`, and only the handover is withheld.
+        // Judged on configuration, not on a live connection: an agent whose
+        // socket failed to start is still recognizable in a mention, and its
+        // door is still its own. One this adapter was never configured for has
+        // 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);
         // The key one Slack MESSAGE is known by, whichever delivery carried
@@ -2704,6 +3480,7 @@ export const createSlackChannelAdapter = (options) => {
             event,
             isDm,
             team,
+            eventKey,
             userId: event.user,
             sessionId: channelSessionKey({
                 channel: 'slack',
@@ -2803,7 +3580,9 @@ export const createSlackChannelAdapter = (options) => {
         if (!gateway) {
             return;
         }
-        const { event, isDm, team, userId, thread, sessionId, threadKey } = admitted;
+        const { event, isDm, team, userId, thread, sessionId, threadKey, eventKey } = admitted;
+        // What the gateway knows this message by (see `dispatchKeyFor`).
+        const dispatchKey = dispatchKeyFor(eventKey);
         // Everything up to (and including) the dispatch call is serialized per
         // session in Slack receipt order: the user lookups and placeholder
         // post below await network I/O, and without this chain a later message
@@ -2868,27 +3647,54 @@ export const createSlackChannelAdapter = (options) => {
             // nobody asked for, since they reach the model ahead of the frame
             // that marks the message as somebody else's, and a judged message
             // names its attachments the way an overheard one does.
-            const { images, unread } = overhear || judged
+            // Images and text files share the message's one download deadline.
+            const deadline = AbortSignal.timeout(fileDownloadTimeoutMs);
+            const reasons = new Map();
+            if (overhear || judged) {
+                for (const file of event.files ?? []) {
+                    reasons.set(file, 'not-opened');
+                }
+            }
+            const { images, unread: notImages } = overhear || judged
                 ? { images: [], unread: event.files ?? [] }
-                : await readImageAttachments(event.files ?? [], connection.config.botToken, fetchFile, fileDownloadTimeoutMs, warn);
-            // An image with nothing said is still a question ("what's this?"); a
-            // file the turn could not open with nothing said is not one, and gets
-            // no reply.
-            if (cleaned.length === 0 && images.length === 0) {
+                : await readImageAttachments(event.files ?? [], connection.config.botToken, fetchFile, fileDownloadTimeoutMs, warn, reasons, deadline);
+            const { texts, unread } = overhear || judged
+                ? { texts: [], unread: notImages }
+                : await readTextAttachments(notImages, connection.config.botToken, fetchFile, fileDownloadTimeoutMs, deadline, warn, reasons);
+            // An image or a document with nothing said is still a question
+            // ("what's this?"); a file the turn could not open with nothing said
+            // is not one, and gets no reply.
+            if (cleaned.length === 0 && images.length === 0 && texts.length === 0) {
                 return undefined;
             }
             const author = await authorFor(connection, userId);
             // In shared channels the model should know who is speaking; a DM is
             // unambiguous. A bare image in a channel still says who sent it.
             const spoken = isDm ? cleaned : (cleaned.length > 0 ? `${author}: ${cleaned}` : `${author}:`);
-            const userMessage = `${spoken}${attachmentNote(unread)}`;
+            const userMessage = `${spoken}${textAttachmentBlocks(texts)}${attachmentNote(unread, reasons)}`;
             // Who sent this, judged against the operator's list — per message,
             // never remembered from the first one in the thread. A DM proves
             // nothing about who is typing, so a DM from an unlisted member is
             // `unknown` exactly as a channel mention would be. The same label
             // whether the agent answers or only hears: the text is in its
             // transcript either way.
-            const senderTrust = (connection.config.principals ?? []).includes(userId) ? 'user' : 'unknown';
+            const senderTrust = senderTrustFor(connection.config, userId);
+            // Who can read this, so the agent writes for them, and a thread says
+            // it is one. A DM names the other person only when they are one of
+            // the operator's principals: this lands in the system prompt, and
+            // anyone else's display name is text they chose, which a pattern
+            // cannot tell from an instruction phrased as a name.
+            const room = await roomFor(connection, event.channel, isDm ? 'im' : event.channel_type);
+            const conversation = room === undefined
+                ? undefined
+                : {
+                    ...room,
+                    ...(room.kind === 'direct' && senderTrust === 'user' ? { with: author } : {}),
+                    ...(thread !== undefined && room.kind !== 'direct' ? { thread: true } : {}),
+                    // People outside this workspace read a Slack Connect channel, and
+                    // the event says so itself, even when the lookup failed.
+                    ...(room.kind !== 'direct' && args.body?.is_ext_shared_channel === true ? { shared: true } : {}),
+                };
             const metadata = {
                 channel: 'slack',
                 team,
@@ -2897,6 +3703,7 @@ export const createSlackChannelAdapter = (options) => {
                 // Carried so a mid-turn approval question is asked in the thread
                 // the turn belongs to rather than at the top of a busy channel.
                 ...(thread ? { slackThread: thread } : {}),
+                ...(conversation !== undefined ? { [CONVERSATION_METADATA_KEY]: conversation } : {}),
                 [SENDER_TRUST_METADATA_KEY]: senderTrust,
             };
             if (overhear) {
@@ -2934,6 +3741,7 @@ export const createSlackChannelAdapter = (options) => {
                 statusThread: thread ?? event.ts,
                 statusWarned: connection.statusWarned,
                 ...(ahead ? { after: ahead } : {}),
+                ...(isDm ? { dmWith: userId } : {}),
             });
             if (!streaming) {
                 replyOrder.set(sessionId, renderer.posted);
@@ -2958,7 +3766,13 @@ export const createSlackChannelAdapter = (options) => {
             const queue = renderers.get(sessionId) ?? [];
             queue.push(renderer);
             renderers.set(sessionId, queue);
-            renderer.showLoading(queue.length === 1);
+            // In a DM each message is its own status key, and Slack stops showing
+            // the running turn's once a newer message sits below it — so a
+            // message queued there that stayed dark read as the agent having
+            // stopped until the reply ahead of it posted. In a channel thread the
+            // key is shared, and the running turn's status stays up instead.
+            renderer.showLoading(queue.length === 1 || queue[0]?.statusThread !== renderer.statusThread);
+            let repeat;
             const turn = gateway.dispatch({
                 sessionId,
                 agentId: connection.config.agentId,
@@ -2967,8 +3781,15 @@ export const createSlackChannelAdapter = (options) => {
                 ...(judged ? { addressed: false } : {}),
                 turnId: renderer.turnId,
                 metadata,
+                // A redelivery this process no longer remembers (it restarted, or
+                // the dedupe evicted it) is still the message it was: the gateway
+                // runs no second turn for it, and says so through `onRepeat`.
+                idempotencyKey: dispatchKey,
+                onRepeat: (kind) => {
+                    repeat = kind;
+                },
             });
-            return { renderer, turn };
+            return { renderer, turn, repeat: () => repeat };
         });
         const started = await intake;
         if (!started) {
@@ -2986,7 +3807,7 @@ export const createSlackChannelAdapter = (options) => {
             }
             return;
         }
-        const { renderer, turn } = started;
+        const { renderer, turn, repeat } = started;
         const removeFromQueue = () => {
             const current = renderers.get(sessionId);
             if (current) {
@@ -3011,15 +3832,73 @@ export const createSlackChannelAdapter = (options) => {
         // events must reach ITS renderer, so this one leaves the queue BEFORE
         // the potentially slow final edit, uploads, and overflow posts.
         removeFromQueue();
+        // The turn is a live earlier delivery's, and that delivery's renderer
+        // posts its answer, or its failure: this one takes down whatever it put
+        // up and says nothing.
+        if (repeat() === 'live') {
+            await renderer.withdraw();
+            renderers.get(sessionId)?.[0]?.refreshLoading();
+            return;
+        }
+        // A finished one's outcome is posted here, because nothing says the
+        // delivery that ran it lived to post it, and no event will carry its
+        // files: they are read from the session, like its reply below.
+        //
+        // Less what the start-up sweep already said, when it finished this
+        // message's turn while the redelivery waited behind it: that outcome
+        // was reported ahead of this renderer as a turn nobody was rendering,
+        // and posting it again would say it twice. It was this message's turn
+        // if it is the session's latest — anything finished after it would be
+        // the latest instead — and the report says, part by part, what reached
+        // the thread: the files it landed are not posted again, and the text
+        // only if it was not said in full.
+        const finished = repeat() === 'finished';
+        const reportedAhead = session && finished && renderer.outcomeReportedAhead !== undefined && isLatestTurn(session, dispatchKey)
+            ? await renderer.outcomeReportedAhead
+            : undefined;
+        if (session && finished) {
+            // Counted, not a set: a turn can produce one path twice, and each
+            // result is an upload of its own, so one landing does not cover both.
+            const landed = new Map();
+            for (const filePath of reportedAhead?.landed ?? []) {
+                landed.set(filePath, (landed.get(filePath) ?? 0) + 1);
+            }
+            renderer.queueFiles(turnFilesFor(session, dispatchKey).filter((file) => {
+                const left = landed.get(file.path) ?? 0;
+                if (left > 0) {
+                    landed.set(file.path, left - 1);
+                    return false;
+                }
+                return true;
+            }));
+        }
+        if (reportedAhead?.said === true) {
+            await renderer.withdraw();
+            renderers.get(sessionId)?.[0]?.refreshLoading();
+            return;
+        }
+        // A dispatch whose turn fails rejects, but one that repeats a turn that
+        // already failed — or continues a crashed one the gateway could only
+        // fail — resolves with the failed session. Its failure is posted as the
+        // original delivery's would have been, not as a reply that says nothing.
+        const failedWith = session ? turnFailureFor(session, dispatchKey) : undefined;
+        if (failedWith !== undefined) {
+            failure = new Error(failedWith);
+            session = undefined;
+        }
         if (session) {
             // The reply is final here, so this is when the thread's other agents
             // take their place for it — before the final edit and the overflow
             // posts, which are network I/O a later message must not overtake.
             // A DM has no thread, and nobody else in it.
-            const reply = latestTurnReply(session);
+            // A finished repeat's session may have moved on since; its own turn
+            // is found by the key.
+            const reply = finished ? turnReplyFor(session, dispatchKey) : latestTurnReply(session);
             // A turn nobody asked for that said nothing posts nothing; every
-            // other turn says `(no reply)` where its answer would have gone.
-            const finalized = renderer.finalize(renderer.lazy ? reply ?? '' : lastAssistantReply(session));
+            // other turn says `(no reply)` where its answer would have gone — one
+            // 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))
                 : undefined;
@@ -3056,6 +3935,7 @@ export const createSlackChannelAdapter = (options) => {
     return {
         name: 'slack',
         resolveOutbound,
+        requestCredential,
         async start(gateway) {
             gatewayRef = gateway;
             unsubscribe = gateway.bus.subscribe((event) => {
@@ -3066,6 +3946,10 @@ export const createSlackChannelAdapter = (options) => {
                     track(renderApprovalRequest(event));
                     return;
                 }
+                if (event.type === 'credential.provided') {
+                    track(settleCredentialPost(event));
+                    return;
+                }
                 if (event.type === 'tool.approval-resolved') {
                     // The question was posted into the turn's thread, which took the
                     // loading status down with it; the turn works on once answered.
@@ -3140,7 +4024,11 @@ export const createSlackChannelAdapter = (options) => {
                 // connection — never leaves the queued reply stalled behind it.
                 if (event.type === 'session.failed' && !rendered) {
                     const claim = head?.reserveHandover();
-                    track(reportUnrenderedFailure(event, claim, takeUnrenderedFiles(event.sessionId)).finally(() => {
+                    const report = reportUnrenderedFailure(event, claim, takeUnrenderedFiles(event.sessionId));
+                    if (head) {
+                        head.outcomeReportedAhead = report.catch(() => NOTHING_REPORTED);
+                    }
+                    track(report.then(() => { }).finally(() => {
                         claim?.release();
                         head?.refreshLoading();
                     }));
@@ -3148,7 +4036,11 @@ export const createSlackChannelAdapter = (options) => {
                 }
                 if (event.type === 'session.completed' && !rendered) {
                     const claim = head?.reserveHandover();
-                    track(reportUnrenderedReply(event, claim, takeUnrenderedFiles(event.sessionId)).finally(() => {
+                    const report = reportUnrenderedReply(event, claim, takeUnrenderedFiles(event.sessionId));
+                    if (head) {
+                        head.outcomeReportedAhead = report.catch(() => NOTHING_REPORTED);
+                    }
+                    track(report.then(() => { }).finally(() => {
                         claim?.release();
                         head?.refreshLoading();
                     }));
@@ -3197,19 +4089,24 @@ export const createSlackChannelAdapter = (options) => {
             for (const connection of authenticated) {
                 const { config, socket } = connection;
                 try {
+                    // Returns the work it started: the SDK ignores it, and a test's fake
+                    // socket waits on it rather than guessing how long it takes.
                     const onEvent = (args) => {
                         const handled = handleInbound(connection, args).catch((error) => {
                             warn(`slack event handling failed: ${error instanceof Error ? error.message : String(error)}`);
                         });
                         inflight.add(handled);
                         void handled.finally(() => inflight.delete(handled));
+                        return handled;
                     };
                     socket.on('app_mention', onEvent);
                     socket.on('message', onEvent);
                     socket.on('interactive', (args) => {
-                        track(handleInteractive(connection, args).catch((error) => {
+                        const handled = handleInteractive(connection, args).catch((error) => {
                             warn(`slack interaction handling failed: ${error instanceof Error ? error.message : String(error)}`);
-                        }));
+                        });
+                        track(handled);
+                        return handled;
                     });
                     await socket.start();
                     connections.push(connection);
@@ -3255,6 +4152,7 @@ export const createSlackChannelAdapter = (options) => {
             botIdentities.clear();
             rendering.clear();
             resolvedWhileRendering.clear();
+            credentialsPosting.clear();
         },
     };
 };