@alejandroroman/agent-kit 0.1.3 → 0.2.0

package/dist/config/schema.d.ts

@@ -56,6 +56,7 @@ declare const AgentSchema: z.ZodObject<{
     model: z.ZodOptional<z.ZodString>;
     tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
     skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    autoActivateSkills: z.ZodDefault<z.ZodBoolean>;
     spawn_only: z.ZodDefault<z.ZodBoolean>;
     can_spawn: z.ZodDefault<z.ZodArray<z.ZodObject<{
         agent: z.ZodString;
@@ -150,6 +151,7 @@ export declare const ConfigSchema: z.ZodObject<{
         model: z.ZodOptional<z.ZodString>;
         tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
         skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        autoActivateSkills: z.ZodDefault<z.ZodBoolean>;
         spawn_only: z.ZodDefault<z.ZodBoolean>;
         can_spawn: z.ZodDefault<z.ZodArray<z.ZodObject<{
             agent: z.ZodString;

package/dist/config/schema.js

@@ -83,6 +83,7 @@ const AgentSchema = z.object({
     model: z.string().min(1).optional(),
     tools: z.array(z.string()).default([]),
     skills: z.array(z.string().min(1)).default([]),
+    autoActivateSkills: z.boolean().default(false),
     spawn_only: z.boolean().default(false),
     can_spawn: z.array(SpawnTargetSchema).default([]),
     maxIterations: z.number().positive().int().optional(),

package/dist/config/writer.d.ts

@@ -0,0 +1,18 @@
+import { EventEmitter } from "events";
+export declare class ConfigWriter extends EventEmitter {
+    private configPath;
+    private lockPromise;
+    private watcher?;
+    private debounceTimer?;
+    private lastSelfWriteMs;
+    constructor(configPath: string);
+    /** Read the current config from disk (fresh read, no cache). */
+    read(): Record<string, any>;
+    /** Write config atomically (temp file + rename). Emits config:changed. */
+    write(config: Record<string, any>): void;
+    /** Watch the config file for external changes. Debounced, ignores self-writes. */
+    watch(): void;
+    stopWatching(): void;
+    /** Mutex-protected read-modify-write. The callback mutates config in place. */
+    mutate(fn: (config: Record<string, any>) => void): Promise<void>;
+}

package/dist/config/writer.js

@@ -0,0 +1,85 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { EventEmitter } from "events";
+import { createLogger } from "../logger.js";
+const log = createLogger("config:writer");
+export class ConfigWriter extends EventEmitter {
+    configPath;
+    lockPromise = Promise.resolve();
+    watcher;
+    debounceTimer;
+    lastSelfWriteMs = 0;
+    constructor(configPath) {
+        super();
+        this.configPath = configPath;
+    }
+    /** Read the current config from disk (fresh read, no cache). */
+    read() {
+        const raw = fs.readFileSync(this.configPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    /** Write config atomically (temp file + rename). Emits config:changed. */
+    write(config) {
+        const tmp = path.join(path.dirname(this.configPath), `.agent-kit-${process.pid}-${Date.now()}.tmp`);
+        fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + os.EOL);
+        try {
+            fs.renameSync(tmp, this.configPath);
+        }
+        catch (err) {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch { /* ignore cleanup error */ }
+            throw err;
+        }
+        log.info("config written");
+        this.lastSelfWriteMs = Date.now();
+        this.emit("config:changed", config);
+    }
+    /** Watch the config file for external changes. Debounced, ignores self-writes. */
+    watch() {
+        if (this.watcher)
+            return;
+        const DEBOUNCE_MS = 250;
+        const SELF_WRITE_WINDOW_MS = 1000;
+        this.watcher = fs.watch(this.configPath, () => {
+            if (this.debounceTimer)
+                clearTimeout(this.debounceTimer);
+            this.debounceTimer = setTimeout(() => {
+                // Ignore fs events triggered by our own write()
+                if (Date.now() - this.lastSelfWriteMs < SELF_WRITE_WINDOW_MS)
+                    return;
+                try {
+                    const config = this.read();
+                    log.info("external config change detected");
+                    this.emit("config:changed", config);
+                }
+                catch (err) {
+                    log.error({ err }, "failed to read config after external change");
+                }
+            }, DEBOUNCE_MS);
+        });
+    }
+    stopWatching() {
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        this.watcher?.close();
+        this.watcher = undefined;
+    }
+    /** Mutex-protected read-modify-write. The callback mutates config in place. */
+    async mutate(fn) {
+        const prev = this.lockPromise;
+        let resolve;
+        this.lockPromise = new Promise((r) => { resolve = r; });
+        await prev;
+        try {
+            const config = this.read();
+            fn(config);
+            this.write(config);
+        }
+        finally {
+            resolve();
+        }
+    }
+}

package/dist/cron/scheduler.d.ts

@@ -2,6 +2,7 @@ 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 { ConfigWriter } from "../config/writer.js";
 import type { UsageStore } from "../usage/store.js";
 export declare class CronScheduler {
     private tasks;
@@ -11,12 +12,14 @@ export declare class CronScheduler {
     private dataDir;
     private skillsDir;
     private usageStore?;
-    constructor(config: Config, toolRegistry: ToolRegistry, agentRegistry: AgentRegistry, dataDir: string, skillsDir?: string, usageStore?: UsageStore);
+    private configWriter?;
+    constructor(config: Config, toolRegistry: ToolRegistry, agentRegistry: AgentRegistry, dataDir: string, skillsDir?: string, usageStore?: UsageStore, configWriter?: ConfigWriter);
     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;
+    reload(newConfig: Config): void;
     stop(): void;
 }

package/dist/cron/scheduler.js

@@ -4,10 +4,13 @@ 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 { createUpdateAgentConfigTool, createManageCronTool } from "../tools/builtin/self-config.js";
 import * as path from "path";
-import { createActivateSkillTool } from "../skills/index.js";
+import { createActivateSkillTool, preActivateSkills } from "../skills/index.js";
 import { createLogger } from "../logger.js";
 import { dateContext } from "../text.js";
+import { context, trace, SpanStatusCode } from "@opentelemetry/api";
+import { getTracer, ATTR } from "../telemetry/index.js";
 const log = createLogger("cron");
 export class CronScheduler {
     tasks = [];
@@ -17,13 +20,15 @@ export class CronScheduler {
     dataDir;
     skillsDir;
     usageStore;
-    constructor(config, toolRegistry, agentRegistry, dataDir, skillsDir, usageStore) {
+    configWriter;
+    constructor(config, toolRegistry, agentRegistry, dataDir, skillsDir, usageStore, configWriter) {
         this.config = config;
         this.toolRegistry = toolRegistry;
         this.agentRegistry = agentRegistry;
         this.dataDir = dataDir;
         this.skillsDir = skillsDir ?? path.join(process.cwd(), "skills");
         this.usageStore = usageStore;
+        this.configWriter = configWriter;
     }
     getJobs() {
         return this.config.cron;
@@ -32,59 +37,96 @@ export class CronScheduler {
         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 tracer = getTracer("cron");
+        const span = tracer.startSpan("source.cron", {
+            attributes: {
+                [ATTR.JOB_ID]: job.id,
+                [ATTR.AGENT]: job.agent,
+                [ATTR.SCHEDULE]: job.schedule,
+                [ATTR.SOURCE]: "cron",
+            },
         });
-        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.";
+        const spanCtx = trace.setSpan(context.active(), span);
+        try {
+            return await context.with(spanCtx, async () => {
+                // 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(),
+                    };
+                    const activateTool = createActivateSkillTool(ctx);
+                    jobRegistry.register(activateTool);
+                    if (resolved.autoActivateSkills) {
+                        skillsIndex = await preActivateSkills(ctx, activateTool, log);
+                    }
+                    else {
+                        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);
+                }
+                // Self-config tool registration
+                if (this.configWriter && agentDef) {
+                    if (agentDef.tools.includes("update_agent_config")) {
+                        jobRegistry.register(createUpdateAgentConfigTool(job.agent, this.configWriter));
+                    }
+                    if (agentDef.tools.includes("manage_cron")) {
+                        jobRegistry.register(createManageCronTool(job.agent, this.configWriter));
+                    }
+                }
+                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;
+            });
         }
-        // Spawn wrapper registration
-        if (resolved.canSpawn.length > 0) {
-            registerSpawnWrappers(resolved.canSpawn, this.config, this.agentRegistry, jobRegistry, this.usageStore);
+        catch (err) {
+            span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+            span.recordException(err instanceof Error ? err : new Error(String(err)));
+            throw err;
+        }
+        finally {
+            span.end();
         }
-        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) {
@@ -107,6 +149,11 @@ export class CronScheduler {
             this.tasks.push(task);
         }
     }
+    reload(newConfig) {
+        this.stop();
+        this.config = newConfig;
+        log.info({ jobs: newConfig.cron.length }, "config reloaded");
+    }
     stop() {
         for (const task of this.tasks)
             task.stop();

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

@@ -8,6 +8,7 @@ export interface SlackClient {
     postMessage(channelId: string, text: string, blocks?: unknown[], threadTs?: string): Promise<{
         ok: boolean;
     }>;
+    downloadFile(urlPrivateDownload: string): Promise<Buffer>;
     app: import("@slack/bolt").App;
 }
 export declare function createSlackClient(options: SlackClientOptions): SlackClient;

package/dist/gateways/slack/client.js

@@ -28,6 +28,15 @@ export function createSlackClient(options) {
         async stop() {
             await app.stop();
         },
+        async downloadFile(urlPrivateDownload) {
+            const response = await fetch(urlPrivateDownload, {
+                headers: { Authorization: `Bearer ${options.botToken}` },
+            });
+            if (!response.ok) {
+                throw new Error(`Failed to download Slack file: ${response.status} ${response.statusText}`);
+            }
+            return Buffer.from(await response.arrayBuffer());
+        },
         async postMessage(channelId, text, blocks, threadTs) {
             const result = await app.client.chat.postMessage({
                 channel: channelId,

package/dist/gateways/slack/handler.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { extractUserText } from "../../llm/types.js";
 import { markdownToBlocks, markdownToPlainText } from "./format.js";
 import { BudgetStatusSchema } from "./types.js";
 import { createLogger } from "../../logger.js";
@@ -16,7 +17,7 @@ function findBudgetToolResults(messages) {
     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);
+            results.push(extractUserText(msg.content));
         }
     }
     return results;

package/dist/gateways/slack/index.js

@@ -4,7 +4,25 @@ import { createSlackListener } from "./listener.js";
 import { createThreadSessionManager } from "./sessions.js";
 import { markdownToBlocks, markdownToPlainText } from "./format.js";
 import { createLogger } from "../../logger.js";
+import { context, trace, SpanStatusCode } from "@opentelemetry/api";
+import { getTracer, ATTR } from "../../telemetry/index.js";
 const log = createLogger("slack");
+function buildUserMessage(msg) {
+    if (!msg.files?.length) {
+        return { role: "user", content: msg.userText };
+    }
+    const blocks = [];
+    if (msg.userText) {
+        blocks.push({ type: "text", text: msg.userText });
+    }
+    for (const file of msg.files) {
+        blocks.push({
+            type: "image",
+            source: { type: "base64", media_type: file.mimetype, data: file.base64 },
+        });
+    }
+    return { role: "user", content: blocks };
+}
 export function createSlackGateway(config, options) {
     const botToken = options?.botToken ?? process.env.SLACK_BOT_TOKEN;
     const appToken = options?.appToken ?? process.env.SLACK_APP_TOKEN;
@@ -40,37 +58,65 @@ export function createSlackGateway(config, options) {
     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));
-            }
+        const tracer = getTracer("slack");
+        const span = tracer.startSpan("source.slack", {
+            attributes: {
+                [ATTR.CHANNEL]: msg.channelId,
+                [ATTR.AGENT]: msg.agentName,
+                [ATTR.THREAD_TS]: msg.threadTs,
+                [ATTR.SOURCE]: "slack",
+            },
+        });
+        const spanCtx = trace.setSpan(context.active(), span);
+        await context.with(spanCtx, async () => {
+            const userMsg = buildUserMessage(msg);
+            sessions.append(msg.threadTs, userMsg);
+            const messages = sessions.get(msg.threadTs);
             try {
-                await client.postMessage(msg.channelId, "Sorry, I encountered an error processing your message. Please try again in a moment.", undefined, msg.threadTs);
+                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);
+                const postSpan = tracer.startSpan("slack.post", {}, spanCtx);
+                try {
+                    await client.postMessage(msg.channelId, fallback, blocks, msg.threadTs);
+                    log.info({ agent: msg.agentName, thread: msg.threadTs }, "reply posted");
+                }
+                catch (postErr) {
+                    postSpan.setStatus({ code: SpanStatusCode.ERROR, message: String(postErr) });
+                    postSpan.recordException(postErr instanceof Error ? postErr : new Error(String(postErr)));
+                    throw postErr;
+                }
+                finally {
+                    postSpan.end();
+                }
             }
-            catch (postErr) {
-                log.error({ err: postErr, thread: msg.threadTs }, "failed to send error reply");
+            catch (err) {
+                span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+                span.recordException(err instanceof Error ? err : new Error(String(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");
+                }
             }
-        }
+            finally {
+                span.end();
+            }
+        });
     }
     // Eviction timer handle
     let evictionTimer;
@@ -78,7 +124,7 @@ export function createSlackGateway(config, options) {
         async start() {
             await client.start();
             if (executor) {
-                createSlackListener(client.app, gatewayConfig, handleInbound);
+                createSlackListener(client.app, gatewayConfig, handleInbound, client);
                 // Evict stale threads every hour
                 evictionTimer = setInterval(() => {
                     sessions.evict();

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

@@ -1,10 +1,17 @@
 import type { App } from "@slack/bolt";
 import type { SlackGatewayConfig } from "./types.js";
+import type { SlackClient } from "./client.js";
+export interface InboundFile {
+    mimetype: string;
+    name: string;
+    base64: string;
+}
 export interface InboundMessage {
     agentName: string;
     userText: string;
     threadTs: string;
     channelId: string;
+    files?: InboundFile[];
 }
 export type OnMessageCallback = (message: InboundMessage) => Promise<void>;
-export declare function createSlackListener(app: App, config: SlackGatewayConfig, onMessage: OnMessageCallback): void;
+export declare function createSlackListener(app: App, config: SlackGatewayConfig, onMessage: OnMessageCallback, client?: SlackClient): void;

package/dist/gateways/slack/listener.js

@@ -1,33 +1,59 @@
+import { sanitizeImage } from "../../media/sanitize.js";
 import { createLogger } from "../../logger.js";
 const log = createLogger("slack:listener");
-export function createSlackListener(app, config, onMessage) {
-    // Build reverse map: channelId → agentName
+const IMAGE_MIMES = new Set(["image/jpeg", "image/png", "image/gif", "image/webp"]);
+export function createSlackListener(app, config, onMessage, client) {
     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)
+        // Allow file_share through so we can process image attachments
+        if (msg.bot_id)
             return;
-        if (!msg.text || typeof msg.text !== "string")
+        if (msg.subtype && msg.subtype !== "file_share")
+            return;
+        const hasText = msg.text && typeof msg.text === "string";
+        const hasFiles = Array.isArray(msg.files) && msg.files.length > 0;
+        if (!hasText && !hasFiles)
             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.
+        let files;
+        if (hasFiles && client) {
+            files = [];
+            for (const file of msg.files) {
+                if (!IMAGE_MIMES.has(file.mimetype)) {
+                    log.debug({ name: file.name, mimetype: file.mimetype }, "skipping non-image file");
+                    continue;
+                }
+                try {
+                    const buffer = await client.downloadFile(file.url_private_download);
+                    const sanitized = await sanitizeImage(buffer, file.mimetype);
+                    files.push({
+                        mimetype: sanitized.mediaType,
+                        name: file.name ?? "image",
+                        base64: sanitized.base64,
+                    });
+                }
+                catch (err) {
+                    log.warn({ err, name: file.name }, "failed to download/sanitize image");
+                }
+            }
+            if (files.length === 0)
+                files = undefined;
+        }
         onMessage({
             agentName,
-            userText: msg.text,
+            userText: msg.text ?? "",
             threadTs,
             channelId,
+            files,
         }).catch((err) => {
             log.error({ err, channelId }, "unhandled error processing message");
         });