@jitsusama/agentic-harness.core 0.1.0

package/dist/slack/api/client.js

@@ -0,0 +1,272 @@
+/**
+ * Slack Web API HTTP client.
+ *
+ * Thin wrapper around fetch that handles authentication,
+ * rate limiting with exponential backoff, and response
+ * validation. No external dependencies.
+ */
+const SLACK_API_BASE = "https://slack.com/api";
+/**
+ * Maximum retries for non-rate-limit errors (network
+ * failures, unexpected HTTP status codes).
+ */
+const MAX_ERROR_RETRIES = 3;
+/**
+ * Maximum rate limit retries before giving up. Rate limits
+ * are transient by definition (the API tells us to wait and
+ * retry), so this budget is much higher than error retries.
+ */
+const MAX_RATE_LIMIT_RETRIES = 10;
+/** Initial backoff delay in milliseconds. */
+const INITIAL_BACKOFF_MS = 1000;
+/**
+ * Thrown when a Slack API call exhausts its rate limit retry
+ * budget. Callers can catch this specifically to implement
+ * backpressure (e.g. reducing concurrency) before retrying.
+ */
+export class RateLimitError extends Error {
+    method;
+    hitCount;
+    constructor(
+    /** The Slack API method that was rate limited. */
+    method, 
+    /** How many rate limit responses were received. */
+    hitCount) {
+        super(`Slack API rate limited ${hitCount} times for ${method}`);
+        this.method = method;
+        this.hitCount = hitCount;
+        this.name = "RateLimitError";
+    }
+}
+/**
+ * Thrown when Slack returns `{ ok: false, error: "..." }`.
+ *
+ * Preserves the API error code so callers can distinguish
+ * permanent failures (channel_not_found, not_in_channel)
+ * from transient ones without parsing error message strings.
+ */
+export class SlackApiError extends Error {
+    errorCode;
+    constructor(
+    /** The Slack API error code (e.g. "not_in_channel"). */
+    errorCode, message) {
+        super(message);
+        this.errorCode = errorCode;
+        this.name = "SlackApiError";
+    }
+}
+/**
+ * Authenticated Slack API client.
+ *
+ * Supports two auth modes:
+ *   - OAuth user tokens (xoxp-): token sent in body, no cookie
+ *   - Browser session tokens (xoxc-): token in body + cookie in header
+ */
+/**
+ * The bytes of a buffer, in a form fetch will take.
+ *
+ * A Node Buffer is not one of the byte-array types the fetch body
+ * accepts, and a plain view over its memory is not either: a typed
+ * array now carries the kind of buffer it sits on, and a Buffer's is
+ * only known to be array-buffer-like. The common case, a buffer
+ * backed by an ordinary ArrayBuffer, is passed without copying; the
+ * shared-memory case, which an uploaded file is never on, copies
+ * rather than refuses.
+ */
+function uploadable(body) {
+    const backing = body.buffer;
+    return backing instanceof ArrayBuffer
+        ? new Uint8Array(backing, body.byteOffset, body.byteLength)
+        : new Uint8Array(body);
+}
+export class SlackClient {
+    token;
+    cookie;
+    constructor(token, cookie) {
+        this.token = token;
+        this.cookie = cookie;
+    }
+    /**
+     * Call a Slack Web API method.
+     *
+     * Sends a POST with form-encoded body containing the token
+     * and any additional parameters. For browser session tokens,
+     * includes the session cookie in the request header. Retries
+     * on rate limits with exponential backoff.
+     */
+    async call(method, params = {}, signal) {
+        const body = new URLSearchParams();
+        body.set("token", this.token);
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined) {
+                body.set(key, String(value));
+            }
+        }
+        const headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+        };
+        if (this.cookie) {
+            headers.Cookie = `d=${this.cookie}`;
+        }
+        let lastError = null;
+        let rateLimitHits = 0;
+        for (let attempt = 0; attempt < MAX_ERROR_RETRIES; attempt++) {
+            if (signal?.aborted) {
+                throw new Error("Request aborted");
+            }
+            const response = await fetch(`${SLACK_API_BASE}/${method}`, {
+                method: "POST",
+                headers,
+                body: body.toString(),
+                signal,
+            });
+            if (response.status === 429) {
+                if (++rateLimitHits > MAX_RATE_LIMIT_RETRIES) {
+                    throw new RateLimitError(method, rateLimitHits);
+                }
+                const retryAfter = Number(response.headers.get("Retry-After") || "1");
+                await sleep(retryAfter * 1000);
+                // Don't count rate limits against the error retry
+                // budget, since the API is explicitly telling us to wait.
+                attempt--;
+                continue;
+            }
+            if (!response.ok) {
+                throw new Error(`Slack API HTTP ${response.status}: ${response.statusText}`);
+            }
+            const data = (await response.json());
+            if (!data.ok) {
+                if (data.error === "ratelimited") {
+                    if (++rateLimitHits > MAX_RATE_LIMIT_RETRIES) {
+                        throw new RateLimitError(method, rateLimitHits);
+                    }
+                    const backoff = INITIAL_BACKOFF_MS * 2 ** rateLimitHits;
+                    await sleep(backoff);
+                    attempt--;
+                    continue;
+                }
+                lastError = new SlackApiError(data.error ?? "unknown", describeError(data.error));
+                throw lastError;
+            }
+            return data;
+        }
+        throw lastError ?? new Error("Slack API call failed after retries");
+    }
+    /**
+     * Paginate through a cursor-based Slack API method.
+     *
+     * Calls the method repeatedly, following next_cursor until
+     * all pages are collected or the limit is reached.
+     */
+    async paginate(method, params, extract, limit, signal) {
+        const results = [];
+        let cursor;
+        do {
+            const response = await this.call(method, { ...params, cursor }, signal);
+            const items = extract(response);
+            results.push(...items);
+            cursor = response.response_metadata?.next_cursor || undefined;
+            if (limit && results.length >= limit) {
+                return results.slice(0, limit);
+            }
+        } while (cursor);
+        return results;
+    }
+    /**
+     * Download a file from an authenticated Slack URL.
+     *
+     * Used to fetch files from `url_private` URLs on Slack
+     * messages. Authenticates with the Bearer token (or session
+     * cookie for browser tokens). Returns the raw bytes and
+     * the content type reported by the server.
+     *
+     * When `maxBytes` is set, the Content-Length header is
+     * checked before reading the body to avoid buffering
+     * oversized files.
+     */
+    async download(url, opts) {
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+        };
+        if (this.cookie) {
+            headers.Cookie = `d=${this.cookie}`;
+        }
+        const response = await fetch(url, {
+            method: "GET",
+            headers,
+            signal: opts?.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`File download failed: HTTP ${response.status} ${response.statusText}`);
+        }
+        // Reject oversized files before reading the body when
+        // the server reports Content-Length.
+        if (opts?.maxBytes) {
+            const contentLength = response.headers.get("content-length");
+            if (contentLength !== null && Number(contentLength) > opts.maxBytes) {
+                // Consume the body to release the connection.
+                await response.body?.cancel();
+                throw new Error(`File too large: ${contentLength} bytes exceeds ${opts.maxBytes} byte limit`);
+            }
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        // Belt-and-suspenders: reject if the actual body exceeds
+        // the limit (covers missing or dishonest Content-Length).
+        if (opts?.maxBytes && arrayBuffer.byteLength > opts.maxBytes) {
+            throw new Error(`File too large: ${arrayBuffer.byteLength} bytes exceeds ${opts.maxBytes} byte limit`);
+        }
+        const contentType = response.headers.get("content-type") ?? "application/octet-stream";
+        return { buffer: Buffer.from(arrayBuffer), contentType };
+    }
+    /**
+     * Upload raw bytes to an external upload URL.
+     *
+     * Used by the file upload flow after obtaining a URL from
+     * files.getUploadURLExternal. Includes the session cookie
+     * when using browser tokens so auth stays encapsulated.
+     */
+    async upload(url, body, signal) {
+        // See `uploadable`: a Node Buffer is not one of the byte-array
+        // types fetch accepts.
+        const headers = {
+            "Content-Type": "application/octet-stream",
+        };
+        if (this.cookie) {
+            headers.Cookie = `d=${this.cookie}`;
+        }
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: uploadable(body),
+            signal,
+        });
+        if (!response.ok) {
+            throw new Error(`File upload failed: HTTP ${response.status} ${response.statusText}`);
+        }
+    }
+}
+/** Describe a Slack API error with actionable guidance. */
+function describeError(error) {
+    if (!error)
+        return "Unknown Slack API error";
+    const hints = {
+        invalid_auth: "Invalid credentials. Your token may have been revoked.\n" +
+            "Run /slack-auth to re-authenticate.",
+        token_revoked: "Token has been revoked.\n" + "Run /slack-auth to get a new token.",
+        not_authed: "No authentication provided.\n" + "Run /slack-auth to authenticate.",
+        account_inactive: "This Slack account has been deactivated or the workspace was deleted.",
+        missing_scope: "Token lacks the required API scope for this operation.\n" +
+            "Run /slack-auth to re-authenticate with the correct scopes.",
+        channel_not_found: "Channel not found. Check the channel name or ID.",
+        user_not_found: "User not found. Check the username or ID.",
+        thread_not_found: "The timestamp doesn't match a thread parent. " +
+            "Use the ts values from list_messages or search_messages results.",
+    };
+    const hint = hints[error];
+    return hint
+        ? `Slack API error: ${error}\n${hint}`
+        : `Slack API error: ${error}`;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/slack/api/files.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Slack file upload API using the V2 external upload flow.
+ *
+ * Implements the 3-step upload process:
+ * 1. Get an upload URL via files.getUploadURLExternal
+ * 2. POST file bytes to that URL
+ * 3. Finalize with files.completeUploadExternal
+ */
+import type { SlackClient } from "./client.js";
+/** Result from completing a file upload. */
+export interface UploadResult {
+    ok: boolean;
+    files: Array<{
+        id: string;
+        title?: string;
+    }>;
+    /**
+     * Timestamp of the message created when sharing to a channel.
+     * Only present when channelId was provided.
+     */
+    ts?: string;
+}
+/** Options for sharing uploaded files. */
+export interface UploadOptions {
+    /** Channel ID to share the files in. */
+    channelId?: string;
+    /** Thread timestamp to upload as a reply. */
+    threadTs?: string;
+    /** Message text introducing the files. */
+    initialComment?: string;
+}
+/**
+ * Upload one or more local files to Slack.
+ *
+ * Each file goes through the external upload flow
+ * individually, then all are finalized in a single
+ * completeUploadExternal call to share them together.
+ */
+export declare function uploadFiles(client: SlackClient, filePaths: string[], opts?: UploadOptions, signal?: AbortSignal): Promise<UploadResult>;
+/** A downloaded file ready to be returned as model content. */
+export type DownloadedFile = {
+    kind: "image";
+    data: string;
+    mimeType: string;
+    name: string;
+} | {
+    kind: "text";
+    text: string;
+    name: string;
+};
+/**
+ * Check whether a MIME type is a supported image format.
+ *
+ * Used to decide whether a file attachment should be
+ * downloaded and sent to the model as image content.
+ */
+export declare function isImageMimeType(mimeType: string | undefined): boolean;
+/**
+ * Check whether a MIME type is readable as text.
+ *
+ * Matches all `text/*` types and a curated set of
+ * `application/*` types that contain human-readable content.
+ */
+export declare function isTextMimeType(mimeType: string | undefined): boolean;
+/** Options for downloading files from Slack messages. */
+export interface FileDownloadOptions {
+    signal?: AbortSignal;
+    /** Maximum number of files to download (default: 10). */
+    maxFiles?: number;
+    /** Maximum size per image file in bytes (default: 5 MB). */
+    maxImageBytes?: number;
+    /** Maximum size per text file in bytes (default: 128 KB). */
+    maxTextBytes?: number;
+}
+/**
+ * Download displayable files from Slack messages.
+ *
+ * Filters files to supported image and text types, downloads
+ * them via the authenticated client, and returns content
+ * ready for model consumption. Images are base64-encoded;
+ * text files are decoded as UTF-8. Skips files that are too
+ * large or fail to download.
+ */
+export declare function downloadFiles(client: SlackClient, files: Array<{
+    name: string;
+    mimetype?: string;
+    url?: string;
+}>, opts?: FileDownloadOptions): Promise<DownloadedFile[]>;
+/**
+ * Get the byte size of a local file.
+ *
+ * Used by callers to display file sizes in confirmation
+ * gates before uploading.
+ */
+export declare function getFileSize(filePath: string): Promise<number>;

package/dist/slack/api/files.js

@@ -0,0 +1,223 @@
+/**
+ * Slack file upload API using the V2 external upload flow.
+ *
+ * Implements the 3-step upload process:
+ * 1. Get an upload URL via files.getUploadURLExternal
+ * 2. POST file bytes to that URL
+ * 3. Finalize with files.completeUploadExternal
+ */
+import { readFile, stat } from "node:fs/promises";
+import { basename } from "node:path";
+/**
+ * Upload one or more local files to Slack.
+ *
+ * Each file goes through the external upload flow
+ * individually, then all are finalized in a single
+ * completeUploadExternal call to share them together.
+ */
+export async function uploadFiles(client, filePaths, opts = {}, signal) {
+    if (filePaths.length === 0) {
+        throw new Error("No file paths provided.");
+    }
+    const fileIds = [];
+    for (const filePath of filePaths) {
+        const fileId = await uploadSingleFile(client, filePath, signal);
+        fileIds.push({ id: fileId });
+    }
+    return completeUpload(client, fileIds, opts, signal);
+}
+/**
+ * Upload a single file and return its Slack file ID.
+ *
+ * Gets an upload URL, reads the file from disk, then
+ * POSTs the bytes to Slack's upload endpoint.
+ */
+async function uploadSingleFile(client, filePath, signal) {
+    const fileBytes = await readFile(filePath);
+    const filename = basename(filePath);
+    const urlResponse = await client.call("files.getUploadURLExternal", { filename, length: fileBytes.length }, signal);
+    await client.upload(urlResponse.upload_url, fileBytes, signal);
+    return urlResponse.file_id;
+}
+/**
+ * Finalize uploaded files and optionally share them.
+ *
+ * Calls files.completeUploadExternal with the collected
+ * file IDs and any sharing parameters (channel, thread,
+ * initial comment).
+ */
+async function completeUpload(client, fileIds, opts, signal) {
+    const params = {
+        files: JSON.stringify(fileIds),
+        channel_id: opts.channelId,
+        thread_ts: opts.threadTs,
+        initial_comment: opts.initialComment,
+    };
+    const response = await client.call("files.completeUploadExternal", params, signal);
+    const result = {
+        ok: true,
+        files: response.files ?? [],
+    };
+    // completeUploadExternal doesn't return the message ts.
+    // When sharing to a channel, recover it from the file's
+    // share metadata via files.info. This is deterministic
+    // (keyed on the file we just uploaded) so there's no
+    // race with other messages landing in the channel.
+    if (opts.channelId && result.files.length > 0) {
+        result.ts = await fetchShareTs(client, result.files[0].id, opts.channelId, signal);
+    }
+    return result;
+}
+/** Maximum attempts when polling for share metadata. */
+const SHARE_POLL_MAX_ATTEMPTS = 5;
+/** Initial delay between share metadata polls (milliseconds). */
+const SHARE_POLL_INITIAL_DELAY_MS = 500;
+/**
+ * Fetch the message timestamp from a file's share metadata.
+ *
+ * Uses files.info to look up the share entry for the given
+ * channel. This is deterministic: we're reading metadata for
+ * the exact file we just uploaded, not guessing based on
+ * channel history.
+ *
+ * Slack processes file shares asynchronously, so the share
+ * entry may not exist immediately after completeUploadExternal
+ * returns. We poll with exponential backoff until it appears
+ * or the attempt budget is exhausted.
+ */
+async function fetchShareTs(client, fileId, channelId, signal) {
+    for (let attempt = 0; attempt < SHARE_POLL_MAX_ATTEMPTS; attempt++) {
+        const response = await client.call("files.info", { file: fileId }, signal);
+        const shares = response.file?.shares;
+        const entries = shares?.public?.[channelId] ?? shares?.private?.[channelId];
+        if (entries?.[0]?.ts)
+            return entries[0].ts;
+        // Share metadata isn't ready yet. Wait before retrying.
+        const delay = SHARE_POLL_INITIAL_DELAY_MS * 2 ** attempt;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+    return undefined;
+}
+/** MIME types recognised as images that the model can interpret. */
+const IMAGE_MIME_TYPES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+]);
+/**
+ * Application MIME types that contain readable text.
+ *
+ * These aren't under `text/` but the model can interpret
+ * their content when decoded as UTF-8.
+ */
+const TEXT_APPLICATION_TYPES = new Set([
+    "application/json",
+    "application/xml",
+    "application/javascript",
+    "application/typescript",
+    "application/x-yaml",
+    "application/x-sh",
+    "application/sql",
+    "application/graphql",
+    "application/toml",
+]);
+/** Default maximum size for image files (5 MB). */
+const DEFAULT_MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+/** Default maximum size for text files (128 KB). */
+const DEFAULT_MAX_TEXT_BYTES = 128 * 1024;
+/** Default maximum number of files to download per request. */
+const DEFAULT_MAX_FILES = 10;
+/**
+ * Check whether a MIME type is a supported image format.
+ *
+ * Used to decide whether a file attachment should be
+ * downloaded and sent to the model as image content.
+ */
+export function isImageMimeType(mimeType) {
+    if (!mimeType)
+        return false;
+    const base = baseMimeType(mimeType);
+    return IMAGE_MIME_TYPES.has(base);
+}
+/**
+ * Check whether a MIME type is readable as text.
+ *
+ * Matches all `text/*` types and a curated set of
+ * `application/*` types that contain human-readable content.
+ */
+export function isTextMimeType(mimeType) {
+    if (!mimeType)
+        return false;
+    const base = baseMimeType(mimeType);
+    return base.startsWith("text/") || TEXT_APPLICATION_TYPES.has(base);
+}
+/** Strip parameters from a MIME type (e.g. "text/plain; charset=utf-8" → "text/plain"). */
+function baseMimeType(mimeType) {
+    return mimeType.split(";")[0].trim().toLowerCase();
+}
+/**
+ * Download displayable files from Slack messages.
+ *
+ * Filters files to supported image and text types, downloads
+ * them via the authenticated client, and returns content
+ * ready for model consumption. Images are base64-encoded;
+ * text files are decoded as UTF-8. Skips files that are too
+ * large or fail to download.
+ */
+export async function downloadFiles(client, files, opts) {
+    const maxFiles = opts?.maxFiles ?? DEFAULT_MAX_FILES;
+    const maxImageBytes = opts?.maxImageBytes ?? DEFAULT_MAX_IMAGE_BYTES;
+    const maxTextBytes = opts?.maxTextBytes ?? DEFAULT_MAX_TEXT_BYTES;
+    const results = [];
+    for (const file of files) {
+        if (results.length >= maxFiles)
+            break;
+        if (!file.url)
+            continue;
+        const isImage = isImageMimeType(file.mimetype);
+        const isText = isTextMimeType(file.mimetype);
+        if (!isImage && !isText)
+            continue;
+        const maxBytes = isImage ? maxImageBytes : maxTextBytes;
+        try {
+            const { buffer, contentType } = await client.download(file.url, {
+                signal: opts?.signal,
+                maxBytes,
+            });
+            if (isImage) {
+                const mimeType = isImageMimeType(contentType)
+                    ? baseMimeType(contentType)
+                    : (file.mimetype ?? "image/png");
+                results.push({
+                    kind: "image",
+                    data: buffer.toString("base64"),
+                    mimeType,
+                    name: file.name,
+                });
+            }
+            else {
+                results.push({
+                    kind: "text",
+                    text: buffer.toString("utf-8"),
+                    name: file.name,
+                });
+            }
+        }
+        catch {
+            // Download failed; skip this file silently.
+            // The text renderer still shows the filename.
+        }
+    }
+    return results;
+}
+/**
+ * Get the byte size of a local file.
+ *
+ * Used by callers to display file sizes in confirmation
+ * gates before uploading.
+ */
+export async function getFileSize(filePath) {
+    const info = await stat(filePath);
+    return info.size;
+}

