@jitsusama/agentic-harness.core 0.1.0

package/dist/slack/renderers/search.js

@@ -0,0 +1,39 @@
+/**
+ * Format search results as readable text.
+ */
+import { count } from "../../ui/count.js";
+/** Render file search results. */
+export function renderFileList(files, total, query) {
+    if (files.length === 0) {
+        return "No files found.";
+    }
+    const lines = [];
+    if (query) {
+        lines.push(`Query: ${query}`);
+    }
+    const truncated = total > files.length;
+    const showing = truncated
+        ? `, showing ${files.length} (limit reached, so pass a higher limit or 0 for all)`
+        : `, showing ${files.length}`;
+    lines.push(`Found ${count(total, "file")}${showing}:\n`);
+    for (const f of files) {
+        const size = f.size ? ` (${formatBytes(f.size)})` : "";
+        const type = f.mimetype ? ` [${f.mimetype}]` : "";
+        lines.push(`- **${f.name}**${type}${size}`);
+        if (f.title && f.title !== f.name) {
+            lines.push(`  Title: ${f.title}`);
+        }
+        if (f.permalink) {
+            lines.push(`  ${f.permalink}`);
+        }
+    }
+    return lines.join("\n");
+}
+/** Format byte count as a human-readable string. */
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}

package/dist/slack/renderers/user.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Format user profiles as readable text.
+ */
+import type { SlackUser } from "../types.js";
+/** Render a user profile as a readable summary. */
+export declare function renderUser(user: SlackUser): string;

package/dist/slack/renderers/user.js

@@ -0,0 +1,32 @@
+/**
+ * Format user profiles as readable text.
+ */
+/** Render a user profile as a readable summary. */
+export function renderUser(user) {
+    const lines = [];
+    const displayName = user.displayName || user.realName || user.name;
+    lines.push(`**@${user.name}** (${displayName})`);
+    if (user.title)
+        lines.push(`Title: ${user.title}`);
+    if (user.email)
+        lines.push(`Email: ${user.email}`);
+    if (user.timezone)
+        lines.push(`Timezone: ${user.timezone}`);
+    if (user.statusText || user.statusEmoji) {
+        const status = [user.statusEmoji, user.statusText]
+            .filter(Boolean)
+            .join(" ");
+        lines.push(`Status: ${status}`);
+    }
+    const flags = [];
+    if (user.isBot)
+        flags.push("bot");
+    if (user.isAdmin)
+        flags.push("admin");
+    if (user.deleted)
+        flags.push("deactivated");
+    if (flags.length > 0)
+        lines.push(`Flags: ${flags.join(", ")}`);
+    lines.push(`ID: ${user.id}`);
+    return lines.join("\n");
+}

package/dist/slack/resolvers/cache.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared file-based cache for name → ID mappings.
+ *
+ * Used by channel and user resolvers. Each resolver gets its
+ * own cache file under the directory paths.ts names. Entries
+ * are keyed by lowercase name to avoid case-sensitivity issues.
+ */
+/**
+ * Look up a cached ID by name.
+ * Returns the ID if found, null otherwise.
+ */
+export declare function lookupId(filename: string, name: string): string | null;
+/**
+ * Look up a cached name by ID.
+ * Reverse lookup: scans all entries for a matching ID.
+ */
+export declare function lookupName(filename: string, id: string): string | null;
+/**
+ * Store a name → ID mapping in the cache.
+ * Called opportunistically whenever we see name/ID pairs in API responses.
+ */
+export declare function cacheMapping(filename: string, name: string, id: string): void;
+/**
+ * List all cached entries, sorted by name.
+ */
+export declare function listCached(filename: string): Array<{
+    name: string;
+    id: string;
+}>;

package/dist/slack/resolvers/cache.js

