@geminixiang/mikan 1.0.0-beta.4 → 1.0.0-beta.41

package/dist/adapters/slack/bot.js

@@ -1,22 +1,49 @@
 import { SocketModeClient } from "@slack/socket-mode";
-import { WebClient } from "@slack/web-api";
-import { existsSync, readFileSync } from "fs";
-import { readFile } from "fs/promises";
-import { basename, join } from "path";
+import { WebAPIRateLimitedError, WebClient } from "@slack/web-api";
+import { readEnv } from "../../env-manifest.js";
+import { existsSync, readFileSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { createConversationEvent, createConversationMessage, } from "../../adapter.js";
+import { createOfficeAddress } from "../../office/index.js";
+import { COMMAND_MANIFEST } from "../../commands/manifest.js";
 import { resolveConversationSettings } from "../../config.js";
+import { parseExtActionId } from "../../harness/extensions/registry.js";
 import * as log from "../../log.js";
-import { PRODUCT_NAME, formatForceStopped, formatNothingRunning } from "../../platform-messages.js";
-import { appendBotResponseLog, appendChannelLog, MessagingEventQueue, resolveOnlyScopedStopTarget, resolveStopTarget, withRetry, } from "../shared.js";
+import { isRecord, readTextFileIfExists } from "../../utils/file-guards.js";
+import { PRODUCT_NAME, formatForceStopped } from "../../platform-messages.js";
+import { appendBotResponseLog, appendChannelLog, MessagingEventQueue, saveIncomingAttachments, withRetry, } from "../shared.js";
 import { processMessageIntake } from "../intake.js";
+import { AssistantThreadRegistry, handleAgentContextChanged, handleAgentDmOpened, handleAssistantThreadStarted, titleAssistantThread, } from "./assistant.js";
 import { createSlackAdapters } from "./context.js";
-import { hasMaterializedChatSession, registerThreadSession, } from "../../sessions/agent-memory-file-manager.js";
+import { hasMaterializedChatSession, registerThreadSession, } from "../../sessions/chat-history-sync.js";
+import { conversationIdOf } from "../../sessions/session-key.js";
 import { isSlackThreadSessionKey, planSlackAdapterSession, planSlackEventAnchorRun, resolveSlackSessionKey, } from "./session.js";
 import { reportUserFacingError } from "../../observability/sentry.js";
-import { renderSlackBlocks } from "./blocks.js";
+import { renderSlackBlocks, resolveSlackMentions } from "./blocks.js";
+import { StreamStartLimiter } from "./stream-limits.js";
 const SLACK_EVENT_ANCHOR_TEXT = "Working on it...";
-// Slack WebClient errors carry either `code: "rate_limited"` (retry-after) or
-// the legacy `data.error === "rate_limited"` / 429 status shape.
+/**
+ * Slack's per-call limit on `markdown_text`: "Limit this field to 12,000
+ * characters." mikan allows far more in a message, so streamed text is split
+ * to fit rather than truncated.
+ */
+const MAX_STREAM_TEXT_CHARS = 12_000;
+/** Slices `text` into pieces that each fit one streaming call. */
+export function chunkStreamText(text, limit = MAX_STREAM_TEXT_CHARS) {
+    if (text.length <= limit)
+        return [text];
+    const chunks = [];
+    for (let index = 0; index < text.length; index += limit) {
+        chunks.push(text.slice(index, index + limit));
+    }
+    return chunks;
+}
+// web-api v8 throws WebAPIRateLimitedError; the duck-typed shapes cover
+// platform `data.error === "rate_limited"` / 429 responses and older callers.
 function slackIsRateLimited(err) {
+    if (err instanceof WebAPIRateLimitedError)
+        return true;
     if (err.code === "rate_limited")
         return true;
     const data = err.data;
@@ -72,11 +99,28 @@ export function buildMrkdwnContextBlock(text) {
 // ============================================================================
 // SlackMessagingBot
 // ============================================================================
+class AttachmentDownloadHttpError extends Error {
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+function isRetryableAttachmentDownloadError(error) {
+    if (!(error instanceof AttachmentDownloadHttpError))
+        return true;
+    return error.status === 408 || error.status === 429 || error.status >= 500;
+}
 export class SlackMessagingBot {
+    /** Host office dir for a Slack conversation. */
+    conversationDir(channelId) {
+        return this.workspace.office(createOfficeAddress("slack", channelId)).dir;
+    }
+    resolveReplyMode(address) {
+        return (resolveConversationSettings(this.workspace.office(address)).slack?.replyMode ?? "top-level");
+    }
     createContext(event) {
         return createSlackAdapters(event, this, {
-            replyMode: resolveConversationSettings(join(this.workingDir, event.conversationId)).slack?.replyMode ??
-                "top-level",
+            replyMode: this.resolveReplyMode(event.address),
         });
     }
     constructor(handler, config) {
@@ -87,11 +131,20 @@ export class SlackMessagingBot {
         this.startupTs = null; // Messages older than this are just logged, not processed
         this.users = new Map();
         this.channels = new Map();
+        /** Which threads belong to the assistant pane, and their last known context. */
+        this.assistantThreads = new AssistantThreadRegistry();
+        /**
+         * Native response streams opened recently. Per bot rather than per module:
+         * the rate tier applies per workspace, and this bot is the connection to
+         * one — which also means a test constructing a bot gets a fresh budget
+         * instead of inheriting whatever ran before it.
+         */
+        this.streamStarts = new StreamStartLimiter();
         this.queues = new Map();
         this.eventsWatcher = null;
         this.handler = handler;
-        this.workingDir = config.workingDir;
-        this.store = config.store;
+        this.workspace = config.workspace;
+        this.botToken = config.botToken;
         this.socketClient = new SocketModeClient({
             appToken: config.appToken,
             // Default 5s is too tight: brief event-loop stalls (e.g. backfill, sync fs)
@@ -145,13 +198,36 @@ export class SlackMessagingBot {
         }
         return source.replace(this.ownMentionRegex, "").trim();
     }
+    /**
+     * Response-source `<@userName>` mentions become native `<@U…>` here — the
+     * one conversion every outgoing response path funnels through. Slack only
+     * links and notifies on raw user ids.
+     */
+    resolveMentions(text) {
+        return resolveSlackMentions(text, this.users.values());
+    }
     async postMessage(channel, text) {
         return slackRetry(async () => {
-            const payload = { channel, ...renderSlackBlocks(text) };
+            const payload = { channel, ...renderSlackBlocks(this.resolveMentions(text)) };
             const result = await this.webClient.chat.postMessage(payload);
             return result.ts;
         });
     }
+    async addReaction(channel, messageTs, emoji) {
+        // Slack reaction names are colon-free short names; strip any wrapping colons.
+        const name = emoji.replace(/^:|:$/g, "");
+        await slackRetry(async () => {
+            try {
+                await this.webClient.reactions.add({ channel, timestamp: messageTs, name });
+            }
+            catch (err) {
+                // Re-reacting with the same emoji is not an error worth surfacing.
+                if (err?.data?.error === "already_reacted")
+                    return;
+                throw err;
+            }
+        });
+    }
     async postEphemeral(channel, user, text, threadTs) {
         return slackRetry(async () => {
             await this.webClient.chat.postEphemeral({
@@ -180,6 +256,11 @@ export class SlackMessagingBot {
             return result.ts;
         });
     }
+    async updateMessageBlocks(channel, ts, text, blocks) {
+        return slackRetry(async () => {
+            await this.webClient.chat.update({ channel, ts, text, blocks: blocks });
+        });
+    }
     async postPrivate(conversationId, userId, text) {
         await this.postEphemeral(conversationId, userId, text);
     }
@@ -190,7 +271,7 @@ export class SlackMessagingBot {
         }
         await this.postEphemeralBlocks(conversationId, userId, text, [buildMrkdwnContextBlock(text)]);
     }
-    async openDirectMessage(userId) {
+    async openDirectConversation(userId) {
         return slackRetry(async () => {
             const result = await this.webClient.conversations.open({ users: userId });
             const channelId = result.channel?.id;
@@ -200,33 +281,127 @@ export class SlackMessagingBot {
             return channelId;
         });
     }
+    /**
+     * Fetch recent messages from a channel, oldest first. Without `threadTs`
+     * this is one `conversations.history` page of top-level messages (thread
+     * replies are not expanded); with it, one `conversations.replies` page of
+     * that thread's replies, excluding the parent. Callers page forward by
+     * passing the last returned `ts` as `oldest`.
+     */
+    async fetchHistory(channel, options) {
+        const limit = Math.min(Math.max(options?.limit ?? 200, 1), 999);
+        const threadTs = options?.threadTs;
+        return slackRetry(async () => {
+            const result = threadTs
+                ? await this.webClient.conversations.replies({
+                    channel,
+                    ts: threadTs,
+                    ...(options?.oldest ? { oldest: options.oldest, inclusive: false } : {}),
+                    limit,
+                })
+                : await this.webClient.conversations.history({
+                    channel,
+                    ...(options?.oldest ? { oldest: options.oldest, inclusive: false } : {}),
+                    limit,
+                });
+            const messages = (result.messages ?? []);
+            const mapped = messages
+                .filter((msg) => !!msg.ts)
+                // conversations.replies leads with the thread parent; the caller asked
+                // for the replies to it, and including it would re-ingest the bot's
+                // own message on every poll.
+                .filter((msg) => msg.ts !== threadTs)
+                .map((msg) => {
+                const user = msg.user ? this.users.get(msg.user) : undefined;
+                const message = {
+                    ts: msg.ts,
+                    text: msg.text ?? "",
+                    isBot: !!msg.bot_id || msg.subtype === "bot_message" || user?.isBot === true,
+                };
+                if (msg.thread_ts && msg.thread_ts !== msg.ts)
+                    message.threadTs = msg.thread_ts;
+                if (msg.user)
+                    message.userId = msg.user;
+                if (user)
+                    message.userName = user.userName;
+                return message;
+            });
+            // history returns newest-first, replies oldest-first; the contract is
+            // oldest-first either way.
+            return threadTs ? mapped : mapped.toReversed();
+        });
+    }
+    /** Refresh and list the workspace's active users (`users.list`). */
+    async listUsers() {
+        await slackRetry(() => this.fetchUsers());
+        return this.getAllUsers().map((user) => ({
+            id: user.id,
+            userName: user.userName,
+            displayName: user.displayName,
+            isBot: user.isBot === true,
+        }));
+    }
     async updateMessage(channel, ts, text) {
         return slackRetry(async () => {
-            const payload = { channel, ts, ...renderSlackBlocks(text) };
+            const payload = { channel, ts, ...renderSlackBlocks(this.resolveMentions(text)) };
             await this.webClient.chat.update(payload);
         });
     }
+    /**
+     * Claim one native stream, or decline. Declining is not an error: the caller
+     * falls back to edit-based updates, which is a working answer rather than a
+     * degraded one, and costs no request against the tighter start tier.
+     */
+    tryReserveStreamStart() {
+        return this.streamStarts.tryReserve();
+    }
+    /**
+     * Open a stream, carrying text of any length.
+     *
+     * Slack caps `markdown_text` at 12,000 characters per call, and a long first
+     * render exceeds that easily — mikan allows 35,000 in a message. Rather than
+     * truncating (losing the answer) or failing (falling back to edit mode for
+     * the whole response), the opening call takes the first slice and the rest
+     * follows as appends before this resolves. The caller sees one operation
+     * that sent everything, so the renderer's idea of what has been streamed
+     * stays true.
+     *
+     * Splitting mid-word or mid-fence is harmless here: a stream concatenates,
+     * so Slack renders the reassembled text, not the pieces.
+     */
     async startMessageStream(channel, text, threadTs, recipientUserId) {
-        return slackRetry(async () => {
+        const [head, ...tail] = chunkStreamText(text);
+        const ts = await slackRetry(async () => {
             const result = await this.webClient.apiCall("chat.startStream", {
                 channel,
-                markdown_text: text,
+                markdown_text: this.resolveMentions(head ?? ""),
                 ...(threadTs ? { thread_ts: threadTs } : {}),
                 ...(this.teamId ? { recipient_team_id: this.teamId } : {}),
                 ...(recipientUserId ? { recipient_user_id: recipientUserId } : {}),
             });
-            const ts = result.ts;
-            if (!ts)
+            const streamTs = result.ts;
+            if (!streamTs)
                 throw new Error("Slack chat.startStream did not return ts");
-            return ts;
+            return streamTs;
         });
+        for (const part of tail)
+            await this.appendStreamChunk(channel, ts, part);
+        return ts;
     }
+    /** Append a delta of any length, split to the per-call cap. */
     async appendMessageStream(channel, ts, text) {
+        for (const part of chunkStreamText(text)) {
+            await this.appendStreamChunk(channel, ts, part);
+        }
+    }
+    async appendStreamChunk(channel, ts, text) {
         return slackRetry(async () => {
             await this.webClient.apiCall("chat.appendStream", {
                 channel,
                 ts,
-                markdown_text: text,
+                // A mention split across stream deltas stays unresolved here; the
+                // canonical final render (updateMessage) resolves the full text.
+                markdown_text: this.resolveMentions(text),
             });
         });
     }
@@ -253,9 +428,76 @@ export class SlackMessagingBot {
             });
         });
     }
+    /** Offer starting points in a new assistant thread. */
+    async setAssistantSuggestedPrompts(channel, threadTs, prompts) {
+        return slackRetry(async () => {
+            // Omitting thread_ts pins the prompts to the DM itself, which is what
+            // the agent surface wants: there is no thread yet when it opens.
+            await this.webClient.assistant.threads.setSuggestedPrompts({
+                channel_id: channel,
+                ...(threadTs ? { thread_ts: threadTs } : {}),
+                prompts,
+            });
+        });
+    }
+    /** Name an assistant thread, which is what the sidebar conversation list shows. */
+    async setAssistantTitle(channel, threadTs, title) {
+        return slackRetry(async () => {
+            await this.webClient.assistant.threads.setTitle({
+                channel_id: channel,
+                thread_ts: threadTs,
+                title,
+            });
+        });
+    }
+    /** The assistant surface's view of this bot, handed to the lifecycle handlers. */
+    assistantOps() {
+        return {
+            postInThread: (channel, threadTs, text) => this.postInThread(channel, threadTs, text),
+            setSuggestedPrompts: (channel, threadTs, prompts) => this.setAssistantSuggestedPrompts(channel, threadTs, prompts),
+            setTitle: (channel, threadTs, title) => this.setAssistantTitle(channel, threadTs, title),
+            channelName: (channelId) => this.channels.get(channelId)?.name,
+        };
+    }
+    /**
+     * A new conversation opened in the assistant pane. Slack waits for the app
+     * to speak first here; staying silent is what makes the pane look broken.
+     */
+    handleAssistantThreadStarted({ event, ack }) {
+        ack();
+        const payload = event;
+        if (!payload.assistant_thread)
+            return;
+        void handleAssistantThreadStarted(this.assistantOps(), this.assistantThreads, payload.assistant_thread);
+    }
+    /**
+     * The person navigated to another channel while the pane is open. Slack
+     * sends this as `assistant_thread_context_changed` under `assistant_view`
+     * and `app_context_changed` under `agent_view`; the payload differs enough
+     * to normalize here rather than in the handler.
+     */
+    handleAgentContextChangedEvent({ event, ack, }) {
+        ack();
+        const payload = event;
+        if (payload.assistant_thread) {
+            handleAgentContextChanged(this.assistantThreads, payload.assistant_thread);
+            return;
+        }
+        const channelId = payload.channel_id ?? payload.channel;
+        if (channelId) {
+            handleAgentContextChanged(this.assistantThreads, {
+                channel_id: channelId,
+                context: payload.context,
+            });
+        }
+    }
     async postInThread(channel, threadTs, text) {
         return slackRetry(async () => {
-            const payload = { channel, thread_ts: threadTs, ...renderSlackBlocks(text) };
+            const payload = {
+                channel,
+                thread_ts: threadTs,
+                ...renderSlackBlocks(this.resolveMentions(text)),
+            };
             const result = await this.webClient.chat.postMessage(payload);
             return result.ts;
         });
@@ -286,18 +528,39 @@ export class SlackMessagingBot {
         });
     }
     logToFile(channel, entry) {
-        appendChannelLog(this.workingDir, channel, entry);
+        appendChannelLog(this.workspace.office(createOfficeAddress("slack", channel)), entry);
     }
     logBotResponse(channel, text, ts, threadTs, slackBlocks) {
-        appendBotResponseLog(this.workingDir, channel, text, ts, threadTs, {
+        appendBotResponseLog(this.workspace.office(createOfficeAddress("slack", channel)), text, ts, threadTs, {
             platform: "slack",
             ...(slackBlocks ? { slackBlocks } : {}),
         });
     }
+    ownsBlockKitMessage(channel, ts, threadTs) {
+        const content = readTextFileIfExists(join(this.conversationDir(channel), "log.jsonl"));
+        if (content === undefined)
+            return false;
+        for (const line of content.trim().split("\n").toReversed()) {
+            try {
+                const entry = JSON.parse(line);
+                if (!isRecord(entry) || entry.ts !== ts)
+                    continue;
+                return (entry.isMessagingBot === true &&
+                    entry.platform === "slack" &&
+                    Array.isArray(entry.slackBlocks) &&
+                    entry.threadTs === threadTs);
+            }
+            catch {
+                continue;
+            }
+        }
+        return false;
+    }
     getMessagingInfo() {
         return {
             name: "slack",
-            formattingGuide: "## Slack Formatting (mrkdwn, NOT Markdown)\nBold: *text*, Italic: _text_, Code: `code`, Block: ```code```, Links: <url|text>\nDo NOT use **double asterisks** or [markdown](links).",
+            trustModel: "membership",
+            formattingGuide: "## Slack Formatting\nWrite standard Markdown/GFM: **bold**, _italic_, ~~strike~~, `code`, fenced code blocks, [links](url), lists, and pipe tables (rendered as native Slack tables).\nDo NOT use Slack mrkdwn syntax like *single-asterisk bold* or <url|label> links.",
             channels: this.getAllChannels().map((c) => ({ id: c.id, name: c.name })),
             users: this.getAllUsers().map((u) => ({
                 id: u.id,
@@ -352,7 +615,7 @@ export class SlackMessagingBot {
             const eventForRun = eventPlan.event;
             if (eventPlan.initialMessageTs && eventForRun.sessionKey) {
                 registerThreadSession({
-                    conversationDir: join(this.workingDir, conversationId),
+                    conversationDir: this.conversationDir(conversationId),
                     sessionKey: eventForRun.sessionKey,
                 });
             }
@@ -360,7 +623,9 @@ export class SlackMessagingBot {
                 initialMessageTs: eventPlan.initialMessageTs,
             }).sessionKey;
             this.getQueue(runQueueKey).enqueue(async () => {
-                const slackEvent = {
+                const slackEvent = createConversationEvent({
+                    platform: "slack",
+                    address: eventForRun.address,
                     type: eventForRun.type,
                     conversationId,
                     conversationKind: eventForRun.conversationKind,
@@ -369,16 +634,12 @@ export class SlackMessagingBot {
                     thread_ts: eventForRun.thread_ts,
                     user: eventForRun.user,
                     text: eventForRun.text,
-                    attachments: eventForRun.attachments?.map((attachment) => ({
-                        original: attachment.name,
-                        localPath: attachment.localPath,
-                    })),
+                    attachments: eventForRun.attachments,
                     sessionKey: eventForRun.sessionKey,
-                };
+                });
                 const context = createSlackAdapters(slackEvent, this, {
                     initialMessageTs: eventPlan.initialMessageTs,
-                    replyMode: resolveConversationSettings(join(this.workingDir, eventForRun.conversationId)).slack
-                        ?.replyMode ?? "top-level",
+                    replyMode: this.resolveReplyMode(eventForRun.address),
                 });
                 return this.handler.handleEvent(eventForRun, this, context);
             });
@@ -399,21 +660,29 @@ export class SlackMessagingBot {
     resolveQueueKey(conversationId, sessionKey) {
         if (!isSlackThreadSessionKey(sessionKey))
             return sessionKey;
-        if (this.handler.isRunning(sessionKey))
+        if (this.handler.isRunning(createOfficeAddress("slack", conversationId), sessionKey)) {
             return sessionKey;
+        }
         return this.hasKnownThreadSession(conversationId, sessionKey) ? sessionKey : conversationId;
     }
     hasKnownThreadSession(conversationId, sessionKey) {
         return hasMaterializedChatSession({
-            conversationDir: join(this.workingDir, conversationId),
+            conversationDir: this.conversationDir(conversationId),
             sessionKey,
         });
     }
     processSlackMessageIntake(options) {
-        void processMessageIntake({
+        const absorbAttachmentFailure = () => {
+            void options.attachmentsPromise.catch((err) => {
+                log.logWarning("Failed to log Slack message", String(err));
+            });
+        };
+        processMessageIntake({
             eventBase: options.event,
-            workingDir: this.workingDir,
+            office: this.workspace.office(options.event.address),
             isAutoReplyCandidate: options.isAutoReplyCandidate,
+            magicWord: { addressed: options.addressed, scopeFallback: "top-level" },
+            busyPolicy: "queue",
             logEntryBase: {},
             processAttachments: () => options.attachmentsPromise,
             queueKey: options.queueKey,
@@ -421,8 +690,15 @@ export class SlackMessagingBot {
             handler: this.handler,
             bot: this,
             createContext: (event) => this.createContext(event),
-            onNotTriggered: options.onNotTriggered,
             deferAttachmentsUntilRun: true,
+        }).then((outcome) => {
+            // Slack logs eagerly via logUserMessage; when intake does not enqueue,
+            // nothing awaits the attachment download, so absorb its failure here.
+            if (outcome !== "enqueued")
+                absorbAttachmentFailure();
+        }, (err) => {
+            log.logWarning("Slack message intake failed", String(err));
+            absorbAttachmentFailure();
         });
     }
     buildHomeView() {
@@ -460,7 +736,7 @@ export class SlackMessagingBot {
             // Threshold for "stuck" detection (10 minutes)
             const STUCK_THRESHOLD_MS = 10 * 60 * 1000;
             for (const session of runningSessions) {
-                const channelId = session.sessionKey.split(":")[0];
+                const channelId = conversationIdOf(session.sessionKey);
                 const channel = this.channels.get(channelId);
                 const channelName = channel ? `#${channel.name}` : channelId;
                 const elapsed = Math.floor((Date.now() - session.startedAt) / 60000);
@@ -500,7 +776,14 @@ export class SlackMessagingBot {
                             {
                                 type: "button",
                                 text: { type: "plain_text", text: "Force Stop", emoji: true },
+                                // The raw session key travels in `value` (Slack returns it
+                                // verbatim); the action_id only routes and must be unique per
+                                // view, so it carries a sanitized copy of the key. Never
+                                // decode the key from the action_id — the `:`↔`_` rewrite is
+                                // irreversible for conversation ids that contain `_` (GitHub's
+                                // GH_owner_repo_number do, by design).
                                 action_id: `force_stop_${session.sessionKey.replace(/:/g, "_")}`,
+                                value: session.sessionKey,
                                 style: "danger",
                             },
                         ],
@@ -559,24 +842,10 @@ export class SlackMessagingBot {
         });
         return { type: "home", blocks: blocks };
     }
-    resolveStopTarget(channelId, threadTs) {
-        const directTarget = resolveStopTarget({
-            handler: this.handler,
-            conversationId: channelId,
-            sessionKey: resolveSlackSessionKey(channelId, threadTs),
-        });
-        if (directTarget)
-            return directTarget;
-        if (threadTs)
-            return null;
-        return resolveOnlyScopedStopTarget(this.handler, channelId);
-    }
-    isStopText(text) {
-        const normalized = text.trim().toLowerCase();
-        return normalized === "stop" || normalized === "/stop";
-    }
     createCommandAdapters(conversationId, userId, userName, text, ts, options = {}) {
-        const message = {
+        const message = createConversationMessage({
+            platform: "slack",
+            conversationId,
             id: ts,
             sessionKey: conversationId,
             conversationKind: options.ephemeralChannelId ? "shared" : "direct",
@@ -584,7 +853,7 @@ export class SlackMessagingBot {
             userName,
             text,
             attachments: [],
-        };
+        });
         const respond = async (responseText) => {
             if (options.ephemeralChannelId) {
                 await this.postEphemeral(options.ephemeralChannelId, userId, responseText, options.threadTs);
@@ -624,6 +893,7 @@ export class SlackMessagingBot {
             deleteResponse: async () => { },
         };
         return {
+            address: message.address,
             message,
             responder,
             platform: this.getMessagingInfo(),
@@ -651,9 +921,10 @@ export class SlackMessagingBot {
             isMessagingBot: false,
             ...(threadTs ? { threadTs } : {}),
         });
-        const event = {
-            type: options.type ?? (isDirectMessage ? "dm" : "mention"),
+        const event = createConversationEvent({
+            platform: "slack",
             conversationId,
+            type: options.type ?? (isDirectMessage ? "dm" : "mention"),
             conversationKind: isDirectMessage ? "direct" : "shared",
             ts: eventTs,
             user: payload.user_id,
@@ -661,14 +932,27 @@ export class SlackMessagingBot {
             attachments: [],
             ...(threadTs ? { thread_ts: threadTs } : {}),
             sessionKey,
-        };
+        });
         const context = this.createCommandAdapters(conversationId, payload.user_id, userName, commandText, eventTs, isDirectMessage ? { threadTs } : { ephemeralChannelId: conversationId, threadTs });
         return { event, context };
     }
-    async routeSlashLoginCommand(payload) {
+    /**
+     * Generic slash-command route: synthesize the command text per the
+     * manifest's SlackSlashRoute data and dispatch to the handler. `/pi-new`
+     * stays bespoke (routeSlashNewCommand) because it replies in 中文 and calls
+     * handleNewCommand directly.
+     */
+    async routeSlashCommand(route, payload) {
         const { event, context } = this.buildSlashCommandEvent(payload, {
-            type: payload.channel_id.startsWith("D") ? "dm" : "private_command",
-            includeText: true,
+            includeText: route.includeText,
+            thread: route.thread,
+            ...(route.privateCommand
+                ? {
+                    type: payload.channel_id.startsWith("D")
+                        ? "dm"
+                        : "private_command",
+                }
+                : {}),
         });
         await this.handler.handleEvent(event, this, context);
     }
@@ -697,19 +981,22 @@ export class SlackMessagingBot {
             enqueueEvent: (event) => this.enqueueEvent(event),
             getMessagingInfo: () => this.getMessagingInfo(),
         };
-        await this.handler.handleNewCommand(conversationId, conversationId, commandMessagingBot);
-    }
-    async routeSlashModelCommand(payload) {
-        const { event, context } = this.buildSlashCommandEvent(payload, { includeText: true });
-        await this.handler.handleEvent(event, this, context);
-    }
-    async routeSlashSessionCommand(payload) {
-        const { event, context } = this.buildSlashCommandEvent(payload, { thread: true });
-        await this.handler.handleEvent(event, this, context);
-    }
-    async routeSlashAdminCommand(payload) {
-        const { event, context } = this.buildSlashCommandEvent(payload, { thread: true });
-        await this.handler.handleEvent(event, this, context);
+        const event = {
+            ...createConversationEvent({
+                platform: "slack",
+                conversationId,
+                type: "dm",
+                conversationKind: "direct",
+                ts: eventTs,
+                user: payload.user_id,
+                text: payload.command,
+                attachments: [],
+                sessionKey: conversationId,
+            }),
+            channel: conversationId,
+        };
+        const context = createSlackAdapters(event, this);
+        await this.handler.handleNewCommand(conversationId, conversationId, commandMessagingBot, context.message, context.responder, context.platform);
     }
     setupEventHandlers() {
         this.socketClient.on("disconnect", (err) => {
@@ -721,10 +1008,27 @@ export class SlackMessagingBot {
         this.socketClient.on("unable_to_socket_mode_start", (err) => {
             log.logWarning("Slack socket unable_to_start", err ? String(err) : "");
         });
+        // Which events Slack actually delivers is otherwise unknowable from here:
+        // a listener that never fires looks the same whether the subscription is
+        // missing, the app needs reinstalling, or the surface never emits it at
+        // all. Off by default — this is one line per event on a busy workspace.
+        if (readEnv("SLACK_TRACE_EVENTS")) {
+            this.socketClient.on("slack_event", ({ type, body }) => {
+                const inner = body?.event;
+                log.logInfo(`Slack socket event: ${type ?? "?"}${inner?.type ? ` → ${inner.type}` : ""}${inner?.tab ? ` (tab: ${inner.tab})` : ""}`);
+            });
+        }
         this.socketClient.on("app_mention", (payload) => this.handleAppMention(payload));
         this.socketClient.on("message", (payload) => this.handleMessageEvent(payload));
         this.socketClient.on("slash_commands", (payload) => void this.handleSlashCommand(payload));
         this.socketClient.on("app_home_opened", (payload) => this.handleAppHomeOpened(payload));
+        // The assistant surface's lifecycle. Both events were already subscribed
+        // in the app manifest and then dropped on the floor, which is why the pane
+        // opened empty and the sidebar filled with untitled conversations.
+        this.socketClient.on("assistant_thread_started", (payload) => this.handleAssistantThreadStarted(payload));
+        this.socketClient.on("assistant_thread_context_changed", (payload) => this.handleAgentContextChangedEvent(payload));
+        // agent_view's spelling of the same signal.
+        this.socketClient.on("app_context_changed", (payload) => this.handleAgentContextChangedEvent(payload));
         this.socketClient.on("block_actions", (payload) => void this.handleBlockAction(payload));
         this.socketClient.on("interactive", (payload) => void this.handleBlockAction(payload));
     }
@@ -739,18 +1043,19 @@ export class SlackMessagingBot {
         // Thread replies get their own isolated session (channelId:thread_ts).
         const sessionKey = resolveSlackSessionKey(e.channel, e.thread_ts);
         const mentionText = this.stripOwnMention(e.text);
-        const slackEvent = {
-            type: "mention",
+        const slackEvent = createConversationEvent({
+            platform: "slack",
             conversationId: e.channel,
+            type: "mention",
             conversationKind: "shared",
-            channel: e.channel,
             ts: e.ts,
             thread_ts: e.thread_ts,
             user: e.user,
             text: mentionText || "Please respond to the recent conversation context.",
-            files: e.files,
             sessionKey,
-        };
+            channel: e.channel,
+            files: e.files,
+        });
         const attachmentsPromise = this.logUserMessage(slackEvent);
         // Only trigger processing for messages AFTER startup (not replayed old messages)
         if (this.startupTs && e.ts < this.startupTs) {
@@ -761,26 +1066,12 @@ export class SlackMessagingBot {
             ack();
             return;
         }
-        // Check for stop command - execute immediately, don't queue!
-        if (this.isStopText(slackEvent.text)) {
-            const stopTarget = this.resolveStopTarget(e.channel, e.thread_ts);
-            if (stopTarget) {
-                this.handler.handleStop(stopTarget, e.channel, this);
-            }
-            else {
-                this.postMessage(e.channel, formatNothingRunning("slack"));
-            }
-            void attachmentsPromise.catch((err) => {
-                log.logWarning("Failed to log Slack message", String(err));
-            });
-            ack();
-            return;
-        }
         this.processSlackMessageIntake({
             event: slackEvent,
             attachmentsPromise,
             queueKey: this.resolveQueueKey(e.channel, sessionKey),
             isAutoReplyCandidate: false,
+            addressed: true,
         });
         ack();
     }
@@ -793,7 +1084,13 @@ export class SlackMessagingBot {
             ack();
             return;
         }
-        const isExternalMessagingBotMessage = !!e.bot_id || e.subtype === "bot_message";
+        // API posts made with a user token carry the posting app's bot_id/app_id
+        // alongside the human `user` — bot_id alone does not make the author a
+        // bot. Only treat the message as bot-authored when the author is not a
+        // known human user (bot users have is_bot=true; unknown authors stay on
+        // the conservative bot path so loop protection holds).
+        const authorIsKnownHuman = !!e.user && this.users.get(e.user)?.isBot === false;
+        const isExternalMessagingBotMessage = e.subtype === "bot_message" || (!!e.bot_id && !authorIsKnownHuman);
         if (isExternalMessagingBotMessage) {
             if (e.subtype !== undefined && e.subtype !== "bot_message" && e.subtype !== "file_share") {
                 ack();
@@ -821,7 +1118,11 @@ export class SlackMessagingBot {
             ack();
             return;
         }
-        const isDM = e.channel_type === "im";
+        // message.im normally carries channel_type "im", but fall back to the
+        // D-prefix convention (used by handleAppMention and session keys) so a
+        // missing channel_type cannot silently demote a DM to an auto-reply
+        // candidate that never triggers.
+        const isDM = e.channel_type === "im" || e.channel.startsWith("D");
         const conversationKind = isDM ? "direct" : "shared";
         const isMessagingBotMention = e.text?.includes(`<@${this.botUserId}>`);
         // Skip channel @mentions - already handled by app_mention event
@@ -831,18 +1132,25 @@ export class SlackMessagingBot {
         }
         const isThreadReply = !!e.thread_ts;
         const sessionKey = isDM ? resolveSlackSessionKey(e.channel, e.thread_ts) : undefined;
-        const slackEvent = {
-            type: isDM ? "dm" : "mention",
+        // Name the conversation from the first thing the person said. Guarded on
+        // the assistant registry, so classic DM threads are untouched, and it
+        // claims the title once per thread.
+        if (isDM && e.thread_ts && e.text) {
+            void titleAssistantThread(this.assistantOps(), this.assistantThreads, e.channel, e.thread_ts, this.stripOwnMention(e.text));
+        }
+        const slackEvent = createConversationEvent({
+            platform: "slack",
             conversationId: e.channel,
+            type: (isDM ? "dm" : "mention"),
             conversationKind,
-            channel: e.channel,
             ts: e.ts,
             thread_ts: e.thread_ts,
             user: e.user,
             text: this.stripOwnMention(e.text),
-            files: e.files,
             sessionKey,
-        };
+            channel: e.channel,
+            files: e.files,
+        });
         const attachmentsPromise = this.logUserMessage(slackEvent);
         // Only trigger processing for messages AFTER startup (not replayed old messages)
         if (this.startupTs && e.ts < this.startupTs) {
@@ -853,59 +1161,26 @@ export class SlackMessagingBot {
             ack();
             return;
         }
-        // Stop command for DM only (app_mention handles shared-channel "@mikan stop").
-        if (isDM && this.isStopText(slackEvent.text)) {
-            const stopTarget = this.resolveStopTarget(e.channel, e.thread_ts);
-            if (stopTarget) {
-                this.handler.handleStop(stopTarget, e.channel, this);
-            }
-            else {
-                this.postMessage(e.channel, formatNothingRunning("slack"));
-            }
+        if (!isDM && isThreadReply) {
             void attachmentsPromise.catch((err) => {
                 log.logWarning("Failed to log Slack message", String(err));
             });
             ack();
             return;
         }
-        const enqueueTriggered = () => {
-            const activeSessionKey = slackEvent.sessionKey ?? resolveSlackSessionKey(e.channel, e.thread_ts);
-            // Auto-reply top-level channel messages start with no sessionKey because
-            // they are only candidates until the policy allows them. Once triggered,
-            // persist the resolved key on the event; otherwise the runtime fallback
-            // treats the message ts as a thread session (`channel:ts`) instead of the
-            // persistent top-level channel session.
-            slackEvent.sessionKey = activeSessionKey;
-            this.processSlackMessageIntake({
-                event: slackEvent,
-                attachmentsPromise,
-                queueKey: this.resolveQueueKey(e.channel, activeSessionKey),
-                isAutoReplyCandidate: false,
-            });
-        };
-        const logOnly = () => {
-            void attachmentsPromise.catch((err) => {
-                log.logWarning("Failed to log Slack message", String(err));
-            });
-        };
-        if (isDM) {
-            enqueueTriggered();
-            ack();
-            return;
-        }
-        if (isThreadReply) {
-            logOnly();
-            ack();
-            return;
-        }
-        const activeSessionKey = resolveSlackSessionKey(e.channel, e.thread_ts);
+        const activeSessionKey = slackEvent.sessionKey ?? resolveSlackSessionKey(e.channel, e.thread_ts);
+        // Auto-reply top-level channel messages start with no sessionKey because
+        // they are only candidates until the policy allows them. Persist the
+        // resolved key on the event; otherwise the runtime fallback treats the
+        // message ts as a thread session (`channel:ts`) instead of the persistent
+        // top-level channel session.
         slackEvent.sessionKey = activeSessionKey;
         this.processSlackMessageIntake({
             event: slackEvent,
             attachmentsPromise,
             queueKey: this.resolveQueueKey(e.channel, activeSessionKey),
-            isAutoReplyCandidate: true,
-            onNotTriggered: logOnly,
+            isAutoReplyCandidate: !isDM,
+            addressed: isDM,
         });
         ack();
     }
@@ -916,54 +1191,20 @@ export class SlackMessagingBot {
             return;
         }
         const { command, text, channel_id, user_id, user_name, thread_ts } = payload;
+        const entry = COMMAND_MANIFEST.find((candidate) => candidate.slackCommand === command);
+        if (!entry)
+            return;
         let handlerPromise = null;
-        if (command === "/pi-login") {
-            handlerPromise = this.routeSlashLoginCommand({
-                command,
-                text,
-                channel_id,
-                user_id,
-                user_name,
-            });
-        }
-        else if (command === "/pi-new") {
+        if (entry.name === "new") {
             handlerPromise = this.routeSlashNewCommand({ command, channel_id, user_id, user_name });
         }
-        else if (command === "/pi-session") {
-            handlerPromise = this.routeSlashSessionCommand({
-                command,
-                channel_id,
-                user_id,
-                user_name,
-                thread_ts,
-            });
-        }
-        else if (command === "/pi-model") {
-            handlerPromise = this.routeSlashModelCommand({
-                command,
-                text,
-                channel_id,
-                user_id,
-                user_name,
-            });
-        }
-        else if (command === "/pi-sandbox" ||
-            command === "/pi-auto-reply" ||
-            command === "/pi-extensions") {
-            handlerPromise = this.routeSlashModelCommand({
+        else if (entry.slackRoute) {
+            handlerPromise = this.routeSlashCommand(entry.slackRoute, {
                 command,
                 text,
                 channel_id,
                 user_id,
                 user_name,
-            });
-        }
-        else if (command === "/pi-admin") {
-            handlerPromise = this.routeSlashAdminCommand({
-                command,
-                channel_id,
-                user_id,
-                user_name,
                 thread_ts,
             });
         }
@@ -977,6 +1218,16 @@ export class SlackMessagingBot {
     handleAppHomeOpened({ event, ack }) {
         const e = event;
         ack();
+        // Under agent_view this is how Slack says "the person opened the app's
+        // DM" — the signal assistant_thread_started used to carry. It fires on
+        // every open, not once per conversation, so this path refreshes the
+        // pinned prompts and deliberately does not greet.
+        if (e.tab === "messages") {
+            if (e.channel) {
+                void handleAgentDmOpened(this.assistantOps(), this.assistantThreads, e.channel, e.context);
+            }
+            return;
+        }
         if (e.tab !== "home")
             return;
         this.webClient.views
@@ -1000,12 +1251,15 @@ export class SlackMessagingBot {
             return;
         }
         ack();
-        const sessionKey = action.action_id.replace("force_stop_", "").replace(/_/g, ":");
+        // Prefer the verbatim key from `value`; the action_id fallback only
+        // serves buttons rendered before `value` existed and misdecodes session
+        // keys whose conversation id contains "_".
+        const sessionKey = action.value ?? action.action_id.replace("force_stop_", "").replace(/_/g, ":");
         const userId = body.user?.id;
-        const channelId = body.container?.channel_id || sessionKey.split(":")[0];
+        const channelId = body.container?.channel_id || conversationIdOf(sessionKey);
         log.logInfo(`[Force Stop] User ${userId} requested force stop for ${sessionKey}`);
         // Use handler's forceStop method
-        this.handler.forceStop(sessionKey);
+        this.handler.forceStop(createOfficeAddress("slack", channelId), sessionKey);
         // Notify in channel
         await this.postMessage(channelId, formatForceStopped("slack", userId ?? "unknown"));
         // Refresh home tab
@@ -1030,6 +1284,38 @@ export class SlackMessagingBot {
         const selectedOptions = Array.isArray(action.selected_options)
             ? action.selected_options
             : undefined;
+        const threadTs = container.thread_ts;
+        const sessionKey = resolveSlackSessionKey(channelId, threadTs);
+        // Extension-owned actions (ext:<slug>: namespaced by api.blockkit.post)
+        // dispatch exclusively to the extension's onAction handler — no agent
+        // run, no chat-history entry. They never fall through to the model: an
+        // unconsumed namespaced action means the extension is gone, and its
+        // routing id would only confuse an agent run.
+        const extAction = parseExtActionId(action.action_id ?? "");
+        if (extAction) {
+            this.getQueue(this.resolveQueueKey(channelId, sessionKey)).enqueue(async () => {
+                const consumed = await this.handler.handleExtensionAction({
+                    address: createOfficeAddress("slack", channelId),
+                    sessionKey,
+                    conversationKind: channelId.startsWith("D") ? "direct" : "shared",
+                    slug: extAction.slug,
+                    action: {
+                        actionId: extAction.actionId,
+                        value: action.value ?? selectedOption?.value ?? selectedOption?.text?.text,
+                        selectedValues: selectedOptions?.map((option) => option.value ?? option.text?.text ?? ""),
+                        userId,
+                        userName: body.user?.username ?? body.user?.name,
+                        conversationId: channelId,
+                        messageTs: container.message_ts,
+                        threadTs,
+                    },
+                });
+                if (!consumed) {
+                    log.logWarning(`[${channelId}] Dropped extension action ${action.action_id}`, `no handler registered by extension "${extAction.slug}"`);
+                }
+            });
+            return;
+        }
         const selectedText = selectedOption?.text?.text ?? selectedOption?.value;
         const selectedTexts = selectedOptions?.map((option) => option.text?.text ?? option.value);
         const valueText = selectedTexts?.length
@@ -1037,8 +1323,6 @@ export class SlackMessagingBot {
             : (selectedText ?? action.value ?? action.action_id);
         const text = `[Slack action] ${action.action_id}: ${valueText}`;
         const ts = `action:${Date.now()}`;
-        const threadTs = container.thread_ts;
-        const sessionKey = resolveSlackSessionKey(channelId, threadTs);
         this.logToFile(channelId, {
             date: new Date().toISOString(),
             ts,
@@ -1065,9 +1349,10 @@ export class SlackMessagingBot {
                 messageTs: container.message_ts,
             },
         });
-        const event = {
-            type: "slack_action",
+        const event = createConversationEvent({
+            platform: "slack",
             conversationId: channelId,
+            type: "slack_action",
             conversationKind: channelId.startsWith("D") ? "direct" : "shared",
             ts,
             user: userId,
@@ -1075,23 +1360,71 @@ export class SlackMessagingBot {
             attachments: [],
             ...(threadTs ? { thread_ts: threadTs } : {}),
             sessionKey,
-        };
+        });
         this.getQueue(this.resolveQueueKey(channelId, sessionKey)).enqueue(async () => {
             const slackEvent = {
-                type: event.conversationKind === "direct" ? "dm" : "mention",
-                conversationId: channelId,
-                conversationKind: event.conversationKind,
+                ...createConversationEvent({
+                    platform: "slack",
+                    conversationId: channelId,
+                    type: (event.conversationKind === "direct" ? "dm" : "mention"),
+                    conversationKind: event.conversationKind,
+                    ts,
+                    thread_ts: threadTs,
+                    user: userId,
+                    text,
+                    attachments: [],
+                    sessionKey,
+                }),
                 channel: channelId,
-                ts,
-                thread_ts: threadTs,
-                user: userId,
-                text,
                 attachments: [],
-                sessionKey,
             };
             return this.handler.handleEvent(event, this, this.createContext(slackEvent));
         });
     }
+    /**
+     * Download Slack message files into the office's attachments directory.
+     * The Slack contract is all-or-error: any failed download throws after the
+     * successful ones are on disk, so callers still log the message text.
+     */
+    async processAttachments(channelId, files, timestamp) {
+        const items = [];
+        for (const file of files) {
+            const url = file.url_private_download || file.url_private;
+            if (!url)
+                continue;
+            if (!file.name) {
+                throw new Error(`Attachment missing name for URL: ${url}`);
+            }
+            items.push({
+                name: file.name,
+                // Slack timestamps are float seconds; the stored filename uses ms.
+                timestampMs: Math.floor(parseFloat(timestamp) * 1000),
+                download: (destPath) => this.downloadSlackFile(url, destPath),
+            });
+        }
+        const office = this.workspace.office(createOfficeAddress("slack", channelId));
+        const { saved, failed } = await saveIncomingAttachments(office, items);
+        const firstFailure = failed[0];
+        if (firstFailure) {
+            const { name, error } = firstFailure;
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to download attachment ${name}: ${errorMsg}`, { cause: error });
+        }
+        return saved;
+    }
+    /** Authorized download with retry; Slack file URLs require the bot token. */
+    async downloadSlackFile(url, destPath) {
+        await withRetry(async () => {
+            const response = await fetch(url, {
+                headers: { Authorization: `Bearer ${this.botToken}` },
+            });
+            if (!response.ok) {
+                throw new AttachmentDownloadHttpError(`HTTP ${response.status}: ${response.statusText}`, response.status);
+            }
+            const buffer = await response.arrayBuffer();
+            await writeFile(destPath, Buffer.from(buffer));
+        }, { maxAttempts: 3, baseDelayMs: 250, isRateLimited: isRetryableAttachmentDownloadError });
+    }
     /**
      * Log a user message to log.jsonl after attachments are ready.
      */
@@ -1101,7 +1434,7 @@ export class SlackMessagingBot {
         let attachmentError;
         if (event.files) {
             try {
-                attachments = await this.store.processAttachments(event.channel, event.files, event.ts);
+                attachments = await this.processAttachments(event.channel, event.files, event.ts);
             }
             catch (err) {
                 attachmentError = err;
@@ -1126,7 +1459,7 @@ export class SlackMessagingBot {
     }
     async logExternalMessagingBotMessage(event) {
         const attachments = event.files
-            ? await this.store.processAttachments(event.channel, event.files, event.ts)
+            ? await this.processAttachments(event.channel, event.files, event.ts)
             : [];
         const botName = event.username ?? event.bot_profile?.name ?? event.bot_profile?.real_name ?? event.bot_id;
         this.logToFile(event.channel, {
@@ -1149,7 +1482,7 @@ export class SlackMessagingBot {
     // Private - Backfill
     // ==========================================================================
     async getExistingTimestamps(channelId) {
-        const logPath = join(this.workingDir, channelId, "log.jsonl");
+        const logPath = join(this.conversationDir(channelId), "log.jsonl");
         const timestamps = new Set();
         if (!existsSync(logPath))
             return timestamps;
@@ -1157,7 +1490,7 @@ export class SlackMessagingBot {
         const lines = content.trim().split("\n").filter(Boolean);
         for (let i = 0; i < lines.length; i++) {
             try {
-                const entry = JSON.parse(lines[i]);
+                const entry = JSON.parse(lines[i] ?? "");
                 if (entry.ts)
                     timestamps.add(entry.ts);
             }
@@ -1235,7 +1568,7 @@ export class SlackMessagingBot {
             const user = this.users.get(msg.user);
             const text = this.stripOwnMention(msg.text);
             const attachments = msg.files
-                ? await this.store.processAttachments(channelId, msg.files, msg.ts)
+                ? await this.processAttachments(channelId, msg.files, msg.ts)
                 : [];
             this.logToFile(channelId, {
                 date: new Date(parseFloat(msg.ts) * 1000).toISOString(),
@@ -1256,7 +1589,7 @@ export class SlackMessagingBot {
         // Only backfill channels that already have a log.jsonl (mikan has interacted with them before)
         const channelsToBackfill = [];
         for (const [channelId, channel] of this.channels) {
-            const logPath = join(this.workingDir, channelId, "log.jsonl");
+            const logPath = join(this.conversationDir(channelId), "log.jsonl");
             if (existsSync(logPath)) {
                 channelsToBackfill.push([channelId, channel]);
             }
@@ -1274,7 +1607,7 @@ export class SlackMessagingBot {
                 log.logWarning(`Failed to backfill #${channel.name}`, String(error));
             }
             // Add delay between channels to avoid hitting Slack rate limits
-            if (channelId !== channelsToBackfill[channelsToBackfill.length - 1][0]) {
+            if (channelId !== channelsToBackfill[channelsToBackfill.length - 1]?.[0]) {
                 await new Promise((resolve) => setTimeout(resolve, 500));
             }
         }
@@ -1296,6 +1629,7 @@ export class SlackMessagingBot {
                             id: u.id,
                             userName: u.name,
                             displayName: u.real_name || u.name,
+                            isBot: !!u.is_bot,
                         });
                     }
                 }