@jitsusama/agentic-harness.core 0.1.0

package/dist/slack/api/resolve-messages.js

@@ -0,0 +1,93 @@
+/**
+ * Unified message resolution: users, conversations and
+ * channel mentions in one call.
+ *
+ * Composes resolveUsersInMessages, resolveConversationsInMessages
+ * and refreshDmNames into a single entry point. Also resolves
+ * channel IDs that only appear as text mentions (<#C123>),
+ * which the per-message conversation resolver doesn't cover.
+ *
+ * Consumers call this after fetching messages and before
+ * rendering. API functions (getMessage, getThread, etc.) do
+ * free cache warming but no resolution, so this function is
+ * the explicit resolution step.
+ */
+import { lookupName } from "../resolvers/cache.js";
+import { cacheChannelName } from "../resolvers/conversation.js";
+import { fetchConversation, getCachedConversation, } from "../resolvers/conversation-cache.js";
+import { refreshDmNames, resolveConversationsInMessages, } from "./resolve-conversations.js";
+import { resolveUsersInMessages } from "./resolve-users.js";
+/** Cache filename for channel name ↔ ID lookups. */
+const CHANNEL_CACHE_FILE = "channels.json";
+/** Pattern matching channel mentions in Slack message text. */
+const CHANNEL_MENTION_PATTERN = /<#([CDG][A-Z0-9]+)(?:\|[^>]*)?>/g;
+/** Concurrency limit for conversations.info calls. */
+const BATCH_SIZE = 20;
+/**
+ * Resolve all unknown entities in a list of messages.
+ *
+ * Handles three concerns in order:
+ * 1. User IDs → display names (msg.user + <@U123> in text)
+ * 2. Conversation IDs → metadata (msg.conversation.id)
+ * 3. Channel mentions in text → cache warming (<#C123>)
+ * 4. DM display name refresh (after user names are known)
+ *
+ * Mutates messages in place. Silently skips entities that
+ * fail to resolve (deleted users, inaccessible channels).
+ */
+export async function resolveMessages(client, messages, signal) {
+    // Users first, since DM display names depend on resolved user handles.
+    await resolveUsersInMessages(client, messages, signal);
+    await resolveConversationsInMessages(client, messages, signal);
+    // Channel mentions in text: <#C123> patterns that aren't
+    // the message's own conversation. resolveConversationsInMessages
+    // only resolves msg.conversation.id.
+    await resolveChannelMentionsInText(client, messages, signal);
+    // Refresh DM names last, now that user handles are resolved.
+    refreshDmNames(messages);
+}
+/**
+ * Resolve channel IDs that appear only as text mentions.
+ *
+ * Scans all message text for <#C123> patterns, deduplicates,
+ * and calls conversations.info for any that aren't in the
+ * channel cache. This warms the file cache so formatSlackText
+ * can resolve them without API calls.
+ */
+async function resolveChannelMentionsInText(client, messages, signal) {
+    const unknownIds = new Set();
+    for (const msg of messages) {
+        if (!msg.text)
+            continue;
+        for (const match of msg.text.matchAll(CHANNEL_MENTION_PATTERN)) {
+            const channelId = match[1];
+            // Skip if already in the file cache (survives across sessions).
+            if (lookupName(CHANNEL_CACHE_FILE, channelId))
+                continue;
+            // Skip if already in the session cache.
+            if (getCachedConversation(channelId))
+                continue;
+            unknownIds.add(channelId);
+        }
+    }
+    if (unknownIds.size === 0)
+        return;
+    const ids = [...unknownIds];
+    for (let i = 0; i < ids.length; i += BATCH_SIZE) {
+        if (signal?.aborted)
+            return;
+        const batch = ids.slice(i, i + BATCH_SIZE);
+        await Promise.all(batch.map(async (id) => {
+            try {
+                const conversation = await fetchConversation(client, id, signal);
+                if (conversation.kind === "channel" && conversation.name) {
+                    cacheChannelName(conversation.name, conversation.id);
+                }
+            }
+            catch {
+                // Channel not found or inaccessible, so skip:
+                // formatSlackText falls back to the raw ID.
+            }
+        }));
+    }
+}

