@stratusagent/channel-slack 0.13.6 → 0.14.0

package/dist/index.js

@@ -3,8 +3,7 @@ import { constants } from 'node:fs';
 import { lstat, mkdir, open, readdir, readFile, realpath, rename, rm, writeFile } 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, RunAbortedError, leastTrusted, sessionTrustOf, SESSION_TRUST_METADATA_KEY, } from '@stratusagent/core';
-import { admitsSender, channelSessionKey, senderTrustFor, } from '@stratusagent/channels';
+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, HostRefusalError, RunAbortedError, leastTrusted, sessionTrustOf, SESSION_TRUST_METADATA_KEY, admitsSender, channelSessionKey, senderTrustFor, } from '@stratusagent/core';
 import { codeRunsOf, toSlackMrkdwn } from "./mrkdwn.js";
 /**
  * The longest display name the model is shown. Slack caps profile names
@@ -85,6 +84,17 @@ const PLACEHOLDER_TEXT = '…';
 /** What the loading status says while a turn works, and while it runs a tool. */
 const THINKING_STATUS = 'is thinking…';
 const toolStatus = (toolName) => `is running ${toolName}…`;
+/**
+ * The same step as a line of its own, for Slack's `loading_messages`
+ * ("is running shell.run…" -> "Running shell.run…"). Slack's agent sessions
+ * show their own generic text ("Finding answers…") in place of `status`,
+ * and rotate these instead. None for the clear: Slack wants one to ten,
+ * and the empty status alone takes the indicator down.
+ */
+const loadingMessage = (status) => {
+    const step = status.replace(/^is /, '');
+    return step === '' ? undefined : step.charAt(0).toUpperCase() + step.slice(1);
+};
 /**
  * How often a loading status is set again while its turn runs. Slack drops
  * one after two minutes with no message, and a long turn — a tool, an
@@ -583,13 +593,19 @@ class ReplyRenderer {
         }
         this.statusText = text;
         const thread = this.statusThread;
+        const loading = loadingMessage(text);
         // Not awaited by the caller: the turn never waits on a status. Only
         // `finalize` does, for the ordering reason on `statusChain`. A refusal
         // — a workspace or plan without it, a token Slack will not honour for
         // it — is said once and then left alone; the reply still arrives,
         // just without the status ahead of it.
         this.statusChain = this.statusChain
-            .then(() => setStatus.call(this.web.assistant?.threads, { channel_id: this.channel, thread_ts: thread, status: text }))
+            .then(() => setStatus.call(this.web.assistant?.threads, {
+            channel_id: this.channel,
+            thread_ts: thread,
+            status: text,
+            ...(loading ? { loading_messages: [loading] } : {}),
+        }))
             .then(() => undefined, (error) => {
             if (!this.statusWarned.value) {
                 this.statusWarned.value = true;
@@ -1178,7 +1194,13 @@ class ReplyRenderer {
         }
         return this.finalize(`Stopped by <@${by}>.`);
     }
-    async fail(message) {
+    /**
+     * `refused` is a turn the host stopped on purpose (`HostRefusalError`), a
+     * spent budget, whose message is already a sentence for the person
+     * reading it. Framed as something having gone wrong, it would read as a
+     * fault to report when it is a limit working.
+     */
+    async fail(message, refused = false) {
         // 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
         // read as "before saying anything" would leave that placeholder saying
@@ -1195,7 +1217,7 @@ class ReplyRenderer {
             this.warn(`a turn nobody asked for failed before saying anything: ${message}`);
             return this.finalize('');
         }
-        return this.finalize(`Something went wrong: ${message}`);
+        return this.finalize(refused ? message : `Something went wrong: ${message}`);
     }
     /**
      * Claim the placeholder for a turn that finished ahead of this one — the
@@ -1570,12 +1592,53 @@ const attachmentNote = (files, reasons) => {
 };
 /** What Slack calls a file, in a warning about it. */
 const fileLabel = (file) => file.name ?? file.title ?? file.id ?? 'an unnamed file';