@@ -0,0 +1,70 @@
+/**
+ * Shared file-based cache for name → ID mappings.
+ *
+ * Used by channel and user resolvers. Each resolver gets its
+ * own cache file under the directory paths.ts names. Entries
+ * are keyed by lowercase name to avoid case-sensitivity issues.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { cacheDir } from "../paths.js";
+/** Directory for resolver caches. */
+const CACHE_DIR = cacheDir();
+/** Ensure the cache directory exists. */
+function ensureDir() {
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+}
+/** Read a cache file, returning an empty object if missing or corrupt. */
+function readCache(filename) {
+    try {
+        const raw = fs.readFileSync(path.join(CACHE_DIR, filename), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        // File doesn't exist or is corrupt.
+        return {};
+    }
+}
+/** Write a cache file. */
+function writeCache(filename, data) {
+    ensureDir();
+    fs.writeFileSync(path.join(CACHE_DIR, filename), JSON.stringify(data, null, "\t"), "utf-8");
+}
+/**
+ * Look up a cached ID by name.
+ * Returns the ID if found, null otherwise.
+ */
+export function lookupId(filename, name) {
+    const data = readCache(filename);
+    return data[name.toLowerCase()]?.id ?? null;
+}
+/**
+ * Look up a cached name by ID.
+ * Reverse lookup: scans all entries for a matching ID.
+ */
+export function lookupName(filename, id) {
+    const data = readCache(filename);
+    for (const entry of Object.values(data)) {
+        if (entry.id === id)
+            return entry.name;
+    }
+    return null;
+}
+/**
+ * Store a name → ID mapping in the cache.
+ * Called opportunistically whenever we see name/ID pairs in API responses.
+ */
+export function cacheMapping(filename, name, id) {
+    const data = readCache(filename);
+    data[name.toLowerCase()] = { id, name, updatedAt: Date.now() };
+    writeCache(filename, data);
+}
+/**
+ * List all cached entries, sorted by name.
+ */
+export function listCached(filename) {
+    const data = readCache(filename);
+    return Object.values(data)
+        .map((e) => ({ name: e.name, id: e.id }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/slack/resolvers/conversation-cache.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared in-memory conversation metadata cache.
+ *
+ * Both the conversation resolver (input resolution) and the
+ * message enrichment step (output formatting) use this cache
+ * as a single source of truth. Avoids duplicate conversations.info
+ * calls across the two code paths.
+ *
+ * Session-scoped: cleared when the process exits. The file-based
+ * name → ID cache in resolvers/cache.ts handles cross-session
+ * persistence for name lookups; this cache handles richer metadata
+ * (kind, displayName) within a session.
+ */
+import type { SlackClient } from "../api/client.js";
+import type { Conversation, ConversationKind } from "../types.js";
+/** Look up a cached conversation by ID. */
+export declare function getCachedConversation(id: string): Conversation | undefined;
+/** Store a conversation in the cache. */
+export declare function cacheConversation(conversation: Conversation): void;
+/**
+ * Fetch conversation metadata, using the cache when possible.
+ *
+ * Calls conversations.info on cache miss, caches the result,
+ * and returns a fully populated Conversation. Callers should
+ * prefer getCachedConversation for the fast path.
+ */
+export declare function fetchConversation(client: SlackClient, id: string, signal?: AbortSignal): Promise<Conversation>;
+/**
+ * Refresh display names on DM conversations after user resolution.
+ *
+ * Call after resolveUsersInMessages so displayNameForId
+ * returns handles instead of raw IDs.
+ */
+export declare function refreshCachedDmNames(): void;
+/**
+ * Infer conversation kind from a channel ID prefix.
+ *
+ * Best-effort guess used when we only have an ID and haven't
+ * called conversations.info yet. D-prefix → DM, G-prefix →
+ * group_dm, everything else → channel.
+ */
+export declare function inferKindFromId(id: string): ConversationKind;

package/dist/slack/resolvers/conversation-cache.js

@@ -0,0 +1,128 @@
+/**
+ * Shared in-memory conversation metadata cache.
+ *
+ * Both the conversation resolver (input resolution) and the
+ * message enrichment step (output formatting) use this cache
+ * as a single source of truth. Avoids duplicate conversations.info
+ * calls across the two code paths.
+ *
+ * Session-scoped: cleared when the process exits. The file-based
+ * name → ID cache in resolvers/cache.ts handles cross-session
+ * persistence for name lookups; this cache handles richer metadata
+ * (kind, displayName) within a session.
+ */
+import { displayNameForId } from "./user.js";
+/** In-memory cache of resolved conversation metadata. */
+const cache = new Map();
+/** Look up a cached conversation by ID. */
+export function getCachedConversation(id) {
+    return cache.get(id);
+}
+/** Store a conversation in the cache. */
+export function cacheConversation(conversation) {
+    cache.set(conversation.id, conversation);
+}
+/**
+ * Fetch conversation metadata, using the cache when possible.
+ *
+ * Calls conversations.info on cache miss, caches the result,
+ * and returns a fully populated Conversation. Callers should
+ * prefer getCachedConversation for the fast path.
+ */
+export async function fetchConversation(client, id, signal) {
+    const cached = cache.get(id);
+    if (cached)
+        return cached;
+    const response = await client.call("conversations.info", { channel: id }, signal);
+    const ch = response.channel;
+    const conversation = toConversation(ch);
+    cache.set(id, conversation);
+    return conversation;
+}
+/**
+ * Refresh display names on DM conversations after user resolution.
+ *
+ * Call after resolveUsersInMessages so displayNameForId
+ * returns handles instead of raw IDs.
+ */
+export function refreshCachedDmNames() {
+    for (const conv of cache.values()) {
+        if (conv.kind === "dm" && conv.dmUserId) {
+            const handle = displayNameForId(conv.dmUserId);
+            if (handle !== conv.dmUserId) {
+                conv.displayName = `@${handle}`;
+            }
+        }
+    }
+}
+/**
+ * Convert a conversations.info response to a Conversation.
+ *
+ * Shared parsing logic for the boolean fields Slack uses
+ * to indicate conversation type.
+ */
+function toConversation(ch) {
+    if (ch.is_im) {
+        const userId = ch.user;
+        const handle = userId ? displayNameForId(userId) : undefined;
+        const displayName = handle && handle !== userId ? `@${handle}` : userId ? userId : undefined;
+        return {
+            id: ch.id,
+            kind: "dm",
+            displayName,
+            dmUserId: userId,
+        };
+    }
+    if (ch.is_mpim) {
+        const displayName = formatGroupDmName(ch.name, ch.purpose?.value);
+        return {
+            id: ch.id,
+            kind: "group_dm",
+            displayName,
+        };
+    }
+    // Regular channel (public or private).
+    return {
+        id: ch.id,
+        name: ch.name,
+        kind: "channel",
+        displayName: ch.name ? `#${ch.name}` : undefined,
+    };
+}
+/**
+ * Format a group DM name from the mpdm- format or purpose.
+ *
+ * Slack names group DMs like `mpdm-user1--user2--user3-1`.
+ * The purpose field contains "Group messaging with: @user1
+ * @user2 @user3". We prefer the purpose when available.
+ */
+function formatGroupDmName(rawName, purpose) {
+    if (purpose?.startsWith("Group messaging with:")) {
+        const names = purpose
+            .replace("Group messaging with:", "")
+            .trim()
+            .split(/\s+/)
+            .map((n) => (n.startsWith("@") ? n : `@${n}`));
+        return names.join(", ");
+    }
+    if (rawName?.startsWith("mpdm-")) {
+        const stripped = rawName.replace(/^mpdm-/, "").replace(/-\d+$/, "");
+        const users = stripped.split("--").map((u) => `@${u}`);
+        return users.join(", ");
+    }
+    return "group DM";
+}
+/**
+ * Infer conversation kind from a channel ID prefix.
+ *
+ * Best-effort guess used when we only have an ID and haven't
+ * called conversations.info yet. D-prefix → DM, G-prefix →
+ * group_dm, everything else → channel.
+ */
+export function inferKindFromId(id) {
+    if (id.startsWith("D"))
+        return "dm";
+    if (id.startsWith("G"))
+        return "group_dm";
+    return "channel";
+}

package/dist/slack/resolvers/conversation.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Conversation resolver: any identifier → Conversation.
+ *
+ * Accepts channel IDs, user IDs, @-prefixed user handles,
+ * #-prefixed channel names, bare channel names and Slack
+ * URLs. Returns a Conversation with at least id and kind
+ * populated. Uses the shared conversation cache to avoid
+ * redundant API calls.
+ *
+ * The prefix determines intent: `@handle` resolves as a
+ * user (opening the DM conversation), `#name` resolves as
+ * a channel. IDs are detected by their Slack prefix pattern
+ * (C/D/G for channels, U/W for users). Bare strings that
+ * match none of these fall through to channel name search
+ * as a last resort.
+ *
+ * On enterprise grids, conversations.list is blocked, so we
+ * resolve channel names by searching for a message in that
+ * channel and extracting the channel ID from the result.
+ */
+import type { SlackClient } from "../api/client.js";
+import type { Conversation } from "../types.js";
+/**
+ * Resolve a conversation identifier to a Conversation.
+ *
+ * Accepts:
+ *   - Channel ID (C..., D..., G...) → fetched via cache or conversations.info
+ *   - User ID (U..., W...) → opens/finds the DM conversation via conversations.open
+ *   - Comma-separated user IDs or @handles → opens/finds a group DM
+ *   - @handle (e.g. "@joel.gerber") → resolved to user ID via search, then DM
+ *   - Channel name (with or without #) → resolved via file cache, then search
+ *   - Slack URL → parsed for the channel ID
+ */
+export declare function resolveConversation(client: SlackClient, input: string): Promise<Conversation>;
+/**
+ * Record a channel name → ID mapping.
+ * Called opportunistically when channel data appears in API responses.
+ */
+export declare function cacheChannelName(name: string, id: string): void;
+/** List all cached channel mappings. */
+export declare function listCachedChannels(): Array<{
+    name: string;
+    id: string;
+}>;

package/dist/slack/resolvers/conversation.js

@@ -0,0 +1,229 @@
+/**
+ * Conversation resolver: any identifier → Conversation.
+ *
+ * Accepts channel IDs, user IDs, @-prefixed user handles,
+ * #-prefixed channel names, bare channel names and Slack
+ * URLs. Returns a Conversation with at least id and kind
+ * populated. Uses the shared conversation cache to avoid
+ * redundant API calls.
+ *
+ * The prefix determines intent: `@handle` resolves as a
+ * user (opening the DM conversation), `#name` resolves as
+ * a channel. IDs are detected by their Slack prefix pattern
+ * (C/D/G for channels, U/W for users). Bare strings that
+ * match none of these fall through to channel name search
+ * as a last resort.
+ *
+ * On enterprise grids, conversations.list is blocked, so we
+ * resolve channel names by searching for a message in that
+ * channel and extracting the channel ID from the result.
+ */
+import { getUserInfo } from "../api/users.js";
+import { cacheMapping, listCached, lookupId } from "./cache.js";
+import { cacheConversation, fetchConversation, getCachedConversation, inferKindFromId, } from "./conversation-cache.js";
+import { parseSlackUrl } from "./url.js";
+import { displayNameForId, resolveUser } from "./user.js";
+const CACHE_FILE = "channels.json";
+/** Pattern matching Slack channel IDs (C, D, or G prefix). */
+const CHANNEL_ID_PATTERN = /^[CDG][A-Z0-9]{8,}$/;
+/** Pattern matching Slack user IDs (U or W prefix). */
+const USER_ID_PATTERN = /^[UW][A-Z0-9]{8,}$/;
+/**
+ * Resolve a conversation identifier to a Conversation.
+ *
+ * Accepts:
+ *   - Channel ID (C..., D..., G...) → fetched via cache or conversations.info
+ *   - User ID (U..., W...) → opens/finds the DM conversation via conversations.open
+ *   - Comma-separated user IDs or @handles → opens/finds a group DM
+ *   - @handle (e.g. "@joel.gerber") → resolved to user ID via search, then DM
+ *   - Channel name (with or without #) → resolved via file cache, then search
+ *   - Slack URL → parsed for the channel ID
+ */
+export async function resolveConversation(client, input) {
+    // Comma-separated values: open a group DM with multiple users.
+    if (input.includes(",")) {
+        return openGroupDmConversation(client, input);
+    }
+    // Channel ID: look up metadata.
+    if (CHANNEL_ID_PATTERN.test(input)) {
+        return resolveById(client, input);
+    }
+    // User ID: open a DM conversation with that user.
+    if (USER_ID_PATTERN.test(input)) {
+        return openDmConversation(client, input);
+    }
+    // Slack URL: extract channel ID directly.
+    const parsed = parseSlackUrl(input);
+    if (parsed)
+        return resolveById(client, parsed.channel);
+    // URL that contains /archives/CHANNELID/ but didn't match the full pattern.
+    const archiveMatch = input.match(/archives\/([CDG][A-Z0-9]+)/);
+    if (archiveMatch)
+        return resolveById(client, archiveMatch[1]);
+    // User handle: @joel.gerber → resolve to user ID, then DM.
+    if (input.startsWith("@")) {
+        const userId = await resolveUser(client, input.slice(1));
+        return openDmConversation(client, userId);
+    }
+    // Channel name: strip leading #.
+    const name = input.startsWith("#") ? input.slice(1) : input;
+    // Recheck after stripping: #U098TB6UXGA → U098TB6UXGA is a user ID.
+    if (USER_ID_PATTERN.test(name)) {
+        return openDmConversation(client, name);
+    }
+    // Check file cache for name → ID mapping.
+    const cachedId = lookupId(CACHE_FILE, name);
+    if (cachedId)
+        return resolveById(client, cachedId);
+    // Resolve via search. Enterprise grids block conversations.list,
+    // but search.messages with in:#channel works across the grid.
+    const response = await client.call("search.messages", {
+        query: `in:#${name} *`,
+        count: 1,
+    });
+    const match = response.messages?.matches?.[0];
+    if (match?.channel?.id) {
+        cacheChannelName(match.channel.name, match.channel.id);
+        const conversation = {
+            id: match.channel.id,
+            name: match.channel.name,
+            kind: "channel",
+            displayName: `#${match.channel.name}`,
+        };
+        cacheConversation(conversation);
+        return conversation;
+    }
+    throw new Error(`Could not resolve channel "${input}". ` +
+        "Use a channel ID (e.g. C0ACMKCS6UW) or verify the channel name.");
+}
+/**
+ * Record a channel name → ID mapping.
+ * Called opportunistically when channel data appears in API responses.
+ */
+export function cacheChannelName(name, id) {
+    if (name && id) {
+        cacheMapping(CACHE_FILE, name, id);
+    }
+}
+/** List all cached channel mappings. */
+export function listCachedChannels() {
+    return listCached(CACHE_FILE);
+}
+/**
+ * Resolve a channel ID to a Conversation.
+ *
+ * Uses the shared conversation cache for the fast path,
+ * falling back to conversations.info on cache miss.
+ */
+async function resolveById(client, id) {
+    const cached = getCachedConversation(id);
+    if (cached)
+        return cached;
+    // Try conversations.info for full metadata.
+    try {
+        return await fetchConversation(client, id);
+    }
+    catch {
+        // If conversations.info fails (permissions, etc.), fall back to
+        // best-effort inference from the ID prefix.
+        const conversation = {
+            id,
+            kind: inferKindFromId(id),
+        };
+        cacheConversation(conversation);
+        return conversation;
+    }
+}
+/**
+ * Open or find the DM conversation for a user ID.
+ *
+ * Uses conversations.open which returns the existing DM
+ * if one exists, or creates it if not.
+ */
+async function openDmConversation(client, userId) {
+    const response = await client.call("conversations.open", { users: userId });
+    const channelId = response.channel?.id;
+    if (!channelId) {
+        throw new Error(`Could not open DM conversation for user "${userId}". ` +
+            "Verify the user ID is correct.");
+    }
+    const displayName = await dmDisplayName(client, userId);
+    const conversation = {
+        id: channelId,
+        kind: "dm",
+        dmUserId: userId,
+        displayName,
+    };
+    cacheConversation(conversation);
+    return conversation;
+}
+/**
+ * Open or find a group DM with multiple users.
+ *
+ * Accepts a comma-separated string of user IDs and/or @handles.
+ * Each segment is resolved to a user ID, then conversations.open
+ * is called with all IDs to create or find the group DM.
+ */
+async function openGroupDmConversation(client, input) {
+    const segments = input
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (segments.length < 2) {
+        throw new Error("Group DM requires at least two user IDs or handles, " +
+            "separated by commas.");
+    }
+    const userIds = [];
+    for (const segment of segments) {
+        const bare = segment.startsWith("@") ? segment.slice(1) : segment;
+        if (USER_ID_PATTERN.test(bare)) {
+            userIds.push(bare);
+        }
+        else {
+            userIds.push(await resolveUser(client, bare));
+        }
+    }
+    const response = await client.call("conversations.open", { users: userIds.join(",") });
+    const ch = response.channel;
+    if (!ch?.id) {
+        throw new Error("Could not open group DM. Verify the user IDs or handles are correct.");
+    }
+    const conversation = {
+        id: ch.id,
+        kind: "group_dm",
+        displayName: formatGroupDmDisplayName(userIds),
+    };
+    cacheConversation(conversation);
+    return conversation;
+}
+/**
+ * Build a display name for a group DM from resolved user IDs.
+ *
+ * Uses cached @handles when available, falls back to raw IDs.
+ */
+function formatGroupDmDisplayName(userIds) {
+    return userIds.map((id) => `@${displayNameForId(id)}`).join(", ");
+}
+/**
+ * Resolve a display name for a DM user.
+ *
+ * Checks the file cache first. On miss, calls users.info
+ * to fetch the handle (which also populates the cache for
+ * future lookups). Returns `@handle` or undefined if
+ * resolution fails entirely.
+ */
+async function dmDisplayName(client, userId) {
+    const cached = displayNameForId(userId);
+    if (cached !== userId)
+        return `@${cached}`;
+    try {
+        const user = await getUserInfo(client, userId);
+        const handle = user.name;
+        if (handle)
+            return `@${handle}`;
+    }
+    catch {
+        // users.info failed; fall through to undefined.
+    }
+    return undefined;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Slack entity resolvers: channel, user, conversation and
+ * target resolution.
+ */
+export { resolveConversation } from "./conversation.js";
+export { resolveTarget } from "./target.js";
+export { type ParsedSlackUrl, parseSlackUrl } from "./url.js";
+export { displayNameForId, resolveUser } from "./user.js";

package/dist/slack/resolvers/index.js

@@ -0,0 +1,8 @@
+/**
+ * Slack entity resolvers: channel, user, conversation and
+ * target resolution.
+ */
+export { resolveConversation } from "./conversation.js";
+export { resolveTarget } from "./target.js";
+export { parseSlackUrl } from "./url.js";
+export { displayNameForId, resolveUser } from "./user.js";

package/dist/slack/resolvers/target.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve a message target to a Conversation and timestamp.
+ *
+ * Many actions accept either a Slack permalink URL or a
+ * channel + timestamp pair. This module centralises that
+ * resolution so handlers don't repeat it.
+ */
+import type { SlackClient } from "../api/client.js";
+import type { MessageTarget } from "../types.js";
+/**
+ * Resolve a message target from tool parameters.
+ *
+ * Accepts:
+ *   - target (Slack URL) → parsed, then conversation resolved
+ *   - channel + ts → conversation resolved
+ *
+ * Throws if neither provides enough information.
+ */
+export declare function resolveTarget(client: SlackClient, target: string | undefined, channel: string | undefined, ts: string | undefined): Promise<MessageTarget>;