package/dist/slack/api/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Slack API client and service functions.
+ */
+export { getChannelInfo } from "./channels.js";
+export { RateLimitError, SlackApiError, SlackClient } from "./client.js";
+export { type DownloadedFile, downloadFiles, type FileDownloadOptions, getFileSize, isImageMimeType, isTextMimeType, type UploadOptions, type UploadResult, uploadFiles, } from "./files.js";
+export { editMessage, formatMentions, type GetMessageOptions, type GetThreadOptions, getMessage, getThread, type ListMessagesOptions, listMessages, replyToThread, type SendResult, sendMessage, } from "./messages.js";
+export { addReaction, getReactions, listReactions, type MessageReactions, type ReactedMessage, removeReaction, } from "./reactions.js";
+export { resolveMessages } from "./resolve-messages.js";
+export { type FileSearchResult, type MessageSearchResult, type SearchFilesOptions, type SearchMessagesOptions, type SearchPageInfo, type SlackFileResult, searchFiles, searchMessages, } from "./search.js";
+export { getUserInfo } from "./users.js";

package/dist/slack/api/index.js

@@ -0,0 +1,11 @@
+/**
+ * Slack API client and service functions.
+ */
+export { getChannelInfo } from "./channels.js";
+export { RateLimitError, SlackApiError, SlackClient } from "./client.js";
+export { downloadFiles, getFileSize, isImageMimeType, isTextMimeType, uploadFiles, } from "./files.js";
+export { editMessage, formatMentions, getMessage, getThread, listMessages, replyToThread, sendMessage, } from "./messages.js";
+export { addReaction, getReactions, listReactions, removeReaction, } from "./reactions.js";
+export { resolveMessages } from "./resolve-messages.js";
+export { searchFiles, searchMessages, } from "./search.js";
+export { getUserInfo } from "./users.js";