package/dist/slack/api/resolve-users.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Batch user ID resolution for messages.
+ *
+ * After fetching messages from any API (search, history,
+ * replies), this module resolves all user IDs to display
+ * names and updates the user cache. This means the renderers
+ * and collapsed previews always show @handles instead of
+ * raw IDs like U08ME9KASG7.
+ *
+ * Resolves both message authors (msg.user) and user mentions
+ * in message text (<@U123> / <@W123> patterns).
+ */
+import type { SlackMessage } from "../types.js";
+import type { SlackClient } from "./client.js";
+/**
+ * Resolve all unknown user IDs in a list of messages.
+ *
+ * Collects unique user IDs from message authors and from
+ * user mentions in message text. Calls users.info for each
+ * unknown ID and caches the results. After this call,
+ * displayNameForId() will return handles for all users
+ * referenced in the messages.
+ *
+ * Silently skips users that fail to resolve (deleted accounts,
+ * bots without profiles).
+ */
+export declare function resolveUsersInMessages(client: SlackClient, messages: SlackMessage[], signal?: AbortSignal): Promise<void>;

package/dist/slack/api/resolve-users.js

@@ -0,0 +1,73 @@
+/**
+ * Batch user ID resolution for messages.
+ *
+ * After fetching messages from any API (search, history,
+ * replies), this module resolves all user IDs to display
+ * names and updates the user cache. This means the renderers
+ * and collapsed previews always show @handles instead of
+ * raw IDs like U08ME9KASG7.
+ *
+ * Resolves both message authors (msg.user) and user mentions
+ * in message text (<@U123> / <@W123> patterns).
+ */
+import { lookupName } from "../resolvers/cache.js";
+import { cacheUser } from "../resolvers/user.js";
+/** Cache filename used by the user resolver. */
+const USER_CACHE_FILE = "users.json";
+/** Pattern matching user mentions in Slack message text. */
+const USER_MENTION_PATTERN = /<@([UW][A-Z0-9]+)(?:\|[^>]*)?>/g;
+/**
+ * Resolve all unknown user IDs in a list of messages.
+ *
+ * Collects unique user IDs from message authors and from
+ * user mentions in message text. Calls users.info for each
+ * unknown ID and caches the results. After this call,
+ * displayNameForId() will return handles for all users
+ * referenced in the messages.
+ *
+ * Silently skips users that fail to resolve (deleted accounts,
+ * bots without profiles).
+ */
+export async function resolveUsersInMessages(client, messages, signal) {
+    const unknownIds = new Set();
+    for (const msg of messages) {
+        // Message author.
+        if (msg.user && !lookupName(USER_CACHE_FILE, msg.user)) {
+            unknownIds.add(msg.user);
+        }
+        // User mentions in message text.
+        if (msg.text) {
+            for (const match of msg.text.matchAll(USER_MENTION_PATTERN)) {
+                const userId = match[1];
+                if (!lookupName(USER_CACHE_FILE, userId)) {
+                    unknownIds.add(userId);
+                }
+            }
+        }
+    }
+    if (unknownIds.size === 0)
+        return;
+    // Resolve in parallel with a concurrency limit. users.info
+    // is Tier 4 (~100 req/min), so 20 concurrent is well
+    // within limits.
+    const ids = [...unknownIds];
+    const BATCH_SIZE = 20;
+    for (let i = 0; i < ids.length; i += BATCH_SIZE) {
+        if (signal?.aborted)
+            return;
+        const batch = ids.slice(i, i + BATCH_SIZE);
+        await Promise.all(batch.map(async (id) => {
+            try {
+                const response = await client.call("users.info", { user: id }, signal);
+                const u = response.user;
+                if (u?.name && u?.id) {
+                    cacheUser(u.name, u.id);
+                }
+            }
+            catch {
+                // User not found, deleted, or rate limited.
+                // Silently skip, since displayNameForId falls back to raw ID.
+            }
+        }));
+    }
+}

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

