@iflow-mcp/jkheadley-instar 0.26.2

package/dist/messaging/shared/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/messaging/shared/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAErE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAKnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAKzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAU3D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClG,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EACL,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAAE,aAAa,EACtE,qBAAqB,GACtB,MAAM,yBAAyB,CAAC"}

package/dist/messaging/slack/ChannelManager.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ChannelManager — Slack channel CRUD operations.
+ *
+ * Handles channel creation (with naming conventions), archiving,
+ * listing, and history retrieval. Uses conversations.* API methods.
+ */
+import type { SlackApiClient } from './SlackApiClient.js';
+import type { SlackChannel, SlackMessage } from './types.js';
+export declare class ChannelManager {
+    private api;
+    private agentName;
+    constructor(api: SlackApiClient, agentName: string);
+    /**
+     * Create a channel. Returns the channel ID.
+     * Validates name format. Checks for existing channel first (idempotent).
+     */
+    createChannel(name: string, isPrivate?: boolean): Promise<string>;
+    /** Create a system channel with the agent prefix. */
+    createSystemChannel(category: string, descriptor: string): Promise<string>;
+    /** Archive a channel (reversible). */
+    archiveChannel(channelId: string): Promise<void>;
+    /** Unarchive a channel. */
+    unarchiveChannel(channelId: string): Promise<void>;
+    /** List all channels the bot is in. */
+    listChannels(): Promise<SlackChannel[]>;
+    /** Get channel info. */
+    getChannelInfo(channelId: string): Promise<SlackChannel>;
+    /**
+     * Get channel message history (for cold start / cache miss only).
+     * Use ring buffer for hot-path reads.
+     */
+    getChannelHistory(channelId: string, limit?: number): Promise<SlackMessage[]>;
+    /** Find a channel by name (returns first match or null). */
+    private findChannelByName;
+}
+//# sourceMappingURL=ChannelManager.d.ts.map

package/dist/messaging/slack/ChannelManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChannelManager.d.ts","sourceRoot":"","sources":["../../../src/messaging/slack/ChannelManager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG7D,qBAAa,cAAc;IACzB,OAAO,CAAC,GAAG,CAAiB;IAC5B,OAAO,CAAC,SAAS,CAAS;gBAEd,GAAG,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM;IAKlD;;;OAGG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAuBrE,qDAAqD;IAC/C,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKhF,sCAAsC;IAChC,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUtD,2BAA2B;IACrB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUxD,uCAAuC;IACjC,YAAY,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAS7C,wBAAwB;IAClB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAK9D;;;OAGG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAU/E,4DAA4D;YAC9C,iBAAiB;CAIhC"}

package/dist/messaging/slack/ChannelManager.js

