@alejandroroman/agent-kit 0.1.0

package/dist/gateways/slack/format.js

@@ -0,0 +1,170 @@
+/**
+ * Convert markdown (as produced by LLMs) to Slack Block Kit blocks.
+ *
+ * Produces an array of Block Kit objects for rich rendering:
+ * - Headings → header blocks
+ * - Horizontal rules → divider blocks
+ * - Tables → section blocks with monospace code for alignment
+ * - Text paragraphs → section blocks with mrkdwn
+ * - Code blocks → section blocks with triple-backtick mrkdwn
+ */
+/** Convert markdown to Slack mrkdwn inline formatting */
+export function convertInlineFormatting(text) {
+    let result = text.replace(/\*\*(.+?)\*\*/g, "*$1*");
+    result = result.replace(/__(.+?)__/g, "*$1*");
+    result = result.replace(/~~(.+?)~~/g, "~$1~");
+    return result;
+}
+/** Convert full markdown string to Slack Block Kit blocks */
+export function markdownToBlocks(md) {
+    const lines = md.split("\n");
+    const blocks = [];
+    let i = 0;
+    let textBuffer = [];
+    function flushText() {
+        const text = textBuffer.join("\n").trim();
+        if (text) {
+            blocks.push({
+                type: "section",
+                text: { type: "mrkdwn", text: convertInlineFormatting(text) },
+            });
+        }
+        textBuffer = [];
+    }
+    while (i < lines.length) {
+        const line = lines[i];
+        // Fenced code blocks → section with triple backticks
+        if (line.trimStart().startsWith("```")) {
+            flushText();
+            const codeLines = [];
+            const lang = line.trim().slice(3);
+            i++;
+            while (i < lines.length && !lines[i].trimStart().startsWith("```")) {
+                codeLines.push(lines[i]);
+                i++;
+            }
+            if (i < lines.length)
+                i++; // skip closing ```
+            blocks.push({
+                type: "section",
+                text: { type: "mrkdwn", text: "```" + (lang ? lang + "\n" : "\n") + codeLines.join("\n") + "\n```" },
+            });
+            continue;
+        }
+        // Horizontal rules → divider
+        if (/^-{3,}$/.test(line.trim()) || /^\*{3,}$/.test(line.trim())) {
+            flushText();
+            blocks.push({ type: "divider" });
+            i++;
+            continue;
+        }
+        // Markdown table → monospace code block for perfect alignment
+        if (isTableRow(line)) {
+            flushText();
+            const tableLines = [];
+            while (i < lines.length && isTableRow(lines[i])) {
+                if (!isTableSeparator(lines[i])) {
+                    tableLines.push(lines[i]);
+                }
+                i++;
+            }
+            const formatted = formatTableMonospace(tableLines);
+            blocks.push({
+                type: "section",
+                text: { type: "mrkdwn", text: "```\n" + formatted + "\n```" },
+            });
+            continue;
+        }
+        // Headings → header block (plain_text, max 150 chars)
+        const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+        if (headingMatch) {
+            flushText();
+            // Strip markdown formatting and emojis for header blocks (plain_text only)
+            let headerText = headingMatch[2]
+                .replace(/\*\*(.+?)\*\*/g, "$1")
+                .replace(/__(.+?)__/g, "$1");
+            if (headerText.length > 150)
+                headerText = headerText.slice(0, 147) + "...";
+            blocks.push({
+                type: "header",
+                text: { type: "plain_text", text: headerText, emoji: true },
+            });
+            i++;
+            continue;
+        }
+        // Empty line — could be paragraph break
+        if (line.trim() === "") {
+            // If we have buffered text, flush as a section
+            if (textBuffer.length > 0 && textBuffer.some((l) => l.trim() !== "")) {
+                flushText();
+            }
+            i++;
+            continue;
+        }
+        // Regular text — buffer it
+        textBuffer.push(line);
+        i++;
+    }
+    flushText();
+    // Slack limits: max 50 blocks per message
+    if (blocks.length > 50) {
+        const truncated = blocks.slice(0, 49);
+        truncated.push({
+            type: "section",
+            text: { type: "mrkdwn", text: "_... (truncated)_" },
+        });
+        return truncated;
+    }
+    return blocks;
+}
+/** Plain-text fallback for notifications/accessibility */
+export function markdownToPlainText(md) {
+    return md
+        .replace(/^#{1,6}\s+/gm, "")
+        .replace(/\*\*(.+?)\*\*/g, "$1")
+        .replace(/__(.+?)__/g, "$1")
+        .replace(/~~(.+?)~~/g, "$1")
+        .replace(/^-{3,}$/gm, "")
+        .replace(/^\*{3,}$/gm, "")
+        .trim();
+}
+function isTableRow(line) {
+    const trimmed = line.trim();
+    return trimmed.startsWith("|") && trimmed.endsWith("|");
+}
+function isTableSeparator(line) {
+    return /^\|[\s\-:|]+\|$/.test(line.trim());
+}
+/** Format table rows as monospace-aligned text for code blocks */
+function formatTableMonospace(rows) {
+    if (rows.length === 0)
+        return "";
+    const parsed = rows.map((row) => row
+        .split("|")
+        .slice(1, -1)
+        .map((cell) => cell.trim()));
+    const colCount = parsed[0].length;
+    const widths = Array(colCount).fill(0);
+    for (const row of parsed) {
+        for (let c = 0; c < Math.min(row.length, colCount); c++) {
+            // Strip emoji for width calc (they render as ~2 chars in monospace)
+            const stripped = row[c].replace(/[\p{Emoji_Presentation}\p{Extended_Pictographic}]/gu, "  ");
+            widths[c] = Math.max(widths[c], stripped.length);
+        }
+    }
+    const out = [];
+    for (const cells of parsed) {
+        const padded = cells.map((cell, c) => {
+            const stripped = cell.replace(/[\p{Emoji_Presentation}\p{Extended_Pictographic}]/gu, "  ");
+            const padding = (widths[c] ?? 0) - stripped.length;
+            return cell + " ".repeat(Math.max(0, padding));
+        });
+        out.push(padded.join("  "));
+    }
+    // Add a separator line after the header
+    if (out.length > 1) {
+        const sep = widths.map((w) => "-".repeat(w)).join("  ");
+        out.splice(1, 0, sep);
+    }
+    return out.join("\n");
+}

package/dist/gateways/slack/handler.d.ts

@@ -0,0 +1,9 @@
+import type { AgentResult } from "../../agent/types.js";
+import type { SlackClient } from "./client.js";
+import type { SlackGatewayConfig } from "./types.js";
+export interface SlackHandler {
+    onJobResult(agentName: string, jobId: string, result: AgentResult, channelOverride?: string): Promise<void>;
+    onJobError(agentName: string, jobId: string, error: Error, channelOverride?: string): Promise<void>;
+    checkBudgetAlerts(agentName: string, budgetJson: string, channelOverride?: string): Promise<void>;
+}
+export declare function createSlackHandler(client: SlackClient, config: SlackGatewayConfig): SlackHandler;

package/dist/gateways/slack/handler.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { markdownToBlocks, markdownToPlainText } from "./format.js";
+import { BudgetStatusSchema } from "./types.js";
+import { createLogger } from "../../logger.js";
+function findBudgetToolResults(messages) {
+    const toolCallNames = new Map();
+    for (const msg of messages) {
+        if (msg.role === "assistant") {
+            for (const block of msg.content) {
+                if (block.type === "tool_call") {
+                    toolCallNames.set(block.id, block.name);
+                }
+            }
+        }
+    }
+    const results = [];
+    for (const msg of messages) {
+        if (msg.role === "tool_result" && toolCallNames.get(msg.tool_call_id) === "get_budget_status") {
+            results.push(msg.content);
+        }
+    }
+    return results;
+}
+const log = createLogger("slack:handler");
+export function createSlackHandler(client, config) {
+    function getChannel(agentName) {
+        return config.channels[agentName]?.channelId;
+    }
+    return {
+        async onJobResult(agentName, jobId, result, channelOverride) {
+            const channelId = channelOverride ?? getChannel(agentName);
+            if (!channelId) {
+                log.warn({ agent: agentName }, "no channel binding");
+                return;
+            }
+            try {
+                const blocks = [
+                    { type: "section", text: { type: "mrkdwn", text: `*[${jobId}]*` } },
+                    ...markdownToBlocks(result.text),
+                ];
+                const fallback = `[${jobId}] ${markdownToPlainText(result.text)}`;
+                await client.postMessage(channelId, fallback, blocks);
+            }
+            catch (err) {
+                log.error({ err, jobId, channelId }, "failed to post result");
+            }
+            // Auto-check budget alerts from raw tool results
+            for (const budgetJson of findBudgetToolResults(result.messages)) {
+                await this.checkBudgetAlerts(agentName, budgetJson, channelOverride);
+            }
+        },
+        async onJobError(agentName, jobId, error, channelOverride) {
+            const channelId = channelOverride ?? getChannel(agentName);
+            if (!channelId) {
+                log.warn({ agent: agentName }, "no channel binding");
+                return;
+            }
+            try {
+                await client.postMessage(channelId, `*[${jobId}] Error:* ${error.message}`);
+            }
+            catch (err) {
+                log.error({ err, jobId, channelId }, "failed to post error");
+            }
+        },
+        async checkBudgetAlerts(agentName, budgetJson, channelOverride) {
+            const channelId = channelOverride ?? getChannel(agentName);
+            if (!channelId) {
+                log.warn({ agent: agentName }, "no channel binding");
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(budgetJson);
+            }
+            catch {
+                log.warn({ agent: agentName }, "could not parse budget status");
+                return;
+            }
+            const result = z.array(BudgetStatusSchema).safeParse(parsed);
+            if (!result.success) {
+                log.warn({ agent: agentName, error: result.error.message }, "invalid budget status shape");
+                return;
+            }
+            const overBudget = result.data.filter((s) => s.percent > 100);
+            for (const item of overBudget) {
+                try {
+                    await client.postMessage(channelId, `*Budget Alert:* ${item.category} at $${item.spent.toLocaleString("en-US")} / $${item.limit.toLocaleString("en-US")} (${item.percent}%)`);
+                }
+                catch (err) {
+                    log.error({ err, category: item.category }, "failed to post budget alert");
+                }
+            }
+        },
+    };
+}

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

@@ -0,0 +1,16 @@
+import type { Config } from "../../config/schema.js";
+import type { AgentResult } from "../../agent/types.js";
+import type { Message } from "../../llm/types.js";
+export interface SlackGateway {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    onJobResult(agentName: string, jobId: string, result: AgentResult, channelOverride?: string): Promise<void>;
+    onJobError(agentName: string, jobId: string, error: Error, channelOverride?: string): Promise<void>;
+}
+export type AgentExecutor = (agentName: string, messages: Message[]) => Promise<AgentResult>;
+export interface SlackGatewayOptions {
+    botToken?: string;
+    appToken?: string;
+    onAgentRequest?: AgentExecutor;
+}
+export declare function createSlackGateway(config: Config, options?: SlackGatewayOptions): SlackGateway;

package/dist/gateways/slack/index.js

@@ -0,0 +1,102 @@
+import { createSlackClient } from "./client.js";
+import { createSlackHandler } from "./handler.js";
+import { createSlackListener } from "./listener.js";
+import { createThreadSessionManager } from "./sessions.js";
+import { markdownToBlocks, markdownToPlainText } from "./format.js";
+import { createLogger } from "../../logger.js";
+const log = createLogger("slack");
+export function createSlackGateway(config, options) {
+    const botToken = options?.botToken ?? process.env.SLACK_BOT_TOKEN;
+    const appToken = options?.appToken ?? process.env.SLACK_APP_TOKEN;
+    if (!botToken || !appToken) {
+        throw new Error("SLACK_BOT_TOKEN and SLACK_APP_TOKEN are required for Slack gateway");
+    }
+    const gatewayConfig = { channels: {} };
+    for (const [name, agent] of Object.entries(config.agents)) {
+        if (agent.slack) {
+            gatewayConfig.channels[name] = agent.slack;
+        }
+    }
+    const client = createSlackClient({ botToken, appToken });
+    const handler = createSlackHandler(client, gatewayConfig);
+    const sessions = createThreadSessionManager();
+    const executor = options?.onAgentRequest;
+    // Per-thread lock to serialize concurrent messages in the same thread
+    const threadLocks = new Map();
+    async function handleInbound(msg) {
+        if (!executor)
+            return;
+        log.info({ agent: msg.agentName, thread: msg.threadTs, text: msg.userText.slice(0, 80) }, "received message");
+        // Serialize per thread
+        const prev = threadLocks.get(msg.threadTs) ?? Promise.resolve();
+        const current = prev.then(() => processMessage(msg));
+        // Prevent rejected promise from blocking the next message in this thread.
+        // The actual error is propagated via `await current` below.
+        threadLocks.set(msg.threadTs, current.catch((err) => {
+            log.warn({ err, thread: msg.threadTs }, "thread lock caught error");
+        }));
+        await current;
+    }
+    async function processMessage(msg) {
+        if (!executor)
+            return;
+        const userMsg = { role: "user", content: msg.userText };
+        sessions.append(msg.threadTs, userMsg);
+        const messages = sessions.get(msg.threadTs);
+        try {
+            const start = Date.now();
+            log.info({ agent: msg.agentName, thread: msg.threadTs, history: messages.length }, "executing agent");
+            const result = await executor(msg.agentName, messages);
+            const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+            log.info({ agent: msg.agentName, thread: msg.threadTs, elapsed, tokens: result.usage.inputTokens + result.usage.outputTokens }, "agent completed");
+            // Replace session with full message history from agent
+            sessions.set(msg.threadTs, result.messages);
+            const text = result.text || "(completed with no text response)";
+            const blocks = markdownToBlocks(text);
+            const fallback = markdownToPlainText(text);
+            await client.postMessage(msg.channelId, fallback, blocks, msg.threadTs);
+            log.info({ agent: msg.agentName, thread: msg.threadTs }, "reply posted");
+        }
+        catch (err) {
+            log.error({ err, agent: msg.agentName, thread: msg.threadTs }, "error handling inbound message");
+            // Roll back user message on failure to avoid malformed conversation history
+            const current = sessions.get(msg.threadTs);
+            if (current.length > 0 && current[current.length - 1].role === "user") {
+                sessions.set(msg.threadTs, current.slice(0, -1));
+            }
+            try {
+                await client.postMessage(msg.channelId, "Sorry, I encountered an error processing your message. Please try again in a moment.", undefined, msg.threadTs);
+            }
+            catch (postErr) {
+                log.error({ err: postErr, thread: msg.threadTs }, "failed to send error reply");
+            }
+        }
+    }
+    // Eviction timer handle
+    let evictionTimer;
+    return {
+        async start() {
+            await client.start();
+            if (executor) {
+                createSlackListener(client.app, gatewayConfig, handleInbound);
+                // Evict stale threads every hour
+                evictionTimer = setInterval(() => {
+                    sessions.evict();
+                    for (const threadTs of threadLocks.keys()) {
+                        if (sessions.get(threadTs).length === 0) {
+                            threadLocks.delete(threadTs);
+                        }
+                    }
+                }, 60 * 60 * 1000);
+                evictionTimer.unref();
+            }
+        },
+        async stop() {
+            if (evictionTimer)
+                clearInterval(evictionTimer);
+            await client.stop();
+        },
+        onJobResult: (agentName, jobId, result, channelOverride) => handler.onJobResult(agentName, jobId, result, channelOverride),
+        onJobError: (agentName, jobId, error, channelOverride) => handler.onJobError(agentName, jobId, error, channelOverride),
+    };
+}

package/dist/gateways/slack/listener.d.ts

@@ -0,0 +1,10 @@
+import type { App } from "@slack/bolt";
+import type { SlackGatewayConfig } from "./types.js";
+export interface InboundMessage {
+    agentName: string;
+    userText: string;
+    threadTs: string;
+    channelId: string;
+}
+export type OnMessageCallback = (message: InboundMessage) => Promise<void>;
+export declare function createSlackListener(app: App, config: SlackGatewayConfig, onMessage: OnMessageCallback): void;

package/dist/gateways/slack/listener.js

@@ -0,0 +1,35 @@
+import { createLogger } from "../../logger.js";
+const log = createLogger("slack:listener");
+export function createSlackListener(app, config, onMessage) {
+    // Build reverse map: channelId → agentName
+    const channelToAgent = new Map();
+    for (const [agentName, binding] of Object.entries(config.channels)) {
+        channelToAgent.set(binding.channelId, agentName);
+    }
+    app.event("message", async (payload) => {
+        // Handle both Bolt's { event } wrapper and direct event (tests)
+        const msg = payload.event ?? payload;
+        // Filter out bot messages and subtypes (edits, deletes, etc.)
+        if (msg.bot_id || msg.subtype)
+            return;
+        if (!msg.text || typeof msg.text !== "string")
+            return;
+        const channelId = msg.channel;
+        const agentName = channelToAgent.get(channelId);
+        if (!agentName)
+            return;
+        // Use thread_ts if in a thread, otherwise use ts as the thread parent
+        const threadTs = msg.thread_ts ?? msg.ts;
+        // Fire-and-forget: don't await the handler so the Bolt event pipeline
+        // returns immediately. This prevents long-running agent loops from
+        // stalling WebSocket ping/pong and causing socket timeouts.
+        onMessage({
+            agentName,
+            userText: msg.text,
+            threadTs,
+            channelId,
+        }).catch((err) => {
+            log.error({ err, channelId }, "unhandled error processing message");
+        });
+    });
+}

package/dist/gateways/slack/sessions.d.ts

@@ -0,0 +1,11 @@
+import type { Message } from "../../llm/types.js";
+export interface ThreadSessionManager {
+    get(threadTs: string): Message[];
+    set(threadTs: string, messages: Message[]): void;
+    append(threadTs: string, message: Message): void;
+    evict(): void;
+}
+export interface ThreadSessionManagerOptions {
+    maxAgeMs?: number;
+}
+export declare function createThreadSessionManager(options?: ThreadSessionManagerOptions): ThreadSessionManager;

package/dist/gateways/slack/sessions.js

@@ -0,0 +1,32 @@
+const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
+export function createThreadSessionManager(options) {
+    const maxAgeMs = options?.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    const threads = new Map();
+    return {
+        get(threadTs) {
+            const entry = threads.get(threadTs);
+            return entry ? [...entry.messages] : [];
+        },
+        set(threadTs, messages) {
+            threads.set(threadTs, { messages: [...messages], lastActivity: Date.now() });
+        },
+        append(threadTs, message) {
+            const entry = threads.get(threadTs);
+            if (entry) {
+                entry.messages.push(message);
+                entry.lastActivity = Date.now();
+            }
+            else {
+                threads.set(threadTs, { messages: [message], lastActivity: Date.now() });
+            }
+        },
+        evict() {
+            const cutoff = Date.now() - maxAgeMs;
+            for (const [key, entry] of threads) {
+                if (entry.lastActivity < cutoff) {
+                    threads.delete(key);
+                }
+            }
+        },
+    };
+}

package/dist/gateways/slack/types.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import type { SlackBinding } from "../../config/schema.js";
+export declare const BudgetStatusSchema: z.ZodObject<{
+    category: z.ZodString;
+    spent: z.ZodNumber;
+    limit: z.ZodNumber;
+    percent: z.ZodNumber;
+}, z.core.$strip>;
+export type BudgetStatus = z.infer<typeof BudgetStatusSchema>;
+export interface SlackGatewayConfig {
+    /** Map of agent name to its slack binding (only agents with slack config) */
+    channels: Record<string, SlackBinding>;
+}

package/dist/gateways/slack/types.js

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export const BudgetStatusSchema = z.object({
+    category: z.string(),
+    spent: z.number(),
+    limit: z.number(),
+    percent: z.number(),
+});

package/dist/heartbeat/index.d.ts

@@ -0,0 +1,2 @@
+export { HeartbeatRunner, isHeartbeatSuppressed, isWithinActiveHours } from "./runner.js";
+export type { HeartbeatCallbacks } from "./runner.js";

package/dist/heartbeat/index.js

@@ -0,0 +1 @@
+export { HeartbeatRunner, isHeartbeatSuppressed, isWithinActiveHours } from "./runner.js";

package/dist/heartbeat/runner.d.ts

@@ -0,0 +1,31 @@
+import type { Config } from "../config/schema.js";
+import type { AgentRegistry } from "../multi/registry.js";
+import type { AgentResult } from "../agent/types.js";
+import type { UsageStore } from "../usage/store.js";
+export declare function isHeartbeatSuppressed(text: string): boolean;
+export declare function isWithinActiveHours(activeHours: {
+    start: number;
+    end: number;
+    timezone: string;
+} | undefined): boolean;
+export interface HeartbeatCallbacks {
+    onResult?: (agentName: string, result: AgentResult) => void;
+    onError?: (agentName: string, error: Error) => void;
+    onSuppressed?: (agentName: string) => void;
+}
+export declare class HeartbeatRunner {
+    private timers;
+    private running;
+    private config;
+    private agentRegistry;
+    private dataDir;
+    private skillsDir;
+    private usageStore?;
+    constructor(config: Config, agentRegistry: AgentRegistry, dataDir: string, skillsDir?: string, usageStore?: UsageStore);
+    getHeartbeatAgents(): string[];
+    private loadHeartbeatInstructions;
+    tick(agentName: string): Promise<AgentResult | undefined>;
+    start(callbacks?: HeartbeatCallbacks): void;
+    stop(): void;
+    isRunning(agentName: string): boolean;
+}