instar 0.24.13 → 0.24.14

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,136 @@
+/**
+ * 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)
+ */
+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 } 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 messageHandler;
+    private started;
+    private authorizedUsers;
+    private channelHistory;
+    private pendingPrompts;
+    private userCache;
+    private promptEvictionTimer;
+    private housekeepingTimer;
+    private logPurgeTimer;
+    /** 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;
+    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>;
+    /** 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;
+    /** 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): 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.
+     */
+    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;
+    private _chunkText;
+}
+//# sourceMappingURL=SlackAdapter.d.ts.map

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

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