+/**
+ * Slack's scaled copies of an image, largest first. Slack makes these for
+ * every image it hosts — a 14 MB, 2600×1800 PNG came back with thumbnails
+ * from 64 to 1024 pixels a side, each a PNG under 3 MB — so an image too
+ * big for the model still has a copy it can take, with no image library
+ * here to make one. Smaller than 360 is too small to read anything in.
+ */
+const SLACK_PREVIEW_KEYS = ['thumb_1024', 'thumb_960', 'thumb_800', 'thumb_720', 'thumb_480', 'thumb_360'];
+/** The largest preview Slack lists for a file, if it lists one. */
+const slackPreviewUrl = (file) => SLACK_PREVIEW_KEYS.map((key) => file[key]).find((url) => typeof url === 'string' && url.length > 0);
+/**
+ * What an image's own bytes say it is. A preview's type is not in Slack's
+ * metadata — only the original's is — so it is read from the file itself,
+ * and anything that is none of the four the API takes is not an image here.
+ */
+const imageMediaTypeOf = (bytes) => {
+    const ascii = (at, length) => bytes.subarray(at, at + length).toString('latin1');
+    if (bytes.length >= 8 && bytes[0] === 0x89 && ascii(1, 3) === 'PNG') {
+        return 'image/png';
+    }
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+        return 'image/jpeg';
+    }
+    if (ascii(0, 4) === 'GIF8') {
+        return 'image/gif';
+    }
+    if (ascii(0, 4) === 'RIFF' && ascii(8, 4) === 'WEBP') {
+        return 'image/webp';
+    }
+    return undefined;
+};
+const MIB = 1024 * 1024;
+/**
+ * Says which images the model sees scaled down. Without it the agent reads
+ * a 1024-pixel preview of a 14 MB screenshot as the screenshot, and states
+ * what the small text says when it could only guess at it.
+ */
+const previewNote = (previews) => previews.map(({ name, width, height, original }) => `\n[${name} is shown as Slack's ${width}×${height} preview, because the original ${original}. Small text in it may not be legible: ask for a crop rather than guessing at it.]`).join('');
 /**
  * A message's attachments, sorted into the images the model will be shown
  * and everything else. An image is fetched only when Slack's own metadata
  * says it is one the API accepts and small enough to send; that keeps a
  * 40 MB PNG from being downloaded just to be dropped, and a PDF from being
- * fetched at all. What comes back is checked as well: without `files:read`
+ * fetched at all. An image over the per-image limits — 5 MB, or 8000
+ * pixels a side — is sent as Slack's own largest preview of it instead,
+ * when Slack made one, and the turn is told it is a preview. What comes
+ * back is checked as well: without `files:read`
  * Slack serves a sign-in page with a 200, and sending that to the model as
  * an image would fail the turn with an error naming nothing the person can
  * fix — the warning here names the scope instead, and the file falls back
@@ -1587,6 +1650,7 @@ const readImageAttachments = async (files, botToken, fetchFile, timeoutMs, warn,
     // 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 previewed = new Map();
     const dropped = new Set();
     // 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.
@@ -1604,121 +1668,157 @@ const readImageAttachments = async (files, botToken, fetchFile, timeoutMs, warn,
     // not slip in past a larger newer one that was left out.
     let windowClosed = false;
     // Why an image is being left out, or nothing when it fits. One place for
-    // both limits so the warning and the fallback cannot disagree.
+    // both limits so the warning and the fallback cannot disagree. Over the
+    // per-image cap, the image can still be sent as Slack's preview; over
+    // what is left of the message's budget, it is not sent at all.
     const overLimit = (label, bytes) => {
         if (bytes > IMAGE_ATTACHMENT_MAX_BYTES) {
-            return `slack: ${label} is ${bytes} bytes, over the ${IMAGE_ATTACHMENT_MAX_BYTES}-byte limit an image can be sent to the model at; the turn is told it cannot be read.`;
+            const why = `${label} is ${bytes} bytes, over the ${IMAGE_ATTACHMENT_MAX_BYTES}-byte limit an image can be sent to the model at`;
+            return {
+                reason: 'too-large',
+                warning: `slack: ${why}; the turn is told it cannot be read.`,
+                oversized: { why, original: `is ${(bytes / MIB).toFixed(1)} MB, over the ${IMAGE_ATTACHMENT_MAX_BYTES / MIB} MB a model can be sent` },
+            };
         }
         if (total + bytes > IMAGE_ATTACHMENTS_MAX_TOTAL_BYTES) {
             windowClosed = true;
-            return `slack: ${label} would take this message's images past the ${IMAGE_ATTACHMENTS_MAX_TOTAL_BYTES} bytes one request can carry; the turn is told it cannot be read. Send it in a message of its own.`;
+            return { reason: 'too-large', warning: `slack: ${label} would take this message's images past the ${IMAGE_ATTACHMENTS_MAX_TOTAL_BYTES} bytes one request can carry; the turn is told it cannot be read. Send it in a message of its own.` };
         }
         return undefined;
     };
-    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)) {
-            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.`);
-            drop(position, 'too-large');
-            continue;
-        }
-        const tooBig = file.size === undefined ? undefined : overLimit(fileLabel(file), file.size);
-        if (tooBig !== undefined) {
-            warn(tooBig);
-            drop(position, 'too-large');
-            continue;
-        }
+    // One download, checked the same way for an original and for a preview:
+    // the image and its size, or why not. `oversized` marks a refusal for the
+    // per-image limits alone — the only kind a smaller copy can get past.
+    // `mediaType` is Slack's word for an original; a preview's is read from
+    // its own bytes, since Slack's metadata describes only the original.
+    const download = async (url, label, mediaType) => {
         // What this image may weigh: the per-image cap, or what is left of the
         // message's budget if that is less. Handed to the fetcher so an
         // oversized response is abandoned mid-body rather than buffered whole.
         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.`);
-            drop(position, 'timed-out');
-            continue;
+            return { reason: 'timed-out', warning: `slack: ${label} was not downloaded: this message's downloads had already taken longer than ${timeoutMs}ms. The turn is told it cannot be read.` };
         }
-        let download;
+        let fetched;
         try {
-            download = await fetchFile(url, botToken, deadline, maxBytes);
+            fetched = await fetchFile(url, botToken, deadline, maxBytes);
         }
         catch (error) {
-            const reason = error instanceof Error && error.name === 'TimeoutError'
+            const timedOut = error instanceof Error && error.name === 'TimeoutError';
+            const cause = timedOut
                 ? `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.`);
-            drop(position, error instanceof Error && error.name === 'TimeoutError' ? 'timed-out' : 'failed');
-            continue;
+            return { reason: timedOut ? 'timed-out' : 'failed', warning: `slack: could not download ${label}: ${cause}. The turn is told it cannot be read.` };
         }
         // Refused on what Slack sends when it will not serve the file — a
         // non-200, or a 200 whose body is a page — rather than on the label of
         // what it does serve: a download URL may be typed as the image or as
         // a plain octet stream, and either is the bytes Slack said it was.
-        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.`);
-            drop(position, 'failed');
-            continue;
+        const contentType = fetched.contentType?.split(';')[0]?.trim().toLowerCase() ?? '';
+        if (fetched.status !== 200 || contentType.startsWith('text/')) {
+            return { reason: 'failed', warning: `slack: ${label} came back as ${contentType || 'no content type'} (HTTP ${fetched.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.` };
         }
-        if (download.truncated === true) {
+        if (fetched.truncated === true) {
+            const why = `${label} is larger than the ${maxBytes} bytes this message could still take for an image; the download was abandoned`;
             // Cut off at what was left of the message's budget, rather than at
             // the per-image cap: the same overflow the size check closes the
             // window on, learned from the bytes instead of the metadata.
             if (maxBytes < IMAGE_ATTACHMENT_MAX_BYTES) {
                 windowClosed = true;
+                return { reason: 'too-large', warning: `slack: ${why} and the turn is told it cannot be read.` };
             }
-            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.`);
-            drop(position, 'too-large');
-            continue;
+            return {
+                reason: 'too-large',
+                warning: `slack: ${why} and the turn is told it cannot be read.`,
+                oversized: { why, original: `is over the ${IMAGE_ATTACHMENT_MAX_BYTES / MIB} MB a model can be sent` },
+            };
         }
-        const stillTooBig = overLimit(fileLabel(file), download.body.length);
-        if (stillTooBig !== undefined) {
-            warn(stillTooBig);
-            drop(position, 'too-large');
-            continue;
+        const tooBig = overLimit(label, fetched.body.length);
+        if (tooBig !== undefined) {
+            return tooBig;
         }
         // Read from the bytes, not from Slack's metadata: an image the model
         // API refuses fails the turn it arrives on and, once stored, every turn
         // after — so what is stored has to be what the API takes.
-        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.`);
-            drop(position, 'unreadable');
-            continue;
+        const type = mediaType ?? imageMediaTypeOf(fetched.body);
+        const dimensions = type === undefined ? undefined : imageDimensions(fetched.body, type);
+        if (type === undefined || dimensions === undefined) {
+            return { reason: 'unreadable', warning: `slack: ${label} is not a complete ${type ?? 'image'} — its header or trailer is missing; the turn is told it cannot be read.` };
         }
         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.`);
+            const why = `${label} is ${dimensions.width}×${dimensions.height}, over the ${IMAGE_ATTACHMENT_MAX_DIMENSION}-pixel side the model can take`;
+            return {
+                reason: 'too-large',
+                warning: `slack: ${why}; the turn is told it cannot be read.`,
+                oversized: { why, original: `is ${dimensions.width}×${dimensions.height}, over the ${IMAGE_ATTACHMENT_MAX_DIMENSION} pixels a side a model can be sent` },
+            };
+        }
+        return { body: fetched.body, mediaType: type, ...dimensions };
+    };
+    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)) {
+            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.`);
             drop(position, 'too-large');
             continue;
         }
-        total += download.body.length;
+        // Slack's own size is trusted before any bytes move: an original it
+        // says is too big is never fetched — only, when that is the per-image
+        // cap, its preview.
+        let result = (file.size === undefined ? undefined : overLimit(fileLabel(file), file.size))
+            ?? await download(url, fileLabel(file), file.mimetype);
+        const previewUrl = 'reason' in result && result.oversized !== undefined ? slackPreviewUrl(file) : undefined;
+        if ('reason' in result && result.oversized !== undefined && previewUrl !== undefined) {
+            const { why, original } = result.oversized;
+            const preview = await download(previewUrl, `Slack's preview of ${fileLabel(file)}`, undefined);
+            if ('reason' in preview) {
+                warn(`slack: ${why}. Slack's smaller preview of it could not be used either: ${preview.warning.replace(/^slack: /, '')}`);
+                drop(position, result.reason);
+                continue;
+            }
+            warn(`slack: ${why}; sent Slack's ${preview.width}×${preview.height} preview of it instead, and the turn is told it is a preview.`);
+            previewed.set(position, { name: fileLabel(file), width: preview.width, height: preview.height, original });
+            result = preview;
+        }
+        if ('reason' in result) {
+            warn(result.warning);
+            drop(position, result.reason);
+            continue;
+        }
+        total += result.body.length;
         const name = file.name ?? file.title;
         kept.set(position, {
-            mediaType: file.mimetype,
-            data: download.body.toString('base64'),
+            mediaType: result.mediaType,
+            data: result.body.toString('base64'),
             ...(name !== undefined ? { name } : {}),
         });
     }
     const images = [];
     const unread = [];
+    const previews = [];
     files.forEach((file, position) => {
         const image = kept.get(position);
         if (image !== undefined) {
             images.push(image);
+            const preview = previewed.get(position);
+            if (preview !== undefined) {
+                previews.push(preview);
+            }
         }
         else if (dropped.has(position)) {
             unread.push(file);
         }
     });
-    return { images, unread };
+    return { images, unread, previews };
 };
 /** The most one text attachment may weigh to be read into the message. */
 const TEXT_ATTACHMENT_MAX_BYTES = 100 * 1024;