@@ -0,0 +1,100 @@
+/**
+ * ChannelManager — Slack channel CRUD operations.
+ *
+ * Handles channel creation (with naming conventions), archiving,
+ * listing, and history retrieval. Uses conversations.* API methods.
+ */
+import { validateChannelName } from './sanitize.js';
+export class ChannelManager {
+    api;
+    agentName;
+    constructor(api, agentName) {
+        this.api = api;
+        this.agentName = agentName;
+    }
+    /**
+     * Create a channel. Returns the channel ID.
+     * Validates name format. Checks for existing channel first (idempotent).
+     */
+    async createChannel(name, isPrivate = false) {
+        if (!validateChannelName(name)) {
+            throw new Error(`Invalid channel name: "${name}". Must be lowercase alphanumeric with hyphens/underscores, max 80 chars.`);
+        }
+        // Check if channel already exists
+        const existing = await this.findChannelByName(name);
+        if (existing) {
+            // Unarchive if it was archived
+            if (existing.is_archived) {
+                await this.unarchiveChannel(existing.id);
+            }
+            return existing.id;
+        }
+        const result = await this.api.call('conversations.create', {
+            name,
+            is_private: isPrivate,
+        });
+        return result.channel.id;
+    }
+    /** Create a system channel with the agent prefix. */
+    async createSystemChannel(category, descriptor) {
+        const name = `${this.agentName}-${category}-${descriptor}`;
+        return this.createChannel(name);
+    }
+    /** Archive a channel (reversible). */
+    async archiveChannel(channelId) {
+        try {
+            await this.api.call('conversations.archive', { channel: channelId });
+        }
+        catch (err) {
+            // Ignore "already_archived" error
+            if (err.message?.includes('already_archived'))
+                return;
+            throw err;
+        }
+    }
+    /** Unarchive a channel. */
+    async unarchiveChannel(channelId) {
+        try {
+            await this.api.call('conversations.unarchive', { channel: channelId });
+        }
+        catch (err) {
+            // Ignore "not_archived" error
+            if (err.message?.includes('not_archived'))
+                return;
+            throw err;
+        }
+    }
+    /** List all channels the bot is in. */
+    async listChannels() {
+        const result = await this.api.call('conversations.list', {
+            types: 'public_channel,private_channel',
+            exclude_archived: false,
+            limit: 200,
+        });
+        return result.channels ?? [];
+    }
+    /** Get channel info. */
+    async getChannelInfo(channelId) {
+        const result = await this.api.call('conversations.info', { channel: channelId });
+        return result.channel;
+    }
+    /**
+     * Get channel message history (for cold start / cache miss only).
+     * Use ring buffer for hot-path reads.
+     */
+    async getChannelHistory(channelId, limit = 50) {
+        const result = await this.api.call('conversations.history', {
+            channel: channelId,
+            limit: Math.min(limit, 200),
+        });
+        const messages = result.messages ?? [];
+        // Slack returns newest-first; reverse to oldest-first
+        return messages.reverse();
+    }
+    /** Find a channel by name (returns first match or null). */
+    async findChannelByName(name) {
+        const channels = await this.listChannels();
+        return channels.find(c => c.name === name) ?? null;
+    }
+}
+//# sourceMappingURL=ChannelManager.js.map

package/dist/messaging/slack/ChannelManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChannelManager.js","sourceRoot":"","sources":["../../../src/messaging/slack/ChannelManager.ts"],"names":[],"mappings":"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"}

package/dist/messaging/slack/FileHandler.d.ts

@@ -0,0 +1,30 @@
+/**
+ * FileHandler — Slack file upload (v2 API) and download with security guards.
+ *
+ * Upload uses the three-step flow required for apps created after May 2024:
+ *   1. files.getUploadURLExternal → get upload URL
+ *   2. PUT file content to upload URL (validate hostname first)
+ *   3. files.completeUploadExternal → share to channel
+ *
+ * Download validates paths to prevent traversal attacks.
+ */
+import type { SlackApiClient } from './SlackApiClient.js';
+export declare class FileHandler {
+    private api;
+    private botToken;
+    private filesDir;
+    constructor(api: SlackApiClient, botToken: string, stateDir: string);
+    /**
+     * Upload a file to a Slack channel using the v2 three-step flow.
+     * files.upload is deprecated and unavailable for new apps.
+     */
+    uploadFile(channelId: string, filePath: string, title?: string): Promise<void>;
+    /**
+     * Download a file from Slack.
+     * Validates destPath to prevent path traversal — must resolve inside filesDir.
+     */
+    downloadFile(url: string, destPath: string): Promise<string>;
+    /** Get the base directory for downloaded files. */
+    get downloadDir(): string;
+}
+//# sourceMappingURL=FileHandler.d.ts.map

package/dist/messaging/slack/FileHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileHandler.d.ts","sourceRoot":"","sources":["../../../src/messaging/slack/FileHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D,qBAAa,WAAW;IACtB,OAAO,CAAC,GAAG,CAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAS;gBAEb,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAOnE;;;OAGG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmCpF;;;OAGG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BlE,mDAAmD;IACnD,IAAI,WAAW,IAAI,MAAM,CAExB;CACF"}

