@alejandroroman/agent-kit 0.1.0

package/dist/config/schema.d.ts

@@ -0,0 +1,217 @@
+import { z } from "zod";
+declare const SandboxSchema: z.ZodObject<{
+    allowedCommands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowedPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+declare const ModelEntrySchema: z.ZodObject<{
+    model: z.ZodString;
+    alias: z.ZodString;
+}, z.core.$strip>;
+declare const MemorySchema: z.ZodObject<{
+    dbPath: z.ZodDefault<z.ZodString>;
+    ollamaEndpoint: z.ZodDefault<z.ZodString>;
+    ollamaModel: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+declare const UsageSchema: z.ZodObject<{
+    dbPath: z.ZodDefault<z.ZodString>;
+    apiPort: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+declare const WebSearchConfigSchema: z.ZodOptional<z.ZodObject<{
+    provider: z.ZodDefault<z.ZodEnum<{
+        brave: "brave";
+        grok: "grok";
+    }>>;
+    grok: z.ZodOptional<z.ZodObject<{
+        model: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+declare const SlackBindingSchema: z.ZodObject<{
+    channelId: z.ZodString;
+    channelName: z.ZodString;
+}, z.core.$strip>;
+declare const SpawnTargetSchema: z.ZodObject<{
+    agent: z.ZodString;
+    tool: z.ZodString;
+    description: z.ZodString;
+}, z.core.$strip>;
+declare const HeartbeatSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    intervalMinutes: z.ZodDefault<z.ZodNumber>;
+    model: z.ZodOptional<z.ZodString>;
+    maxIterations: z.ZodOptional<z.ZodNumber>;
+    activeHours: z.ZodOptional<z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        timezone: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    slack: z.ZodOptional<z.ZodObject<{
+        channelId: z.ZodString;
+        channelName: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const AgentSchema: z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodString>;
+    emoji: z.ZodOptional<z.ZodString>;
+    avatar: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    spawn_only: z.ZodDefault<z.ZodBoolean>;
+    can_spawn: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        agent: z.ZodString;
+        tool: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strip>>>;
+    maxIterations: z.ZodOptional<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    sandbox: z.ZodOptional<z.ZodObject<{
+        allowedCommands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allowedPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    slack: z.ZodOptional<z.ZodObject<{
+        channelId: z.ZodString;
+        channelName: z.ZodString;
+    }, z.core.$strip>>;
+    heartbeat: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        intervalMinutes: z.ZodDefault<z.ZodNumber>;
+        model: z.ZodOptional<z.ZodString>;
+        maxIterations: z.ZodOptional<z.ZodNumber>;
+        activeHours: z.ZodOptional<z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+            timezone: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>;
+        slack: z.ZodOptional<z.ZodObject<{
+            channelId: z.ZodString;
+            channelName: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    webSearch: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodDefault<z.ZodEnum<{
+            brave: "brave";
+            grok: "grok";
+        }>>;
+        grok: z.ZodOptional<z.ZodObject<{
+            model: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const CronJobSchema: z.ZodObject<{
+    id: z.ZodString;
+    agent: z.ZodString;
+    schedule: z.ZodString;
+    prompt: z.ZodString;
+    enabled: z.ZodBoolean;
+    slack: z.ZodOptional<z.ZodObject<{
+        channelId: z.ZodString;
+        channelName: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ConfigSchema: z.ZodObject<{
+    models: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        model: z.ZodString;
+        alias: z.ZodString;
+    }, z.core.$strip>>>;
+    defaults: z.ZodDefault<z.ZodObject<{
+        model: z.ZodDefault<z.ZodString>;
+        maxTokens: z.ZodDefault<z.ZodNumber>;
+        maxIterations: z.ZodDefault<z.ZodNumber>;
+        compactionThreshold: z.ZodDefault<z.ZodNumber>;
+        commandTimeout: z.ZodDefault<z.ZodNumber>;
+        maxToolResultSize: z.ZodDefault<z.ZodNumber>;
+        sandbox: z.ZodOptional<z.ZodObject<{
+            allowedCommands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            allowedPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        memory: z.ZodOptional<z.ZodObject<{
+            dbPath: z.ZodDefault<z.ZodString>;
+            ollamaEndpoint: z.ZodDefault<z.ZodString>;
+            ollamaModel: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>;
+        usage: z.ZodOptional<z.ZodObject<{
+            dbPath: z.ZodDefault<z.ZodString>;
+            apiPort: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        webSearch: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodDefault<z.ZodEnum<{
+                brave: "brave";
+                grok: "grok";
+            }>>;
+            grok: z.ZodOptional<z.ZodObject<{
+                model: z.ZodDefault<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        displayName: z.ZodOptional<z.ZodString>;
+        emoji: z.ZodOptional<z.ZodString>;
+        avatar: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        spawn_only: z.ZodDefault<z.ZodBoolean>;
+        can_spawn: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            agent: z.ZodString;
+            tool: z.ZodString;
+            description: z.ZodString;
+        }, z.core.$strip>>>;
+        maxIterations: z.ZodOptional<z.ZodNumber>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        sandbox: z.ZodOptional<z.ZodObject<{
+            allowedCommands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            allowedPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        slack: z.ZodOptional<z.ZodObject<{
+            channelId: z.ZodString;
+            channelName: z.ZodString;
+        }, z.core.$strip>>;
+        heartbeat: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            intervalMinutes: z.ZodDefault<z.ZodNumber>;
+            model: z.ZodOptional<z.ZodString>;
+            maxIterations: z.ZodOptional<z.ZodNumber>;
+            activeHours: z.ZodOptional<z.ZodObject<{
+                start: z.ZodNumber;
+                end: z.ZodNumber;
+                timezone: z.ZodDefault<z.ZodString>;
+            }, z.core.$strip>>;
+            slack: z.ZodOptional<z.ZodObject<{
+                channelId: z.ZodString;
+                channelName: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        webSearch: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodDefault<z.ZodEnum<{
+                brave: "brave";
+                grok: "grok";
+            }>>;
+            grok: z.ZodOptional<z.ZodObject<{
+                model: z.ZodDefault<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    cron: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        agent: z.ZodString;
+        schedule: z.ZodString;
+        prompt: z.ZodString;
+        enabled: z.ZodBoolean;
+        slack: z.ZodOptional<z.ZodObject<{
+            channelId: z.ZodString;
+            channelName: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type Config = z.infer<typeof ConfigSchema>;
+export type AgentDef = z.infer<typeof AgentSchema>;
+export type CronJobDef = z.infer<typeof CronJobSchema>;
+export type SandboxDef = z.infer<typeof SandboxSchema>;
+export type SlackBinding = z.infer<typeof SlackBindingSchema>;
+export type ModelEntry = z.infer<typeof ModelEntrySchema>;
+export type MemoryConfig = z.infer<typeof MemorySchema>;
+export type UsageConfig = z.infer<typeof UsageSchema>;
+export type SpawnTarget = z.infer<typeof SpawnTargetSchema>;
+export type HeartbeatDef = z.infer<typeof HeartbeatSchema>;
+export type WebSearchConfig = z.infer<typeof WebSearchConfigSchema>;
+export {};

package/dist/config/schema.js

@@ -0,0 +1,159 @@
+import { z } from "zod";
+const modelPattern = /^[a-z]+:.+$/;
+const SandboxSchema = z.object({
+    allowedCommands: z.array(z.string().min(1)).min(1).optional(),
+    allowedPaths: z.array(z.string().min(1)).min(1).optional(),
+}).refine((s) => s.allowedCommands !== undefined || s.allowedPaths !== undefined, { message: "Sandbox must specify at least allowedCommands or allowedPaths" });
+const ModelEntrySchema = z.object({
+    model: z.string().regex(modelPattern, "Model must be in 'provider:model-name' format"),
+    alias: z.string().min(1),
+});
+const MemorySchema = z.object({
+    dbPath: z.string().min(1).default("~/.agent-kit/memory.db"),
+    ollamaEndpoint: z.string().min(1).default("http://localhost:11434"),
+    ollamaModel: z.string().min(1).default("all-minilm:l6-v2"),
+});
+const UsageSchema = z.object({
+    dbPath: z.string().min(1).default("~/.agent-kit/usage.db"),
+    apiPort: z.number().positive().default(7878),
+});
+const WebSearchConfigSchema = z.object({
+    provider: z.enum(["brave", "grok"]).default("brave"),
+    grok: z.object({
+        model: z.string().min(1).default("grok-4-1-fast"),
+    }).optional(),
+}).optional();
+const DefaultsSchema = z.object({
+    model: z.string().min(1).default("anthropic:claude-sonnet-4-6"),
+    maxTokens: z.number().positive().default(4096),
+    maxIterations: z.number().positive().int().default(20),
+    compactionThreshold: z.number().positive().default(100_000),
+    commandTimeout: z.number().positive().default(30),
+    maxToolResultSize: z.number().positive().default(8192),
+    sandbox: SandboxSchema.optional(),
+    memory: MemorySchema.optional(),
+    usage: UsageSchema.optional(),
+    webSearch: WebSearchConfigSchema,
+});
+const DefaultsWithDefault = DefaultsSchema.default({
+    model: "anthropic:claude-sonnet-4-6",
+    maxTokens: 4096,
+    maxIterations: 20,
+    compactionThreshold: 100_000,
+    commandTimeout: 30,
+    maxToolResultSize: 8192,
+    sandbox: undefined,
+    usage: undefined,
+    webSearch: undefined,
+});
+const SlackBindingSchema = z.object({
+    channelId: z.string().min(1),
+    channelName: z.string().min(1),
+});
+const SpawnTargetSchema = z.object({
+    agent: z.string().min(1),
+    tool: z.string().min(1),
+    description: z.string().min(1),
+});
+const ActiveHoursSchema = z.object({
+    start: z.number().int().min(0).max(23),
+    end: z.number().int().min(0).max(23),
+    timezone: z.string().min(1).default("America/Chicago").refine((tz) => {
+        try {
+            Intl.DateTimeFormat(undefined, { timeZone: tz });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, { message: "must be a valid IANA timezone (e.g., 'America/Chicago', 'UTC')" }),
+}).refine((h) => h.start !== h.end, { message: "start and end must differ" });
+const HeartbeatSchema = z.object({
+    enabled: z.boolean().default(true),
+    intervalMinutes: z.number().positive().int().default(30),
+    model: z.string().min(1).optional(),
+    maxIterations: z.number().positive().int().optional(),
+    activeHours: ActiveHoursSchema.optional(),
+    slack: SlackBindingSchema.optional(),
+});
+const AgentSchema = z.object({
+    displayName: z.string().min(1).optional(),
+    emoji: z.string().min(1).optional(),
+    avatar: z.string().url().optional(),
+    model: z.string().min(1).optional(),
+    tools: z.array(z.string()).default([]),
+    skills: z.array(z.string().min(1)).default([]),
+    spawn_only: z.boolean().default(false),
+    can_spawn: z.array(SpawnTargetSchema).default([]),
+    maxIterations: z.number().positive().int().optional(),
+    maxTokens: z.number().positive().optional(),
+    sandbox: SandboxSchema.optional(),
+    slack: SlackBindingSchema.optional(),
+    heartbeat: HeartbeatSchema.optional(),
+    webSearch: WebSearchConfigSchema,
+});
+const CronJobSchema = z.object({
+    id: z.string().min(1),
+    agent: z.string().min(1),
+    schedule: z.string().min(1),
+    prompt: z.string().min(1),
+    enabled: z.boolean(),
+    slack: SlackBindingSchema.optional(),
+});
+export const ConfigSchema = z
+    .object({
+    models: z.array(ModelEntrySchema).optional(),
+    defaults: DefaultsWithDefault,
+    agents: z.record(z.string(), AgentSchema).default({}),
+    cron: z.array(CronJobSchema).default([]),
+})
+    .refine((config) => config.cron.every((job) => job.agent in config.agents), { message: "Cron job references an agent not defined in agents" })
+    .refine((config) => {
+    if (!config.models)
+        return true;
+    const aliases = config.models.map((m) => m.alias);
+    return new Set(aliases).size === aliases.length;
+}, { message: "Duplicate alias in models" })
+    .refine((config) => {
+    if (!config.models)
+        return true;
+    const modelStrings = config.models.map((m) => m.model);
+    return new Set(modelStrings).size === modelStrings.length;
+}, { message: "Duplicate model string in models" })
+    .refine((config) => {
+    if (!config.models)
+        return true;
+    const aliases = new Set(config.models.map((m) => m.alias));
+    return aliases.has(config.defaults.model);
+}, { message: "defaults.model must reference a valid alias when models is defined" })
+    .refine((config) => {
+    if (!config.models)
+        return true;
+    const aliases = new Set(config.models.map((m) => m.alias));
+    return Object.values(config.agents).every((agent) => !agent.model || aliases.has(agent.model));
+}, { message: "Agent model must reference a valid alias when models is defined" })
+    .refine((config) => {
+    if (!config.models)
+        return true;
+    const aliases = new Set(config.models.map((m) => m.alias));
+    return Object.values(config.agents).every((agent) => !agent.heartbeat?.model || aliases.has(agent.heartbeat.model));
+}, { message: "Heartbeat model must reference a valid alias when models is defined" })
+    .refine((config) => {
+    for (const agent of Object.values(config.agents)) {
+        for (const target of agent.can_spawn) {
+            if (!(target.agent in config.agents))
+                return false;
+        }
+    }
+    return true;
+}, { message: "can_spawn references an agent not defined in agents" })
+    .refine((config) => {
+    for (const agent of Object.values(config.agents)) {
+        for (const target of agent.can_spawn) {
+            const targetAgent = config.agents[target.agent];
+            if (targetAgent && !targetAgent.spawn_only)
+                return false;
+        }
+    }
+    return true;
+}, { message: "can_spawn target must have spawn_only: true" });

package/dist/cron/scheduler.d.ts

@@ -0,0 +1,22 @@
+import type { Config, CronJobDef } from "../config/schema.js";
+import type { ToolRegistry } from "../tools/registry.js";
+import type { AgentResult } from "../agent/types.js";
+import type { AgentRegistry } from "../multi/registry.js";
+import type { UsageStore } from "../usage/store.js";
+export declare class CronScheduler {
+    private tasks;
+    private config;
+    private toolRegistry;
+    private agentRegistry;
+    private dataDir;
+    private skillsDir;
+    private usageStore?;
+    constructor(config: Config, toolRegistry: ToolRegistry, agentRegistry: AgentRegistry, dataDir: string, skillsDir?: string, usageStore?: UsageStore);
+    getJobs(): CronJobDef[];
+    runJob(jobId: string): Promise<AgentResult | undefined>;
+    start(callbacks?: {
+        onResult?: (jobId: string, agentName: string, result: AgentResult) => void;
+        onError?: (jobId: string, agentName: string, error: Error) => void;
+    }): void;
+    stop(): void;
+}

package/dist/cron/scheduler.js

@@ -0,0 +1,115 @@
+import cron from "node-cron";
+import { runAgentLoop } from "../agent/loop.js";
+import { setupAgentSession } from "../agent/setup.js";
+import { resolveAgent, resolveWebSearch } from "../config/resolve.js";
+import { createBuiltinRegistry } from "../tools/builtin/index.js";
+import { registerSpawnWrappers } from "../tools/builtin/spawn.js";
+import * as path from "path";
+import { createActivateSkillTool } from "../skills/index.js";
+import { createLogger } from "../logger.js";
+import { dateContext } from "../text.js";
+const log = createLogger("cron");
+export class CronScheduler {
+    tasks = [];
+    config;
+    toolRegistry;
+    agentRegistry;
+    dataDir;
+    skillsDir;
+    usageStore;
+    constructor(config, toolRegistry, agentRegistry, dataDir, skillsDir, usageStore) {
+        this.config = config;
+        this.toolRegistry = toolRegistry;
+        this.agentRegistry = agentRegistry;
+        this.dataDir = dataDir;
+        this.skillsDir = skillsDir ?? path.join(process.cwd(), "skills");
+        this.usageStore = usageStore;
+    }
+    getJobs() {
+        return this.config.cron;
+    }
+    async runJob(jobId) {
+        const job = this.config.cron.find((j) => j.id === jobId);
+        if (!job)
+            return undefined;
+        // Resolve sandbox for this job's agent
+        const agentDef = this.config.agents[job.agent];
+        const sandbox = agentDef?.sandbox ?? this.config.defaults.sandbox;
+        const memoryConfig = this.config.defaults.memory;
+        const jobRegistry = createBuiltinRegistry({
+            allowedCommands: sandbox?.allowedCommands,
+            allowedPaths: sandbox?.allowedPaths,
+            memoryConfig,
+            webSearch: resolveWebSearch(job.agent, this.config),
+        });
+        const resolved = resolveAgent(job.agent, this.config, jobRegistry, this.skillsDir);
+        // Skills setup for this job
+        const promptFragments = [];
+        let skillsIndex = "";
+        if (resolved.skills.length > 0) {
+            const ctx = {
+                manifests: resolved.skills,
+                skillsDir: this.skillsDir,
+                toolRegistry: jobRegistry,
+                promptFragments,
+                activatedSkills: new Set(),
+            };
+            jobRegistry.register(createActivateSkillTool(ctx));
+            skillsIndex = "\n\nYou have the following skills available:\n\n"
+                + resolved.skills.map((s) => `- **${s.name}**: ${s.description}`).join("\n")
+                + "\n\nTo use a skill, call the `activate_skill` tool with the skill name.";
+        }
+        // Spawn wrapper registration
+        if (resolved.canSpawn.length > 0) {
+            registerSpawnWrappers(resolved.canSpawn, this.config, this.agentRegistry, jobRegistry, this.usageStore);
+        }
+        const sessionId = `cron-${job.id}`;
+        const { soul, session } = setupAgentSession(this.dataDir, job.agent, sessionId);
+        const userMsg = { role: "user", content: job.prompt };
+        session.append(userMsg);
+        const systemPrompt = [soul, dateContext(), skillsIndex, ...promptFragments]
+            .filter(Boolean)
+            .join("\n\n") || undefined;
+        const result = await runAgentLoop([userMsg], {
+            model: resolved.model,
+            fallbacks: resolved.fallbacks,
+            systemPrompt,
+            toolRegistry: jobRegistry,
+            maxIterations: resolved.maxIterations,
+            compactionThreshold: resolved.compactionThreshold,
+            maxToolResultSize: resolved.maxToolResultSize,
+            agentName: job.agent,
+            usageStore: this.usageStore,
+            source: "cron",
+        });
+        const lastMsg = result.messages[result.messages.length - 1];
+        session.append(lastMsg);
+        return result;
+    }
+    start(callbacks) {
+        for (const job of this.config.cron) {
+            if (!job.enabled)
+                continue;
+            const task = cron.schedule(job.schedule, async () => {
+                log.info({ jobId: job.id }, "running job");
+                try {
+                    const result = await this.runJob(job.id);
+                    if (result && callbacks?.onResult)
+                        callbacks.onResult(job.id, job.agent, result);
+                }
+                catch (err) {
+                    const error = err instanceof Error ? err : new Error(String(err));
+                    log.error({ err: error, jobId: job.id }, "job failed");
+                    if (callbacks?.onError)
+                        callbacks.onError(job.id, job.agent, error);
+                }
+            });
+            this.tasks.push(task);
+        }
+    }
+    stop() {
+        for (const task of this.tasks)
+            task.stop();
+        this.tasks = [];
+    }
+}

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

@@ -0,0 +1,13 @@
+export interface SlackClientOptions {
+    botToken: string;
+    appToken: string;
+}
+export interface SlackClient {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    postMessage(channelId: string, text: string, blocks?: unknown[], threadTs?: string): Promise<{
+        ok: boolean;
+    }>;
+    app: import("@slack/bolt").App;
+}
+export declare function createSlackClient(options: SlackClientOptions): SlackClient;

package/dist/gateways/slack/client.js

@@ -0,0 +1,44 @@
+import { App } from "@slack/bolt";
+const MAX_MESSAGE_LENGTH = 4000;
+const TRUNCATION_SUFFIX = "\n... (truncated)";
+export function createSlackClient(options) {
+    const app = new App({
+        token: options.botToken,
+        appToken: options.appToken,
+        socketMode: true,
+    });
+    // Increase ping timeouts on the underlying SocketModeClient to avoid
+    // spurious "pong wasn't received" warnings during long-running agent jobs.
+    // The Bolt App doesn't expose these options, so we patch via the receiver.
+    const internal = app;
+    if (internal.receiver?.client) {
+        internal.receiver.client.clientPingTimeoutMS = 30_000;
+        internal.receiver.client.serverPingTimeoutMS = 60_000;
+    }
+    function truncate(text) {
+        if (text.length <= MAX_MESSAGE_LENGTH)
+            return text;
+        return text.slice(0, MAX_MESSAGE_LENGTH - TRUNCATION_SUFFIX.length) + TRUNCATION_SUFFIX;
+    }
+    return {
+        app,
+        async start() {
+            await app.start();
+        },
+        async stop() {
+            await app.stop();
+        },
+        async postMessage(channelId, text, blocks, threadTs) {
+            const result = await app.client.chat.postMessage({
+                channel: channelId,
+                text: truncate(text) || " ",
+                ...(blocks && { blocks }),
+                ...(threadTs && { thread_ts: threadTs }),
+            });
+            if (!result.ok) {
+                throw new Error(`Slack postMessage failed for channel ${channelId}`);
+            }
+            return { ok: true };
+        },
+    };
+}

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

@@ -0,0 +1,30 @@
+/**
+ * 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
+ */
+export interface SlackBlock {
+    type: string;
+    text?: {
+        type: string;
+        text: string;
+        emoji?: boolean;
+    };
+    elements?: Array<{
+        type: string;
+        text?: string;
+        elements?: unknown[];
+    }>;
+    [key: string]: unknown;
+}
+/** Convert markdown to Slack mrkdwn inline formatting */
+export declare function convertInlineFormatting(text: string): string;
+/** Convert full markdown string to Slack Block Kit blocks */
+export declare function markdownToBlocks(md: string): SlackBlock[];
+/** Plain-text fallback for notifications/accessibility */
+export declare function markdownToPlainText(md: string): string;