@@ -2122,12 +2222,19 @@ 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)`;
+/**
+ * What answering means when the agent asked for the key in a variable,
+ * said before anything is typed: the approval covers the binding too.
+ * `agentName` arrives escaped; the variable passed the gateway's rule, so
+ * it is letters, digits and underscores.
+ */
+const credentialShellLine = (agentName, env) => `${agentName}'s shell commands will be able to read this as \`${env}\`, so ${agentName} can see the value.`;
 /**
  * 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, replace = false) => {
+const credentialRequestBlocks = (agentName, name, scope, reason, requestId, replace = false, env) => {
     const shortReason = reason !== undefined && reason.length > CREDENTIAL_REASON_LIMIT
         ? `${reason.slice(0, CREDENTIAL_REASON_LIMIT)}…`
         : reason;
@@ -2144,6 +2251,9 @@ const credentialRequestBlocks = (agentName, name, scope, reason, requestId, repl
         ...(shortReason !== undefined
             ? [{ type: 'section', text: { type: 'mrkdwn', text: `_${escapeSlackText(agentName)} says:_ ${escapeSlackText(shortReason)}` } }]
             : []),
+        ...(env !== undefined
+            ? [{ type: 'section', text: { type: 'mrkdwn', text: `*${credentialShellLine(escapeSlackText(agentName), escapeSlackText(env))}*` } }]
+            : []),
         {
             type: 'context',
             elements: [{
@@ -2182,11 +2292,12 @@ const credentialModal = (post, requestId) => ({
             type: 'section',
             text: {
                 type: 'mrkdwn',
-                text: post.replace === true
+                text: (post.replace === true
                     ? `\`${escapeSlackText(post.name)}\`, ${credentialWhose(escapeSlackText(post.agentName), post.scope)}. `
                         + 'The new value replaces the stored one once it saves; it never appears in the conversation.'
                     : `\`${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.`,
+                        + `It is stored add-only and granted to ${escapeSlackText(post.agentName)}; it never appears in the conversation.`)
+                    + (post.env !== undefined ? ` ${credentialShellLine(escapeSlackText(post.agentName), escapeSlackText(post.env))}` : ''),
             },
         },
         {
@@ -2220,6 +2331,26 @@ const credentialModal = (post, requestId) => ({
  */
 /** Uncached author names one `message.read` looks up; the rest keep their id. */
 const READ_NAME_LOOKUPS = 10;