package/dist/messaging/slack/FileHandler.js

@@ -0,0 +1,87 @@
+/**
+ * FileHandler — Slack file upload (v2 API) and download with security guards.
+ *
+ * Upload uses the three-step flow required for apps created after May 2024:
+ *   1. files.getUploadURLExternal → get upload URL
+ *   2. PUT file content to upload URL (validate hostname first)
+ *   3. files.completeUploadExternal → share to channel
+ *
+ * Download validates paths to prevent traversal attacks.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { validateSlackHostname } from './sanitize.js';
+export class FileHandler {
+    api;
+    botToken;
+    filesDir;
+    constructor(api, botToken, stateDir) {
+        this.api = api;
+        this.botToken = botToken;
+        this.filesDir = path.join(stateDir, 'slack-files');
+        fs.mkdirSync(this.filesDir, { recursive: true });
+    }
+    /**
+     * Upload a file to a Slack channel using the v2 three-step flow.
+     * files.upload is deprecated and unavailable for new apps.
+     */
+    async uploadFile(channelId, filePath, title) {
+        const stats = await fs.promises.stat(filePath);
+        const fileName = path.basename(filePath);
+        // Step 1: Get upload URL
+        const urlResponse = await this.api.call('files.getUploadURLExternal', {
+            filename: fileName,
+            length: stats.size,
+        });
+        const uploadUrl = urlResponse.upload_url;
+        // SSRF prevention: validate hostname is *.slack.com
+        if (!validateSlackHostname(uploadUrl)) {
+            throw new Error(`[slack-file] Refusing upload: URL hostname is not *.slack.com: ${new URL(uploadUrl).hostname}`);
+        }
+        // Step 2: PUT file content
+        const fileContent = await fs.promises.readFile(filePath);
+        const putResponse = await fetch(uploadUrl, {
+            method: 'PUT',
+            body: fileContent,
+        });
+        if (!putResponse.ok) {
+            throw new Error(`[slack-file] Upload PUT failed: ${putResponse.status} ${putResponse.statusText}`);
+        }
+        // Step 3: Complete upload and share to channel
+        await this.api.call('files.completeUploadExternal', {
+            files: [{ id: urlResponse.file_id, title: title || fileName }],
+            channel_id: channelId,
+        });
+    }
+    /**
+     * Download a file from Slack.
+     * Validates destPath to prevent path traversal — must resolve inside filesDir.
+     */
+    async downloadFile(url, destPath) {
+        // Path traversal protection
+        const resolvedPath = path.resolve(this.filesDir, destPath);
+        if (!resolvedPath.startsWith(this.filesDir + path.sep) && resolvedPath !== this.filesDir) {
+            throw new Error(`[slack-file] Path traversal blocked: ${destPath} resolves outside ${this.filesDir}`);
+        }
+        // Ensure destination directory exists
+        const destDir = path.dirname(resolvedPath);
+        await fs.promises.mkdir(destDir, { recursive: true });
+        // Download with auth header
+        const response = await fetch(url, {
+            headers: {
+                'Authorization': `Bearer ${this.botToken}`,
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`[slack-file] Download failed: ${response.status} ${response.statusText}`);
+        }
+        const buffer = Buffer.from(await response.arrayBuffer());
+        await fs.promises.writeFile(resolvedPath, buffer);
+        return resolvedPath;
+    }
+    /** Get the base directory for downloaded files. */
+    get downloadDir() {
+        return this.filesDir;
+    }
+}
+//# sourceMappingURL=FileHandler.js.map

package/dist/messaging/slack/FileHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileHandler.js","sourceRoot":"","sources":["../../../src/messaging/slack/FileHandler.ts"],"names":[],"mappings":"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"}