@@ -0,0 +1,86 @@
+/**
+ * Slack search API: messages and files.
+ *
+ * Builds queries from structured parameters, including Slack
+ * search operators (from:, in:, after:, before:). Auto-paginates
+ * through results using Slack's traditional paging (page +
+ * count). Caches channel and user mappings found in results.
+ */
+import type { SlackMessage } from "../types.js";
+import type { SlackClient } from "./client.js";
+/** Search result with messages, total count and the query sent to Slack. */
+export interface MessageSearchResult {
+    messages: SlackMessage[];
+    total: number;
+    query: string;
+}
+/** Page metadata passed to the `onPage` callback. */
+export interface SearchPageInfo {
+    /** Current page number (1-indexed). */
+    page: number;
+    /** Total number of pages available. */
+    totalPages: number;
+    /** Total number of matching messages across all pages. */
+    total: number;
+}
+/** Options for searching messages. */
+export interface SearchMessagesOptions {
+    channel?: string;
+    from?: string;
+    with?: string;
+    after?: string;
+    before?: string;
+    limit?: number;
+    signal?: AbortSignal;
+    /**
+     * Called after each page is fetched, deduplicated and
+     * cached. Receives only new (non-duplicate) messages
+     * from that page. Useful for progress reporting or
+     * incremental processing without reimplementing
+     * pagination.
+     */
+    onPage?: (messages: SlackMessage[], pageInfo: SearchPageInfo) => void;
+}
+/**
+ * Search Slack messages with automatic pagination.
+ *
+ * Fetches pages of up to 100 results until the requested limit
+ * is reached or all pages are exhausted. Pass `limit: 0` for
+ * unlimited (up to Slack's ceiling of 10,000 results).
+ */
+export declare function searchMessages(client: SlackClient, query: string, opts?: SearchMessagesOptions): Promise<MessageSearchResult>;
+/** File metadata from a file search. */
+export interface SlackFileResult {
+    id: string;
+    name: string;
+    title?: string;
+    mimetype?: string;
+    size?: number;
+    user?: string;
+    permalink?: string;
+}
+/** File search result. */
+export interface FileSearchResult {
+    files: SlackFileResult[];
+    total: number;
+    query: string;
+}
+/** Options for searching files. */
+export interface SearchFilesOptions {
+    channel?: string;
+    from?: string;
+    with?: string;
+    after?: string;
+    before?: string;
+    type?: string;
+    limit?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Search Slack files with automatic pagination.
+ *
+ * Fetches pages of up to 100 results until the requested limit
+ * is reached or all pages are exhausted. Pass `limit: 0` for
+ * unlimited (up to Slack's ceiling of 10,000 results).
+ */
+export declare function searchFiles(client: SlackClient, query: string, opts?: SearchFilesOptions): Promise<FileSearchResult>;

package/dist/slack/api/search.js

@@ -0,0 +1,186 @@
+/**
+ * Slack search API: messages and files.
+ *
+ * Builds queries from structured parameters, including Slack
+ * search operators (from:, in:, after:, before:). Auto-paginates
+ * through results using Slack's traditional paging (page +
+ * count). Caches channel and user mappings found in results.
+ */
+import { cacheChannelName } from "../resolvers/conversation.js";
+import { cacheUser } from "../resolvers/user.js";
+import { cacheConversationFromSearch } from "./resolve-conversations.js";
+/** Maximum results per page (Slack API hard limit). */
+const MAX_PER_PAGE = 100;
+/** Maximum page number (Slack API hard limit). */
+const MAX_PAGE = 100;
+/** Default number of results when no limit is specified. */
+const DEFAULT_LIMIT = 20;
+/** Build a search query string from structured parameters. */
+function buildQuery(query, opts) {
+    let q = query;
+    if (opts.channel) {
+        const ch = opts.channel.startsWith("#") ? opts.channel : `#${opts.channel}`;
+        q += ` in:${ch}`;
+    }
+    if (opts.from) {
+        const user = opts.from.startsWith("@") ? opts.from.slice(1) : opts.from;
+        q += ` from:${user}`;
+    }
+    if (opts.with) {
+        const user = opts.with.startsWith("@") ? opts.with.slice(1) : opts.with;
+        q += ` with:${user}`;
+    }
+    if (opts.after)
+        q += ` after:${opts.after}`;
+    if (opts.before)
+        q += ` before:${opts.before}`;
+    return q;
+}
+/** Cache conversation and user mappings from a search match. */
+function cacheMatchMappings(m) {
+    if (m.channel?.id && m.channel?.name) {
+        cacheChannelName(m.channel.name, m.channel.id);
+        cacheConversationFromSearch(m.channel.id, m.channel.name);
+    }
+    if (m.user && m.username) {
+        cacheUser(m.username, m.user);
+    }
+}
+/** Convert a Slack search match to our message type. */
+function matchToMessage(m) {
+    const conversation = m.channel?.id
+        ? {
+            id: m.channel.id,
+            name: m.channel.name,
+            kind: m.channel.name?.startsWith("mpdm-") ? "group_dm" : "channel",
+            displayName: m.channel.name
+                ? m.channel.name.startsWith("mpdm-")
+                    ? undefined
+                    : `#${m.channel.name}`
+                : undefined,
+        }
+        : undefined;
+    return {
+        ts: m.ts,
+        text: m.text ?? "",
+        user: m.user,
+        conversation,
+        threadTs: m.thread_ts,
+        replyCount: m.reply_count,
+        isThreadParent: m.thread_ts !== undefined && m.thread_ts === m.ts,
+        permalink: m.permalink,
+    };
+}
+/**
+ * Search Slack messages with automatic pagination.
+ *
+ * Fetches pages of up to 100 results until the requested limit
+ * is reached or all pages are exhausted. Pass `limit: 0` for
+ * unlimited (up to Slack's ceiling of 10,000 results).
+ */
+export async function searchMessages(client, query, opts = {}) {
+    const fullQuery = buildQuery(query, opts);
+    const targetLimit = opts.limit === 0 ? Number.POSITIVE_INFINITY : opts.limit || DEFAULT_LIMIT;
+    const perPage = Math.min(targetLimit, MAX_PER_PAGE);
+    const allMessages = [];
+    const seen = new Set();
+    let page = 1;
+    let totalPages = 1;
+    let total = 0;
+    while (allMessages.length < targetLimit &&
+        page <= totalPages &&
+        page <= MAX_PAGE) {
+        if (opts.signal?.aborted)
+            break;
+        const response = await client.call("search.messages", {
+            query: fullQuery,
+            count: perPage,
+            page,
+            sort: "timestamp",
+            sort_dir: "desc",
+        }, opts.signal);
+        const matches = response.messages?.matches ?? [];
+        total = response.messages?.total ?? 0;
+        totalPages = response.messages?.paging?.pages ?? 1;
+        if (matches.length === 0)
+            break;
+        const pageMessages = [];
+        for (const m of matches) {
+            cacheMatchMappings(m);
+            if (seen.has(m.ts))
+                continue;
+            seen.add(m.ts);
+            const msg = matchToMessage(m);
+            allMessages.push(msg);
+            pageMessages.push(msg);
+            if (allMessages.length >= targetLimit)
+                break;
+        }
+        if (opts.onPage && pageMessages.length > 0) {
+            opts.onPage(pageMessages, { page, totalPages, total });
+        }
+        page++;
+    }
+    return {
+        messages: allMessages,
+        total,
+        query: fullQuery,
+    };
+}
+/**
+ * Search Slack files with automatic pagination.
+ *
+ * Fetches pages of up to 100 results until the requested limit
+ * is reached or all pages are exhausted. Pass `limit: 0` for
+ * unlimited (up to Slack's ceiling of 10,000 results).
+ */
+export async function searchFiles(client, query, opts = {}) {
+    const fullQuery = buildQuery(query, opts);
+    const targetLimit = opts.limit === 0 ? Number.POSITIVE_INFINITY : opts.limit || DEFAULT_LIMIT;
+    const perPage = Math.min(targetLimit, MAX_PER_PAGE);
+    const allFiles = [];
+    const seen = new Set();
+    let page = 1;
+    let totalPages = 1;
+    let total = 0;
+    while (allFiles.length < targetLimit &&
+        page <= totalPages &&
+        page <= MAX_PAGE) {
+        if (opts.signal?.aborted)
+            break;
+        const response = await client.call("search.files", {
+            query: fullQuery,
+            count: perPage,
+            page,
+            sort: "timestamp",
+            sort_dir: "desc",
+        }, opts.signal);
+        const matches = response.files?.matches ?? [];
+        total = response.files?.total ?? 0;
+        totalPages = response.files?.paging?.pages ?? 1;
+        if (matches.length === 0)
+            break;
+        for (const f of matches) {
+            if (seen.has(f.id))
+                continue;
+            seen.add(f.id);
+            allFiles.push({
+                id: f.id,
+                name: f.name,
+                title: f.title,
+                mimetype: f.mimetype,
+                size: f.size,
+                user: f.user,
+                permalink: f.permalink,
+            });
+            if (allFiles.length >= targetLimit)
+                break;
+        }
+        page++;
+    }
+    return {
+        files: allFiles,
+        total,
+        query: fullQuery,
+    };
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Slack user API: profiles and info.
+ */
+import type { SlackUser } from "../types.js";
+import type { SlackClient } from "./client.js";
+/**
+ * Fetch a user's profile by ID.
+ *
+ * Uses users.info which works with client tokens on
+ * enterprise grids (unlike users.list).
+ */
+export declare function getUserInfo(client: SlackClient, userId: string, signal?: AbortSignal): Promise<SlackUser>;

package/dist/slack/api/users.js

@@ -0,0 +1,33 @@
+/**
+ * Slack user API: profiles and info.
+ */
+import { cacheUser } from "../resolvers/user.js";
+/**
+ * Fetch a user's profile by ID.
+ *
+ * Uses users.info which works with client tokens on
+ * enterprise grids (unlike users.list).
+ */
+export async function getUserInfo(client, userId, signal) {
+    const response = await client.call("users.info", { user: userId }, signal);
+    const u = response.user;
+    const profile = u.profile ?? {};
+    // Cache the handle → ID mapping.
+    if (u.name && u.id) {
+        cacheUser(u.name, u.id);
+    }
+    return {
+        id: u.id,
+        name: u.name,
+        realName: profile.real_name ?? u.real_name,
+        displayName: profile.display_name || undefined,
+        title: profile.title || undefined,
+        email: profile.email || undefined,
+        isBot: u.is_bot ?? false,
+        isAdmin: u.is_admin ?? false,
+        timezone: u.tz,
+        statusText: profile.status_text || undefined,
+        statusEmoji: profile.status_emoji || undefined,
+        deleted: u.deleted ?? false,
+    };
+}

package/dist/slack/auth/browser-extract.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Automatic Slack credential extraction via browser.
+ *
+ * Launches Chrome (non-headless, using the user's existing
+ * install), navigates to Slack, and polls localStorage and
+ * cookies for the xoxc- token and xoxd- cookie. Works with
+ * any Slack workspace; the user just needs to be logged in
+ * (or log in when the browser opens).
+ *
+ * Uses puppeteer-core (no bundled browser) for consistency
+ * with web-search-integration.
+ */
+/** Extracted browser session credentials. */
+export interface BrowserCredentials {
+    token: string;
+    cookie: string;
+}
+/**
+ * Launch Chrome, navigate to Slack, and extract credentials.
+ *
+ * Opens a visible browser window so the user can log in if
+ * needed. Polls localStorage for the xoxc- token and the
+ * browser's cookie jar for the xoxd- session cookie.
+ *
+ * @param slackUrl - Slack URL to navigate to (default: the sign-in
+ *   entry point, not a workspace or the marketing homepage)
+ * @param timeoutMs - How long to wait before giving up
+ * @param onStep - Called once, right after the browser opens, with
+ *   the guidance a person watching needs to actually finish sign-in.
+ *   Adapter-supplied rather than written straight to stderr here, so
+ *   a host that isn't a bare terminal can surface it its own way.
+ */
+export declare function extractFromBrowser(slackUrl?: string, timeoutMs?: number, onStep?: (message: string) => void): Promise<BrowserCredentials>;