+/** Slack's longest channel name. */
+const CHANNEL_NAME_LIMIT = 80;
+/** Slack's longest channel topic, and its longest purpose. */
+const CHANNEL_TEXT_LIMIT = 250;
+/** The most users one `conversations.invite` call takes. */
+const CHANNEL_INVITE_LIMIT = 1000;
+/** A bookmark title longer than this is cut, with an ellipsis. */
+const BOOKMARK_TITLE_LIMIT = 200;
+/** A bookmark link longer than this is replaced by `BOOKMARK_LINK_TOO_LONG`. */
+const BOOKMARK_LINK_LIMIT = 2000;
+const BOOKMARK_LINK_TOO_LONG = '(this link is longer than 2,000 characters, so it is not shown)';
+/**
+ * The error code of a failed Web API call (`missing_scope`, `ratelimited`),
+ * which `@slack/web-api` puts on the error's `data.error`. Undefined for a
+ * failure that never reached Slack.
+ */
+const slackErrorCode = (error) => {
+    const code = error?.data?.error;
+    return typeof code === 'string' && code.length > 0 ? code : undefined;
+};
 /**
  * Orders two Slack message timestamps ("seconds.micros"). Compared as
  * integers, not floats: a current ts has more digits than a double holds.
@@ -3606,14 +3737,76 @@ export const createSlackChannelAdapter = (options) => {
         }
         return kind;
     };
+    /**
+     * The bookmarks a first-page read returns beside the messages. Never
+     * throws: a failure is a sentence for the agent, and the messages come
+     * back either way.
+     */
+    const listBookmarks = async (web, channel) => {
+        if (!web.bookmarks) {
+            return {};
+        }
+        let listed;
+        try {
+            listed = await web.bookmarks.list({ channel_id: channel });
+        }
+        catch (error) {
+            const code = slackErrorCode(error);
+            return {
+                bookmarksUnavailable: code === 'missing_scope'
+                    ? 'This Slack app can\'t read bookmarks because it lacks the bookmarks:read scope. Add it to the app\'s manifest and reinstall the app.'
+                    : `The channel's bookmarks could not be listed (${code ?? (error instanceof Error ? error.message : String(error))}).`,
+            };
+        }
+        const bookmarks = [];
+        for (const entry of Array.isArray(listed?.bookmarks) ? listed.bookmarks : []) {
+            const link = typeof entry?.link === 'string' ? entry.link.trim() : '';
+            if (!link) {
+                continue;
+            }
+            const title = (typeof entry.title === 'string' && entry.title.trim()) || link;
+            bookmarks.push({
+                title: title.length > BOOKMARK_TITLE_LIMIT ? `${title.slice(0, BOOKMARK_TITLE_LIMIT - 1)}…` : title,
+                // A cut link is a broken one, so an over-long link is not shown.
+                link: link.length > BOOKMARK_LINK_LIMIT ? BOOKMARK_LINK_TOO_LONG : link,
+            });
+        }
+        return bookmarks.length > 0 ? { bookmarks } : {};
+    };
+    /**
+     * The conversation a session lives in, read off its id, for this
+     * agent's connected app only: exactly `slack:<agent>:<this app's
+     * team>:<conversation>`, or that plus one thread `ts`, the keys this
+     * adapter opens sessions under. Anything longer (a delegation's
+     * `:delegate:…`, an archive's `:rolledover:…`) or of another shape (a
+     * schedule's) is no session of a conversation here. No lookup: the id
+     * is the identity check, and only the gateway names it.
+     */
+    const SLACK_TS = /^\d+\.\d+$/;
+    const sessionConversation = (agentId, sessionId) => {
+        const connection = connectionFor(agentId);
+        if (!connection?.teamId) {
+            return undefined;
+        }
+        const prefix = channelSessionKey({ channel: 'slack', agentId, team: connection.teamId, conversation: '' });
+        if (!sessionId.startsWith(prefix)) {
+            return undefined;
+        }
+        const [conversation, thread, ...rest] = sessionId.slice(prefix.length).split(':');
+        if (!conversation || rest.length > 0 || (thread !== undefined && !SLACK_TS.test(thread))) {
+            return undefined;
+        }
+        return conversation;
+    };
     /**
      * 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.
+     * DMs are refused, member or not, except the one the reading session
+     * lives in (`sessionConversation`). 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; from inside, it is what they already said to this agent. A
+     * thread in a channel is fine for the same reason the channel is.
      */
     const readConversation = async (request) => {
         const channel = request.conversation.trim();
@@ -3637,10 +3830,14 @@ export const createSlackChannelAdapter = (options) => {
         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. Approval cannot unlock this; read a channel instead.`);
+        const direct = info.is_im === true || info.is_mpim === true;
+        if (direct && (request.sessionId === undefined || sessionConversation(request.agentId, request.sessionId) !== info.id)) {
+            throw new Error(`slack: ${channel} is a direct message this conversation is not in, and a direct message is read only from inside it. Approval cannot unlock this; read a channel instead.`);
         }
-        if (info.is_member !== true) {
+        // A one-to-one IM states no membership; the session living in it is
+        // the proof. A group DM does say, and an app that left one cannot read
+        // it however its stale session is named.
+        if (info.is_im !== true && 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;
@@ -3650,6 +3847,12 @@ export const createSlackChannelAdapter = (options) => {
         if (!fetchPage) {
             throw new Error(`slack: this Slack client cannot read ${request.thread !== undefined ? 'threads' : 'channel history'}.`);
         }
+        // On the first page of the top level only, so paging costs no extra
+        // calls, and only once the checks above have said the read may happen.
+        // Asked beside the history, and settled without throwing.
+        const listing = request.thread === undefined && request.after === undefined && request.before === undefined
+            ? listBookmarks(connection.web, info.id)
+            : undefined;
         const base = {
             channel: info.id,
             inclusive: false,
@@ -3728,7 +3931,159 @@ export const createSlackChannelAdapter = (options) => {
                 ...(files.length > 0 ? { files } : {}),
             });
         }
-        return { messages, more };
+        return { messages, more, ...(listing ? await listing : {}) };
+    };
+    /**
+     * Creates a channel with the asking agent's own app — `channel.create`.
+     * Everything Slack would refuse once the channel exists is refused here
+     * first, so a bad request leaves no channel behind. After the create
+     * nothing throws: a topic, purpose or invitation that fails is reported,
+     * and the channel stays. Slack names are unique, so an agent that
+     * retries a create gets `name_taken`, never a second channel.
+     */
+    const createConversation = async (request) => {
+        const name = request.name.trim().replace(/^#/, '');
+        if (!name) {
+            throw new Error('slack: a channel needs a name.');
+        }
+        if (!/^[a-z0-9_-]+$/.test(name)) {
+            throw new Error(`slack: "${name}" can't be a channel name: Slack names use only lowercase letters, numbers, hyphens and underscores. Nothing was created.`);
+        }
+        if (name.length > CHANNEL_NAME_LIMIT) {
+            throw new Error(`slack: a channel name is at most ${CHANNEL_NAME_LIMIT} characters; this one is ${name.length}. Nothing was created.`);
+        }
+        for (const field of ['topic', 'purpose']) {
+            const length = [...(request[field] ?? '')].length;
+            if (length > CHANNEL_TEXT_LIMIT) {
+                throw new Error(`slack: the ${field} is ${length} characters; Slack allows ${CHANNEL_TEXT_LIMIT}. Nothing was created.`);
+            }
+        }
+        const invite = request.invite ?? [];
+        if (invite.length > CHANNEL_INVITE_LIMIT) {
+            throw new Error(`slack: that invites ${invite.length.toLocaleString('en-US')} people; Slack invites at most ${CHANNEL_INVITE_LIMIT.toLocaleString('en-US')} at once. Nothing was created.`);
+        }
+        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 it cannot create a channel.`
+                : `slack: agent ${request.agentId} has no Slack app, so it cannot create a Slack channel.`);
+        }
+        const { create, setTopic, setPurpose, invite: inviteUsers } = connection.web.conversations;
+        if (!create || !setTopic || !setPurpose || !inviteUsers) {
+            throw new Error('slack: this Slack client cannot create channels.');
+        }
+        // Who each entry is, before anything exists: agents on this host become
+        // the user their app posts as, in the same workspace only.
+        const invited = [];
+        const notInvited = [];
+        const toInvite = new Map();
+        for (const who of invite) {
+            const identity = botIdentities.get(who);
+            if (who === request.agentId || identity?.botUserId === connection.botUserId) {
+                invited.push(who);
+            }
+            else if (configuredAgents.has(who) && !identity?.botUserId) {
+                notInvited.push({ who, reason: `Agent ${who}'s Slack app is not connected, so its Slack user is unknown.` });
+            }
+            else if (identity) {
+                if (identity.teamId !== connection.teamId) {
+                    notInvited.push({ who, reason: `Agent ${who}'s Slack app is in another Slack workspace.` });
+                }
+                else {
+                    toInvite.set(who, identity.botUserId);
+                }
+            }
+            else if (/^[UW][A-Z0-9]+$/.test(who)) {
+                toInvite.set(who, who);
+            }
+            else {
+                notInvited.push({ who, reason: 'Not a Slack user id (U… or W…) or an agent with a Slack app on this host.' });
+            }
+        }
+        const kind = request.private === true ? 'private' : 'public';
+        let created;
+        try {
+            created = await create({ name, is_private: request.private === true });
+        }
+        catch (error) {
+            const code = slackErrorCode(error);
+            if (code === 'missing_scope') {
+                throw new Error(`slack: ${request.agentId}'s Slack app can't create ${kind} channels because it lacks the ${request.private === true ? 'groups:write' : 'channels:manage'} scope. Add it to the app's manifest and reinstall the app.`);
+            }
+            if (code === 'name_taken') {
+                throw new Error(`slack: there is already a channel named #${name} in this workspace, perhaps archived. Pick another name, or use that channel.`);
+            }
+            throw new Error(`slack: Slack could not create #${name} (${code ?? (error instanceof Error ? error.message : String(error))}).`);
+        }
+        const conversation = created.channel?.id;
+        if (!conversation) {
+            throw new Error(`slack: Slack answered the create of #${name} without a channel id, so whether it exists is unknown. Read the channel list before trying again.`);
+        }
+        const notSet = [];
+        const describe = (error) => slackErrorCode(error) ?? (error instanceof Error ? error.message : String(error));
+        if (request.topic) {
+            await setTopic({ channel: conversation, topic: request.topic })
+                .catch((error) => notSet.push({ field: 'topic', reason: `Slack did not set the topic (${describe(error)}).` }));
+        }
+        if (request.purpose) {
+            await setPurpose({ channel: conversation, purpose: request.purpose })
+                .catch((error) => notSet.push({ field: 'purpose', reason: `Slack did not set the purpose (${describe(error)}).` }));
+        }
+        if (toInvite.size > 0) {
+            // Slack's per-id failures, by user id: on the answer, or on the error
+            // the SDK throws for an ok: false answer.
+            const refusedOf = (errors) => new Map((Array.isArray(errors) ? errors : []).flatMap((entry) => typeof entry?.user === 'string' && typeof entry.error === 'string' ? [[entry.user, entry.error]] : []));
+            let refused;
+            let failure;
+            try {
+                refused = refusedOf((await inviteUsers({ channel: conversation, users: [...new Set(toInvite.values())].join(','), force: true })).errors);
+            }
+            catch (error) {
+                refused = refusedOf(error?.data?.errors);
+                failure = describe(error);
+            }
+            // A failed call that does not name everyone leaves the rest unknown,
+            // so the channel's members decide; who cannot be checked is not claimed.
+            let members;
+            let membersFailure;
+            if (failure !== undefined && [...toInvite.values()].some((user) => !refused.has(user))) {
+                try {
+                    members = new Set();
+                    let cursor;
+                    do {
+                        const page = await connection.web.conversations.members({ channel: conversation, limit: 1000, ...(cursor ? { cursor } : {}) });
+                        for (const member of page.members ?? []) {
+                            members.add(member);
+                        }
+                        cursor = page.response_metadata?.next_cursor || undefined;
+                    } while (cursor);
+                }
+                catch (error) {
+                    members = undefined;
+                    membersFailure = describe(error);
+                }
+            }
+            for (const [who, user] of toInvite) {
+                const code = refused.get(user);
+                if (code === 'already_in_channel' || (code === undefined && (failure === undefined || members?.has(user)))) {
+                    invited.push(who);
+                }
+                else if (code !== undefined || members !== undefined) {
+                    notInvited.push({ who, reason: `Slack did not invite them (${code ?? failure}).` });
+                }
+                else {
+                    notInvited.push({
+                        who,
+                        reason: `The invitation failed (${failure}) and the channel's members could not be checked (${membersFailure}), so they may or may not have been added.`,
+                    });
+                }
+            }
+        }
+        const order = new Map(invite.map((who, index) => [who, index]));
+        const byRequest = (left, right) => (order.get(left) ?? 0) - (order.get(right) ?? 0);
+        invited.sort(byRequest);
+        notInvited.sort((left, right) => byRequest(left.who, right.who));
+        return { conversation, name: created.channel?.name ?? name, invited, notInvited, notSet };
     };
     /**
      * Renders one parked call as buttons and remembers where it went.
@@ -4129,7 +4484,9 @@ export const createSlackChannelAdapter = (options) => {
             return { said: true, landed: await uploadUnrenderedFiles(connection, channel, thread, files) };
         }
         let landed = [];
-        const said = await postAheadOf(behind, connection, channel, thread, messageChunks(stoppedBy === undefined ? `Something went wrong: ${event.error}` : `Stopped by <@${stoppedBy}>.`), async () => {
+        const said = await postAheadOf(behind, connection, channel, thread, messageChunks(stoppedBy !== undefined
+            ? `Stopped by <@${stoppedBy}>.`
+            : event.refused ? event.error : `Something went wrong: ${event.error}`), async () => {
             landed = await uploadUnrenderedFiles(connection, channel, thread, files);
         });
         return { said, landed };
@@ -4287,7 +4644,7 @@ export const createSlackChannelAdapter = (options) => {
                 channel,
                 text: escapeSlackText(`${agentName} is asking ${request.replace === true ? 'to replace' : 'for'} a credential: ${request.name}, ${credentialWhose(agentName, request.scope)}.`),
                 ...(thread ? { thread_ts: thread } : {}),
-                blocks: credentialRequestBlocks(agentName, request.name, request.scope, request.reason, request.requestId, request.replace === true),
+                blocks: credentialRequestBlocks(agentName, request.name, request.scope, request.reason, request.requestId, request.replace === true, request.env),
             });
         }
         catch (error) {
@@ -4309,6 +4666,7 @@ export const createSlackChannelAdapter = (options) => {
             name: request.name,
             scope: request.scope,
             ...(request.replace === true ? { replace: true } : {}),
+            ...(request.env !== undefined ? { env: request.env } : {}),
             approvers,
         });
     };
@@ -4322,14 +4680,17 @@ export const createSlackChannelAdapter = (options) => {
             ? `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.replace === true
+        const shell = post.env !== undefined && event.grantError === undefined
+            ? ` Its shell commands read it as \`${escapeSlackText(post.env)}\`.`
+            : '';
+        const text = (event.replace === true
             ? `Replaced \`${escapeSlackText(post.name)}\` ${event.scope === 'agent' ? `for ${escapeSlackText(post.agentName)}` : 'as a shared credential'}${by}. `
                 + `${escapeSlackText(post.agentName)} uses the new value from its next reply; it is in the credential store, not here.`
             : 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.';
+                    + 'Add the name to the credentials list in its soul on the machine.') + shell;
         try {
             await post.connection.web.chat.update({ channel: post.channel, ts: post.ts, text, blocks: [{ type: 'section', text: { type: 'mrkdwn', text } }] });
         }
@@ -6017,8 +6378,8 @@ export const createSlackChannelAdapter = (options) => {
                     reasons.set(file, 'not-opened');
                 }
             }
-            const { images, unread: notImages } = overhear
-                ? { images: [], unread: event.files ?? [] }
+            const { images, unread: notImages, previews } = overhear
+                ? { images: [], unread: event.files ?? [], previews: [] }
                 : await readImageAttachments(event.files ?? [], connection.config.botToken, fetchFile, fileDownloadTimeoutMs, warn, reasons, deadline);
             const { texts, saved, unread } = overhear
                 ? { texts: [], saved: [], unread: notImages }
@@ -6042,7 +6403,7 @@ export const createSlackChannelAdapter = (options) => {
             // 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}${textAttachmentBlocks(texts)}${savedAttachmentBlocks(saved)}${attachmentNote(unread, reasons)}`;
+            const userMessage = `${spoken}${textAttachmentBlocks(texts)}${savedAttachmentBlocks(saved)}${previewNote(previews)}${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
@@ -6442,7 +6803,7 @@ export const createSlackChannelAdapter = (options) => {
                 ? await renderer.stopped(renderer.stoppedBy)
                 : refused
                     ? await renderer.finalize(renderer.lazy ? '' : deferredText ?? failure.message)
-                    : await renderer.fail(failure instanceof Error ? failure.message : String(failure));
+                    : await renderer.fail(failure instanceof Error ? failure.message : String(failure), failure instanceof HostRefusalError);
             const { spoke, spokeAt } = refused && renderer.stoppedBy === undefined
                 ? outcome
                 : noteReplayOutcome(connection, event.channel, event.ts, outcome);
@@ -6459,12 +6820,15 @@ export const createSlackChannelAdapter = (options) => {
         name: 'slack',
         resolveOutbound,
         readConversation,
+        sessionConversation,
+        createConversation,
         // A channel id is unique only within its workspace, so a standing
         // grant on one is bound to the team the agent's app authenticated in.
         accountFor: (agentId) => botIdentities.get(agentId)?.teamId || undefined,
         conversationKindFor,
         requestCredential,
         credentialReplaceForms: true,
+        credentialEnvForms: true,
         async start(gateway) {
             gatewayRef = gateway;
             // Nothing counts as seen live until every socket is up (Codex