package/dist/messaging/slack/RingBuffer.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Generic fixed-capacity ring buffer.
+ *
+ * When full, the oldest item is silently overwritten.
+ * Used for per-channel message history caching (capacity: 50).
+ */
+export declare class RingBuffer<T> {
+    private buffer;
+    private head;
+    private count;
+    readonly capacity: number;
+    constructor(capacity: number);
+    /** Add an item. Overwrites oldest if at capacity. */
+    push(item: T): void;
+    /** Return all items in insertion order (oldest first). */
+    toArray(): T[];
+    /** Number of items currently stored. */
+    get size(): number;
+    /** Remove all items. */
+    clear(): void;
+}
+//# sourceMappingURL=RingBuffer.d.ts.map

package/dist/messaging/slack/RingBuffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RingBuffer.d.ts","sourceRoot":"","sources":["../../../src/messaging/slack/RingBuffer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,UAAU,CAAC,CAAC;IACvB,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,KAAK,CAAK;IAClB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;IAM5B,qDAAqD;IACrD,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAMnB,0DAA0D;IAC1D,OAAO,IAAI,CAAC,EAAE;IAWd,wCAAwC;IACxC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,wBAAwB;IACxB,KAAK,IAAI,IAAI;CAKd"}

package/dist/messaging/slack/RingBuffer.js

@@ -0,0 +1,48 @@
+/**
+ * Generic fixed-capacity ring buffer.
+ *
+ * When full, the oldest item is silently overwritten.
+ * Used for per-channel message history caching (capacity: 50).
+ */
+export class RingBuffer {
+    buffer;
+    head = 0;
+    count = 0;
+    capacity;
+    constructor(capacity) {
+        if (capacity < 1)
+            throw new Error('RingBuffer capacity must be >= 1');
+        this.capacity = capacity;
+        this.buffer = new Array(capacity);
+    }
+    /** Add an item. Overwrites oldest if at capacity. */
+    push(item) {
+        this.buffer[this.head] = item;
+        this.head = (this.head + 1) % this.capacity;
+        if (this.count < this.capacity)
+            this.count++;
+    }
+    /** Return all items in insertion order (oldest first). */
+    toArray() {
+        if (this.count === 0)
+            return [];
+        const result = [];
+        const start = this.count < this.capacity ? 0 : this.head;
+        for (let i = 0; i < this.count; i++) {
+            const idx = (start + i) % this.capacity;
+            result.push(this.buffer[idx]);
+        }
+        return result;
+    }
+    /** Number of items currently stored. */
+    get size() {
+        return this.count;
+    }
+    /** Remove all items. */
+    clear() {
+        this.buffer = new Array(this.capacity);
+        this.head = 0;
+        this.count = 0;
+    }
+}
+//# sourceMappingURL=RingBuffer.js.map

package/dist/messaging/slack/RingBuffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RingBuffer.js","sourceRoot":"","sources":["../../../src/messaging/slack/RingBuffer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,UAAU;IACb,MAAM,CAAoB;IAC1B,IAAI,GAAG,CAAC,CAAC;IACT,KAAK,GAAG,CAAC,CAAC;IACT,QAAQ,CAAS;IAE1B,YAAY,QAAgB;QAC1B,IAAI,QAAQ,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACtE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED,qDAAqD;IACrD,IAAI,CAAC,IAAO;QACV,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC5C,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,KAAK,EAAE,CAAC;IAC/C,CAAC;IAED,0DAA0D;IAC1D,OAAO;QACL,IAAI,IAAI,CAAC,KAAK,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAChC,MAAM,MAAM,GAAQ,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QACzD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YACpC,MAAM,GAAG,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;YACxC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAM,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,wCAAwC;IACxC,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,wBAAwB;IACxB,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACd,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;IACjB,CAAC;CACF"}

package/dist/messaging/slack/SlackAdapter.d.ts

@@ -0,0 +1,283 @@
+/**
+ * SlackAdapter — Native Slack messaging adapter for Instar.
+ *
+ * Implements the MessagingAdapter interface using Socket Mode (WebSocket)
+ * for event intake and the Slack Web API for outbound messages.
+ *
+ * Key design decisions:
+ * - DIY app model (each user creates their own Slack app)
+ * - Socket Mode (no public URLs, no webhooks)
+ * - Zero external SDK (direct HTTP to Slack Web API)
+ * - authorizedUserIds is required and fail-closed
+ * - Ring buffer scoped to authorized users only
+ * - JSON-encoded context files (no delimiter-based injection)
+ *
+ * Required bot scopes (each event subscription requires its read scope):
+ *   app_mentions:read, channels:history, channels:join, channels:manage,
+ *   channels:read, chat:write, files:read, groups:history, im:history,
+ *   im:read, im:write, pins:write, reactions:read, reactions:write, users:read
+ */
+import type { MessagingAdapter, Message, OutgoingMessage } from '../../core/types.js';
+import { SlackApiClient } from './SlackApiClient.js';
+import { type LogEntry } from '../shared/MessageLogger.js';
+import type { SlackMessage, InteractionPayload, SlackWorkspaceMode, SlackRespondMode } from './types.js';
+export declare class SlackAdapter implements MessagingAdapter {
+    readonly platform = "slack";
+    private config;
+    private stateDir;
+    private apiClient;
+    private socketClient;
+    private channelManager;
+    private fileHandler;
+    private logger;
+    private workspaceMode;
+    private autoJoinChannels;
+    private respondMode;
+    private botUserId;
+    private messageHandler;
+    private started;
+    private authorizedUsers;
+    private channelHistory;
+    private pendingPrompts;
+    private seenMessageTs;
+    private seenMessageTsCleanupTimer;
+    private userCache;
+    private promptEvictionTimer;
+    private housekeepingTimer;
+    private logPurgeTimer;
+    private channelToSession;
+    private channelRegistryPath;
+    private channelResumeMap;
+    private channelResumeMapPath;
+    private pendingStalls;
+    private stallCheckTimer;
+    private pendingPromises;
+    /** Called when a prompt gate response is received */
+    onPromptResponse: ((channelId: string, promptId: string, value: string) => void) | null;
+    /** Called when a message is logged (for dual-write to SQLite) */
+    onMessageLogged: ((entry: LogEntry) => void) | null;
+    /** Called when a stall is detected */
+    onStallDetected: ((channelId: string, sessionName: string, messageText: string, injectedAt: number) => void) | null;
+    /** Called to interrupt a session (send Escape) */
+    onInterruptSession: ((sessionName: string) => Promise<boolean>) | null;
+    /** Called to restart a session */
+    onRestartSession: ((sessionName: string, channelId: string) => Promise<void>) | null;
+    /** Called to list running sessions */
+    onListSessions: (() => Array<{
+        name: string;
+        tmuxSession: string;
+        status: string;
+        alive: boolean;
+    }>) | null;
+    /** Called to check if a session is alive */
+    onIsSessionAlive: ((tmuxSession: string) => boolean) | null;
+    /** Called to transcribe a voice/audio file (via Whisper API) */
+    transcribeVoice: ((filePath: string) => Promise<string>) | null;
+    /** Called to handle standby commands (unstick, quiet, resume, restart) */
+    onStandbyCommand: ((channelId: string, command: string, userId: string) => Promise<boolean>) | null;
+    /** Called to get triage status for a channel's session */
+    onGetTriageStatus: ((channelId: string) => {
+        active: boolean;
+        classification?: string;
+        checkCount: number;
+        lastCheck?: string;
+    } | null) | null;
+    /** Called to classify why a session died */
+    onClassifySessionDeath: ((sessionName: string) => Promise<{
+        cause: string;
+        detail: string;
+    } | null>) | null;
+    /** Intelligence provider for LLM-gated stall confirmation */
+    intelligence: {
+        evaluate: (prompt: string, opts: {
+            maxTokens: number;
+            temperature: number;
+        }) => Promise<string>;
+    } | null;
+    constructor(config: Record<string, unknown>, stateDir: string);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send(message: OutgoingMessage): Promise<void | unknown>;
+    onMessage(handler: (message: Message) => Promise<void>): void;
+    resolveUser(channelIdentifier: string): Promise<string | null>;
+    /** Get the current workspace behavior config. */
+    getWorkspaceConfig(): {
+        mode: SlackWorkspaceMode;
+        autoJoinChannels: boolean;
+        respondMode: SlackRespondMode;
+    };
+    /** Get the bot's own Slack user ID (for distinguishing bot vs user messages). */
+    getBotUserId(): string | null;
+    /** Check if a user is authorized. */
+    isAuthorized(userId: string): boolean;
+    /** Send a message to a specific channel. */
+    sendToChannel(channelId: string, text: string, options?: {
+        thread_ts?: string;
+    }): Promise<string>;
+    /** Add a reaction (fire-and-forget). */
+    addReaction(channelId: string, timestamp: string, emoji: string): void;
+    /** Remove a reaction (fire-and-forget). */
+    removeReaction(channelId: string, timestamp: string, emoji: string): void;
+    /** Update an existing message. */
+    updateMessage(channelId: string, timestamp: string, text: string): Promise<void>;
+    /** Pin a message. */
+    pinMessage(channelId: string, timestamp: string): Promise<void>;
+    /** Send an ephemeral message (visible only to one user). */
+    postEphemeral(channelId: string, userId: string, text: string): Promise<void>;
+    /** Send a message with Block Kit blocks. */
+    sendBlocks(channelId: string, blocks: unknown[], text?: string): Promise<string>;
+    /** Get cached channel messages from ring buffer. */
+    getChannelMessages(channelId: string, limit?: number): SlackMessage[];
+    /** Get user info (cached for 5 minutes). */
+    getUserInfo(userId: string): Promise<{
+        id: string;
+        name: string;
+    }>;
+    /** Create a channel. */
+    createChannel(name: string, isPrivate?: boolean): Promise<string>;
+    /** Archive a channel. */
+    archiveChannel(channelId: string): Promise<void>;
+    /** Upload a file. */
+    uploadFile(channelId: string, filePath: string, title?: string): Promise<void>;
+    /** Download a file. */
+    downloadFile(url: string, destPath: string): Promise<string>;
+    /** Get the underlying API client (for routes). */
+    get api(): SlackApiClient;
+    /** Register a channel → session binding. Persisted to disk. */
+    registerChannelSession(channelId: string, sessionName: string, channelName?: string): void;
+    /** Look up which session is bound to a channel. */
+    getSessionForChannel(channelId: string): string | null;
+    /** Look up which channel is bound to a session. */
+    getChannelForSession(sessionName: string): string | null;
+    /** Remove a channel → session binding. */
+    unregisterChannel(channelId: string): void;
+    /** Get all channel → session mappings. */
+    getChannelRegistry(): Record<string, {
+        sessionName: string;
+        channelName?: string;
+    }>;
+    /** Save a session UUID for resume when a channel goes idle. */
+    saveChannelResume(channelId: string, uuid: string, sessionName: string): void;
+    /** Get the resume UUID for a channel (returns null if none or expired). */
+    getChannelResume(channelId: string): {
+        uuid: string;
+        sessionName: string;
+    } | null;
+    /** Remove a resume entry (consumed after resume). */
+    removeChannelResume(channelId: string): void;
+    /** Track an injected message for stall detection. */
+    trackMessageInjection(channelId: string, sessionName: string, text: string): void;
+    /** Clear stall tracking for a channel (agent responded). */
+    clearStallTracking(channelId: string): void;
+    /** Start periodic stall checking (stalls + promise expiry, LLM-gated). */
+    startStallDetection(timeoutMs?: number, promiseTimeoutMs?: number): void;
+    /** Get pending stall count. */
+    getPendingStallCount(): number;
+    /** Track a promise from the agent ("give me a minute" etc.) */
+    trackPromise(channelId: string, sessionName: string, text: string): void;
+    /** Clear promise tracking for a channel. */
+    clearPromiseTracking(channelId: string): void;
+    private _isPromiseMessage;
+    private _isFollowThroughMessage;
+    /** LLM-gated stall alert confirmation. Returns true if alert should be sent. Fail-open. */
+    confirmStallAlert(context: {
+        type: 'stall' | 'promise-expired';
+        sessionName: string;
+        messageText: string;
+        minutesElapsed: number;
+        sessionAlive: boolean;
+    }): Promise<boolean>;
+    /** Get adapter status. */
+    getStatus(): {
+        started: boolean;
+        uptime: number | null;
+        pendingStalls: number;
+        pendingPromises: number;
+        channelMappings: number;
+    };
+    private _loadChannelRegistry;
+    private _saveChannelRegistry;
+    private _loadChannelResumeMap;
+    private _saveChannelResumeMap;
+    /** Inject a simulated message for testing. */
+    _testInjectMessage(event: Record<string, unknown>): Promise<void>;
+    /** Inject a simulated interaction for testing. */
+    _testInjectInteraction(payload: InteractionPayload): Promise<void>;
+    private _handleEvent;
+    private _handleMessage;
+    private _handleInteraction;
+    private _handleFileShared;
+    /** Register a pending prompt (for interaction validation). */
+    registerPendingPrompt(messageTs: string, promptId: string, channelId: string, sessionName?: string): void;
+    private _startPromptEviction;
+    /**
+     * Relay a prompt to the user via Block Kit interactive message.
+     * Registers the prompt for validation against spoofed button presses.
+     */
+    relayPrompt(channelId: string, promptId: string, question: string, options: Array<{
+        label: string;
+        value: string;
+        primary?: boolean;
+    }>): Promise<void>;
+    /** Search the JSONL message log. */
+    searchLog(params: {
+        query?: string;
+        channelId?: string;
+        since?: Date;
+        limit?: number;
+    }): LogEntry[];
+    /** Get message log statistics. */
+    getLogStats(): {
+        totalMessages: number;
+        logSizeBytes: number;
+        logPath: string;
+    };
+    /**
+     * Auto-archive channels idle for more than AUTO_ARCHIVE_DAYS.
+     * Runs periodically. Only archives session channels (sess- prefix).
+     */
+    private _archiveIdleChannels;
+    private _startHousekeeping;
+    /** Purge log entries older than logRetentionDays. */
+    private _purgeOldLogs;
+    private _startLogPurge;
+    /**
+     * Broadcast the tunnel URL to the dashboard channel.
+     * Called by server.ts when tunnel is established.
+     */
+    /** Last broadcast dashboard URL and message timestamp (for update-in-place) */
+    private lastDashboardUrl;
+    private lastDashboardMessageTs;
+    broadcastDashboardUrl(tunnelUrl: string): Promise<void>;
+    /**
+     * Get count of unanswered user messages in a channel.
+     * A message is "unanswered" if it's from a user and no agent reply follows.
+     */
+    getUnansweredCount(channelId: string): number;
+    /** Handle slash commands from Slack messages. Returns true if handled. */
+    private _handleSlashCommand;
+    /**
+     * Auto-join all public channels in the workspace.
+     * Only called in dedicated mode or when autoJoinChannels is true.
+     * Runs asynchronously — doesn't block startup.
+     */
+    /**
+     * Backfill ring buffers with recent channel history from Slack's API.
+     * This runs on startup so that sessions spawned after a server restart
+     * have conversation context instead of starting from scratch.
+     */
+    private _backfillChannelHistory;
+    private _autoJoinAllChannels;
+    /**
+     * Check if a message mentions the bot (via @mention).
+     * Slack encodes mentions as <@U12345> in message text.
+     */
+    /**
+     * Validate that a downloaded file is a processable image.
+     * Checks magic bytes and file size to avoid Claude API "Could not process image" errors.
+     */
+    private _validateImageFile;
+    private _isBotMentioned;
+    private _chunkText;
+}
+//# sourceMappingURL=SlackAdapter.d.ts.map