@geminixiang/mama 0.2.0-beta.7 → 0.2.0-beta.9

package/dist/agent.js

@@ -1,17 +1,17 @@
 import { Agent } from "@earendil-works/pi-agent-core";
 import { getModel } from "@earendil-works/pi-ai";
-import { AgentSession, AuthStorage, convertToLlm, DefaultResourceLoader, formatSkillsForPrompt, getAgentDir, loadSkillsFromDir, ModelRegistry, } from "@earendil-works/pi-coding-agent";
+import { AgentSession, AuthStorage, convertToLlm, DefaultResourceLoader, formatSkillsForPrompt, getAgentDir, loadSkillsFromDir, ModelRegistry, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { existsSync, readFileSync } from "fs";
 import { mkdir, readFile, writeFile } from "fs/promises";
 import { homedir } from "os";
 import { join, posix } from "path";
 import { loadAgentConfigForConversation } from "./config.js";
-import { createMamaSettingsManager, syncLogToSessionManager } from "./context.js";
 import { ActorExecutionResolver } from "./execution-resolver.js";
 import * as log from "./log.js";
 import { createExecutor } from "./sandbox.js";
 import { addLifecycleBreadcrumb, metricAttributes } from "./sentry.js";
-import { extractSessionSuffix, extractSessionUuid, openManagedSession, } from "./session-store.js";
+import { extractSessionUuid, openManagedSession, } from "./session-store.js";
+import { shouldSurfaceToolDiagnostic } from "./tool-diagnostics.js";
 import { createMamaTools } from "./tools/index.js";
 import * as Sentry from "@sentry/node";
 const IMAGE_MIME_TYPES = {
@@ -103,48 +103,53 @@ function buildRuntimePaths(workspacePath, conversationId) {
         scratchPath: posix.join(conversationPath, "scratch"),
     };
 }
-function buildSystemPrompt(workspacePath, conversationId, conversationKind, currentUserId, memory, sandboxConfig, platform, skills) {
-    const { workspaceRoot, conversationPath, scratchPath } = buildRuntimePaths(workspacePath, conversationId);
-    const isContainer = sandboxConfig.type === "container" || sandboxConfig.type === "image";
-    const isImageSandbox = sandboxConfig.type === "image";
-    const isFirecracker = sandboxConfig.type === "firecracker";
-    const isCloudflareSandbox = sandboxConfig.type === "cloudflare";
-    // Format channel mappings
-    const channelMappings = platform.channels.length > 0
-        ? platform.channels.map((c) => `${c.id}\t#${c.name}`).join("\n")
-        : "(no channels loaded)";
-    // Format user mappings
-    const userMappings = platform.users.length > 0
-        ? platform.users.map((u) => `${u.id}\t@${u.userName}\t${u.displayName}`).join("\n")
-        : "(no users loaded)";
-    const envDescription = isImageSandbox
-        ? `You are running inside a managed per-user container.
+function buildEnvDescription(sandboxType, workspaceRoot) {
+    switch (sandboxType) {
+        case "image":
+            return `You are running inside a managed per-user container.
 - Runtime workspace root: ${workspaceRoot}
 - Bash commands start in: ${workspaceRoot}
 - Install tools with the image's package manager
-- Your changes persist for this user's container until it is recreated`
-        : isContainer
-            ? `You are running inside a shared container.
+- Your changes persist for this user's container until it is recreated`;
+        case "container":
+            return `You are running inside a shared container.
 - Runtime workspace root: ${workspaceRoot}
 - Bash commands start in: ${workspaceRoot}
 - Install tools with the container's package manager
-- Your changes persist across sessions`
-            : isFirecracker
-                ? `You are running inside a Firecracker microVM.
+- Your changes persist across sessions`;
+        case "firecracker":
+            return `You are running inside a Firecracker microVM.
 - Runtime workspace root: ${workspaceRoot}
 - Use cd or absolute paths; project files are under ${workspaceRoot}
 - Install tools with: apt-get install <package> (Debian-based)
-- Your changes persist across sessions`
-                : isCloudflareSandbox
-                    ? `You are running through a Cloudflare Sandbox bridge.
+- Your changes persist across sessions`;
+        case "cloudflare":
+            return `You are running through a Cloudflare Sandbox bridge.
 - Runtime workspace root: ${workspaceRoot}
 - Bash commands start in: ${workspaceRoot}
 - Your commands run in a remote container managed by Cloudflare
-- Important: the remote filesystem is not automatically synced back to the host workspace`
-                    : `You are running directly on the host machine.
+- Important: the remote filesystem is not automatically synced back to the host workspace`;
+        default:
+            return `You are running directly on the host machine.
 - Runtime workspace root: ${workspaceRoot}
 - Bash commands start in: ${process.cwd()}
 - Be careful with system modifications`;
+    }
+}
+function buildSystemPrompt(workspacePath, conversationId, conversationKind, currentUserId, memory, sandboxConfig, platform, skills) {
+    const { workspaceRoot, conversationPath, scratchPath } = buildRuntimePaths(workspacePath, conversationId);
+    const sandboxType = sandboxConfig.type;
+    const isContainerLike = sandboxType === "container" || sandboxType === "image";
+    const isFirecracker = sandboxType === "firecracker";
+    // Format channel mappings
+    const channelMappings = platform.channels.length > 0
+        ? platform.channels.map((c) => `${c.id}\t#${c.name}`).join("\n")
+        : "(no channels loaded)";
+    // Format user mappings
+    const userMappings = platform.users.length > 0
+        ? platform.users.map((u) => `${u.id}\t@${u.userName}\t${u.displayName}`).join("\n")
+        : "(no users loaded)";
+    const envDescription = buildEnvDescription(sandboxType, workspaceRoot);
     return `You are mama, a ${platform.name} bot assistant. Be concise. No emojis.
 
 ## Context
@@ -298,8 +303,7 @@ Update this file whenever you modify the environment. On fresh container, read i
 Format: \`{"date":"...","ts":"...","user":"...","userName":"...","text":"...","isBot":false}\`
 The log contains user messages and your final responses (not tool calls/results).
 Use \`log.jsonl\` for quick grep-style history. Use \`${conversationPath}/sessions/\` when you need structured turns, tool outputs, or branch lineage.
-${isContainer ? "Install jq: apt-get install jq" : ""}
-${isFirecracker ? "Install jq: apt-get install jq" : ""}
+${isContainerLike || isFirecracker ? "Install jq: apt-get install jq" : ""}
 
 \`\`\`bash
 # Recent messages
@@ -331,50 +335,10 @@ function truncate(text, maxLen) {
         return text;
     return `${text.substring(0, maxLen - 3)}...`;
 }
-// Tools whose output is interesting in the structured session log but too noisy
-// to surface as a per-tool diagnostic to the user.
-const QUIET_TOOLS = new Set(["read", "write", "edit"]);
-// Cap raw tool output before handing it to adapters. Bash output can be MB; without
-// this each adapter's splitter would fan it out into many sequential platform posts.
-const TOOL_RESULT_DIAGNOSTIC_CAP = 8000;
-function extractToolResultText(result) {
-    if (typeof result === "string") {
-        return result;
-    }
-    if (result &&
-        typeof result === "object" &&
-        "content" in result &&
-        Array.isArray(result.content)) {
-        const content = result.content;
-        const textParts = [];
-        for (const part of content) {
-            if (part.type === "text" && part.text) {
-                textParts.push(part.text);
-            }
-        }
-        if (textParts.length > 0) {
-            return textParts.join("\n");
-        }
-    }
-    return JSON.stringify(result);
+function initialWorkspacePath(sandboxConfig, hostWorkspacePath) {
+    return sandboxConfig.type === "host" ? hostWorkspacePath : "/workspace";
 }
-// ============================================================================
-// Agent runner
-// ============================================================================
-/**
- * Create a new AgentRunner for a channel.
- * Sets up the session and subscribes to events once.
- *
- * Runner caching is handled by the caller (channelStates in main.ts).
- * This is a stateless factory function.
- */
-export async function createRunner(sandboxConfig, sessionKey, conversationId, conversationDir, workspaceDir, sessionScope, vaultManager, bindingStore, provisioner) {
-    const agentConfig = loadAgentConfigForConversation(conversationDir);
-    // Initialize logger with settings from config
-    log.initLogger({
-        logFormat: agentConfig.logFormat,
-        logLevel: agentConfig.logLevel,
-    });
+function createRunnerExecutionContext(sandboxConfig, vaultManager, provisioner, workspaceDir, hostWorkspacePath) {
     const executionResolver = vaultManager &&
         sandboxConfig.type !== "host" &&
         (vaultManager.isEnabled() ||
@@ -400,68 +364,42 @@ export async function createRunner(sandboxConfig, sessionKey, conversationId, co
             return activeExecutor.getSandboxConfig();
         },
     };
-    const workspaceBase = join(conversationDir, "..");
-    const getWorkspacePath = () => executor.getWorkspacePath(workspaceBase);
-    let workspacePath = getWorkspacePath();
-    // Create tools (per-runner, with per-runner upload function setter)
-    const { tools, setUploadFunction, setEventContext } = createMamaTools(executor, workspaceDir);
-    // Resolve model from config
-    // Use 'as any' cast because agentConfig.provider/model are plain strings,
-    // while getModel() has constrained generic types for known providers.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const model = getModel(agentConfig.provider, agentConfig.model);
-    // Initial system prompt (will be updated each run with fresh memory/channels/users/skills)
-    const memory = await getMemory(conversationDir);
-    const skills = loadMamaSkills(conversationDir, workspacePath);
-    const emptyPlatform = {
-        name: "chat",
-        formattingGuide: "",
-        channels: [],
-        users: [],
+    return {
+        executionResolver,
+        executor,
+        getWorkspacePath: () => executor.getWorkspacePath(hostWorkspacePath),
+        async resolveExecutorForRun(context) {
+            if (!executionResolver)
+                return;
+            activeExecutor = await executionResolver.resolve(context);
+        },
     };
-    const systemPrompt = buildSystemPrompt(workspacePath, conversationId, "shared", undefined, memory, sandboxConfig, emptyPlatform, skills);
-    // Create session manager and settings manager. Top-level/private sessions
-    // use the conversation's current pointer; scoped sessions use fixed files.
-    // Platform-specific branch/fork behavior is resolved before runner creation.
-    const isThread = sessionKey.includes(":");
-    const rootTs = extractSessionSuffix(sessionKey);
-    const { sessionDir, contextFile, threadRootMessage } = sessionScope;
-    const sessionManager = openManagedSession(contextFile, sessionDir, conversationDir);
-    const threadSessionName = buildThreadSessionName(threadRootMessage);
-    if (isThread && threadSessionName && sessionManager.getSessionName() !== threadSessionName) {
-        sessionManager.appendSessionInfo(threadSessionName);
-    }
-    const sessionUuid = extractSessionUuid(contextFile);
-    const settingsManager = createMamaSettingsManager(join(conversationDir, ".."));
-    // Create AuthStorage and ModelRegistry
-    // Auth stored outside workspace so agent can't access it
+}
+async function createConfiguredAgentSession(params) {
+    const { conversationId, workspaceDir, workspacePath, systemPrompt, model, thinkingLevel, tools, sessionManager, settingsManager, } = params;
     const authStorage = AuthStorage.create(join(homedir(), ".pi", "mama", "auth.json"));
     const modelRegistry = ModelRegistry.create(authStorage);
-    // Create agent
     const agent = new Agent({
         initialState: {
             systemPrompt,
             model,
-            thinkingLevel: agentConfig.thinkingLevel,
+            thinkingLevel,
             tools,
         },
         convertToLlm,
         getApiKey: async () => {
             const key = await modelRegistry.getApiKeyForProvider(model.provider);
-            if (!key)
+            if (!key) {
                 throw new Error(`No API key for provider "${model.provider}". Set the appropriate environment variable or configure via auth.json`);
+            }
             return key;
         },
     });
-    // Load existing messages
     const loadedSession = sessionManager.buildSessionContext();
     if (loadedSession.messages.length > 0) {
         agent.state.messages = loadedSession.messages;
         log.logInfo(`[${conversationId}] Loaded ${loadedSession.messages.length} messages from context.jsonl`);
     }
-    // Load extensions, skills, prompts, themes via DefaultResourceLoader
-    // This reads ~/.pi/agent/settings.json (packages, extensions enable/disable)
-    // and discovers resources from standard locations + npm/git packages.
     const resourceLoader = new DefaultResourceLoader({
         cwd: workspaceDir,
         agentDir: getAgentDir(),
@@ -475,111 +413,354 @@ export async function createRunner(sandboxConfig, sessionKey, conversationId, co
                 log.logWarning(`[${conversationId}] Extension load error: ${err.path}`, err.error);
             }
         }
-        log.logInfo(`[${conversationId}] Loaded ${extResult.extensions.length} extension(s): ${extResult.extensions.map((e) => e.path).join(", ")}`);
+        log.logInfo(`[${conversationId}] Loaded ${extResult.extensions.length} extension(s): ${extResult.extensions.map((extension) => extension.path).join(", ")}`);
     }
     catch (error) {
         log.logWarning(`[${conversationId}] Failed to load resources`, String(error));
     }
     const baseToolsOverride = Object.fromEntries(tools.map((tool) => [tool.name, tool]));
-    // Create AgentSession wrapper
     const session = new AgentSession({
         agent,
         sessionManager,
         settingsManager,
-        cwd: workspaceDir,
+        cwd: workspacePath,
         modelRegistry,
         resourceLoader,
         baseToolsOverride,
     });
-    // Mutable per-run state - event handler references this
-    const runState = {
+    return { agent, session };
+}
+function createEmptyUsageTotals() {
+    return {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    };
+}
+function createRunState() {
+    return {
         responseCtx: null,
         logCtx: null,
         queue: null,
         pendingTools: new Map(),
-        totalUsage: {
-            input: 0,
-            output: 0,
-            cacheRead: 0,
-            cacheWrite: 0,
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-        },
+        totalUsage: createEmptyUsageTotals(),
         llmCallCount: 0,
         stopReason: "stop",
         errorMessage: undefined,
     };
-    // Subscribe to events ONCE
+}
+function resetRunState(runState, responseCtx, sessionConversation, userName, sessionUuid) {
+    runState.responseCtx = responseCtx;
+    runState.logCtx = {
+        conversationId: sessionConversation,
+        userName,
+        conversationName: undefined,
+        sessionId: sessionUuid,
+    };
+    runState.pendingTools.clear();
+    runState.totalUsage = createEmptyUsageTotals();
+    runState.llmCallCount = 0;
+    runState.stopReason = "stop";
+    runState.errorMessage = undefined;
+}
+function createRunQueue(responseCtx) {
+    let queueChain = Promise.resolve();
+    return {
+        queue: {
+            enqueue(fn, errorContext) {
+                queueChain = queueChain.then(async () => {
+                    try {
+                        await fn();
+                    }
+                    catch (err) {
+                        const errMsg = err instanceof Error ? err.message : String(err);
+                        log.logWarning(`API error (${errorContext})`, errMsg);
+                        try {
+                            await responseCtx.respondDiagnostic(`Error: ${errMsg}`, { style: "error" });
+                        }
+                        catch {
+                            // Ignore
+                        }
+                    }
+                });
+            },
+        },
+        wait: () => queueChain,
+    };
+}
+function padTwoDigits(n) {
+    return n.toString().padStart(2, "0");
+}
+function formatTimestampedUserMessage(message) {
+    const now = new Date();
+    const offset = -now.getTimezoneOffset();
+    const offsetSign = offset >= 0 ? "+" : "-";
+    const offsetHours = padTwoDigits(Math.floor(Math.abs(offset) / 60));
+    const offsetMins = padTwoDigits(Math.abs(offset) % 60);
+    const timestamp = `${now.getFullYear()}-${padTwoDigits(now.getMonth() + 1)}-${padTwoDigits(now.getDate())} ` +
+        `${padTwoDigits(now.getHours())}:${padTwoDigits(now.getMinutes())}:${padTwoDigits(now.getSeconds())}` +
+        `${offsetSign}${offsetHours}:${offsetMins}`;
+    const threadContext = message.threadTs ? ` [in-thread:${message.threadTs}]` : "";
+    return `[${timestamp}] [${message.userName || "unknown"}]${threadContext}: ${message.text}`;
+}
+function collectMessageAttachments(message, workspacePath) {
+    const imageAttachments = [];
+    const nonImagePaths = [];
+    for (const attachment of message.attachments || []) {
+        const fullPath = `${workspacePath}/${attachment.localPath}`;
+        const mimeType = getImageMimeType(attachment.localPath);
+        if (mimeType && existsSync(fullPath)) {
+            try {
+                imageAttachments.push({
+                    type: "image",
+                    mimeType,
+                    data: readFileSync(fullPath).toString("base64"),
+                });
+            }
+            catch {
+                nonImagePaths.push(fullPath);
+            }
+        }
+        else {
+            nonImagePaths.push(fullPath);
+        }
+    }
+    return { imageAttachments, nonImagePaths };
+}
+function buildPromptPayload(message, workspacePath) {
+    let userMessage = formatTimestampedUserMessage(message);
+    const { imageAttachments, nonImagePaths } = collectMessageAttachments(message, workspacePath);
+    if (nonImagePaths.length > 0) {
+        userMessage += `\n\n<slack_attachments>\n${nonImagePaths.join("\n")}\n</slack_attachments>`;
+    }
+    return { userMessage, imageAttachments };
+}
+async function writePromptDebugContext(conversationDir, systemPrompt, session, userMessage, imageAttachmentCount) {
+    const debugContext = {
+        systemPrompt,
+        messages: session.messages,
+        newUserMessage: userMessage,
+        imageAttachmentCount,
+    };
+    await writeFile(join(conversationDir, "last_prompt.jsonl"), JSON.stringify(debugContext, null, 2));
+}
+function getFinalAssistantText(session) {
+    const lastAssistant = session.messages.filter((message) => message.role === "assistant").pop();
+    return (lastAssistant?.content
+        .filter((content) => content.type === "text")
+        .map((content) => content.text)
+        .join("\n") || "");
+}
+async function finalizeRunResponse(responseCtx, session, runState) {
+    if (runState.stopReason === "error" && runState.errorMessage) {
+        try {
+            await responseCtx.replaceResponse("_Sorry, something went wrong_");
+            await responseCtx.respondDiagnostic(`Error: ${runState.errorMessage}`, {
+                style: "error",
+            });
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            log.logWarning("Failed to post error message", errMsg);
+        }
+        return;
+    }
+    const finalText = getFinalAssistantText(session);
+    if (finalText.trim() === "[SILENT]" || finalText.trim().startsWith("[SILENT]")) {
+        try {
+            await responseCtx.deleteResponse();
+            log.logInfo("Silent response - deleted message and thread");
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            log.logWarning("Failed to delete message for silent response", errMsg);
+        }
+        return;
+    }
+    if (!finalText.trim())
+        return;
+    try {
+        await responseCtx.replaceResponse(finalText);
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        log.logWarning("Failed to replace message with final text", errMsg);
+    }
+}
+async function reportUsageSummary(ctx) {
+    const { session, runState, responseCtx, platform, model, agentConfig, sessionConversation, sessionUuid, waitForQueue, } = ctx;
+    if (runState.totalUsage.cost.total <= 0)
+        return;
+    const lastAssistantMessage = session.messages
+        .slice()
+        .toReversed()
+        .find((message) => message.role === "assistant" && message.stopReason !== "aborted");
+    const contextTokens = lastAssistantMessage
+        ? lastAssistantMessage.usage.input +
+            lastAssistantMessage.usage.output +
+            lastAssistantMessage.usage.cacheRead +
+            lastAssistantMessage.usage.cacheWrite
+        : 0;
+    const contextWindow = model.contextWindow || 200000;
+    const { totalUsage } = runState;
+    const runMetricAttributes = metricAttributes({
+        provider: model.provider,
+        model: agentConfig.model,
+        channel_id: sessionConversation,
+        session_id: sessionUuid,
+        stop_reason: runState.stopReason,
+        llm_calls: runState.llmCallCount,
+    });
+    Sentry.metrics.distribution("agent.run.tokens_in", totalUsage.input, {
+        attributes: runMetricAttributes,
+    });
+    Sentry.metrics.distribution("agent.run.tokens_out", totalUsage.output, {
+        attributes: runMetricAttributes,
+    });
+    Sentry.metrics.distribution("agent.run.cache_read", totalUsage.cacheRead, {
+        attributes: runMetricAttributes,
+    });
+    Sentry.metrics.distribution("agent.run.cache_write", totalUsage.cacheWrite, {
+        attributes: runMetricAttributes,
+    });
+    Sentry.metrics.distribution("agent.run.cost", totalUsage.cost.total, {
+        attributes: runMetricAttributes,
+    });
+    Sentry.metrics.gauge("agent.context.utilization", contextTokens / contextWindow, {
+        unit: "ratio",
+        attributes: runMetricAttributes,
+    });
+    const summary = log.logUsageSummary(runState.logCtx, runState.totalUsage, contextTokens, contextWindow);
+    if (platform.diagnostics?.showUsageSummary === true) {
+        runState.queue.enqueue(() => responseCtx.respondDiagnostic(summary, { style: "muted" }), "usage summary");
+        await waitForQueue();
+    }
+}
+function reloadSessionMessages(sessionManager, conversationId, agent) {
+    const messages = sessionManager.buildSessionContext().messages;
+    if (messages.length > 0) {
+        agent.state.messages = messages;
+        log.logInfo(`[${conversationId}] Reloaded ${messages.length} messages from context`);
+    }
+}
+async function prepareRunContext(params) {
+    const { message, responseCtx, platform, conversationId, conversationDir, sessionUuid, runState, executor, executionResolver, resolveExecutorForRun, getWorkspacePath, sessionManager, session, agent, setEventContext, setUploadFunction, } = params;
+    let workspacePath = params.workspacePath;
+    const sessionConversation = message.sessionKey.split(":")[0];
+    await mkdir(join(conversationDir, "scratch"), { recursive: true });
+    if (executionResolver) {
+        await resolveExecutorForRun({
+            platform: platform.name,
+            userId: message.userId,
+            conversationId,
+        });
+        workspacePath = getWorkspacePath();
+    }
+    reloadSessionMessages(sessionManager, conversationId, agent);
+    const memory = await getMemory(conversationDir);
+    const skills = loadMamaSkills(conversationDir, workspacePath);
+    const systemPrompt = buildSystemPrompt(workspacePath, conversationId, message.conversationKind, message.userId, memory, executor.getSandboxConfig(), platform, skills);
+    session.agent.state.systemPrompt = systemPrompt;
+    setEventContext({
+        platform: platform.name,
+        conversationId,
+        conversationKind: message.conversationKind,
+        userId: message.userId,
+        sessionKey: message.sessionKey,
+        threadTs: message.threadTs,
+    });
+    setUploadFunction(async (filePath, title) => {
+        const hostPath = translateToHostPath(filePath, conversationDir, workspacePath, conversationId);
+        await responseCtx.uploadFile(hostPath, title);
+    });
+    resetRunState(runState, responseCtx, sessionConversation, message.userName, sessionUuid);
+    const runQueue = createRunQueue(responseCtx);
+    runState.queue = runQueue.queue;
+    log.logInfo(`Context sizes - system: ${systemPrompt.length} chars, memory: ${memory.length} chars`);
+    log.logInfo(`Channels: ${platform.channels.length}, Users: ${platform.users.length}`);
+    const { userMessage, imageAttachments } = buildPromptPayload(message, workspacePath);
+    await writePromptDebugContext(conversationDir, systemPrompt, session, userMessage, imageAttachments.length);
+    return {
+        sessionConversation,
+        runQueue,
+        userMessage,
+        imageAttachments,
+        workspacePath,
+    };
+}
+function attachSessionEventHandlers(params) {
+    const { session, runState, model, agentConfig } = params;
     session.subscribe(async (event) => {
-        // Skip if no active run
         if (!runState.responseCtx || !runState.logCtx || !runState.queue)
             return;
         const { responseCtx, logCtx, queue, pendingTools } = runState;
         const baseAttrs = { channel_id: logCtx.conversationId, session_id: logCtx.sessionId };
         if (event.type === "tool_execution_start") {
-            const agentEvent = event;
-            const args = agentEvent.args;
-            const label = args.label || agentEvent.toolName;
-            pendingTools.set(agentEvent.toolCallId, {
-                toolName: agentEvent.toolName,
-                args: agentEvent.args,
+            const args = (event.args ?? {});
+            const label = args.label || event.toolName;
+            pendingTools.set(event.toolCallId, {
+                toolName: event.toolName,
+                args: event.args,
                 startTime: Date.now(),
             });
             addLifecycleBreadcrumb("agent.tool.started", {
-                tool: agentEvent.toolName,
+                tool: event.toolName,
                 ...baseAttrs,
             });
-            log.logToolStart(logCtx, agentEvent.toolName, label, agentEvent.args);
+            log.logToolStart(logCtx, event.toolName, label, event.args);
+            return;
         }
-        else if (event.type === "tool_execution_end") {
-            const agentEvent = event;
-            const resultStr = extractToolResultText(agentEvent.result);
-            const pending = pendingTools.get(agentEvent.toolCallId);
-            pendingTools.delete(agentEvent.toolCallId);
+        if (event.type === "tool_execution_end") {
+            const resultStr = extractToolResultText(event.result);
+            const pending = pendingTools.get(event.toolCallId);
+            pendingTools.delete(event.toolCallId);
             const durationMs = pending ? Date.now() - pending.startTime : 0;
             Sentry.metrics.count("agent.tool.calls", 1, {
                 attributes: metricAttributes({
-                    tool: agentEvent.toolName,
-                    error: String(agentEvent.isError),
+                    tool: event.toolName,
+                    error: String(event.isError),
                     ...baseAttrs,
                 }),
             });
             Sentry.metrics.distribution("agent.tool.duration", durationMs, {
                 unit: "millisecond",
                 attributes: metricAttributes({
-                    tool: agentEvent.toolName,
+                    tool: event.toolName,
                     ...baseAttrs,
                 }),
             });
             addLifecycleBreadcrumb("agent.tool.completed", {
-                tool: agentEvent.toolName,
-                error: agentEvent.isError,
+                tool: event.toolName,
+                error: event.isError,
                 duration_ms: durationMs,
                 ...baseAttrs,
             });
-            if (agentEvent.isError) {
-                log.logToolError(logCtx, agentEvent.toolName, durationMs, resultStr);
+            if (event.isError) {
+                log.logToolError(logCtx, event.toolName, durationMs, resultStr);
             }
             else {
-                log.logToolSuccess(logCtx, agentEvent.toolName, durationMs, resultStr);
+                log.logToolSuccess(logCtx, event.toolName, durationMs, resultStr);
             }
-            if (!QUIET_TOOLS.has(agentEvent.toolName)) {
+            if (shouldSurfaceToolDiagnostic(event.toolName)) {
                 const toolResult = {
-                    toolName: agentEvent.toolName,
+                    toolName: event.toolName,
                     label: pending?.args ? pending.args.label : undefined,
                     args: pending?.args,
                     result: truncate(resultStr, TOOL_RESULT_DIAGNOSTIC_CAP),
-                    isError: agentEvent.isError,
+                    isError: event.isError,
                     durationMs,
                 };
                 queue.enqueue(() => responseCtx.respondToolResult(toolResult), "tool result diagnostic");
             }
-            if (agentEvent.isError) {
+            if (event.isError) {
                 queue.enqueue(() => responseCtx.respond(`_Error: ${truncate(resultStr, 200)}_`), "tool error");
             }
+            return;
         }
-        else if (event.type === "message_start") {
-            const agentEvent = event;
-            if (agentEvent.message.role === "assistant") {
+        if (event.type === "message_start") {
+            if (event.message.role === "assistant") {
                 runState.llmCallCount += 1;
                 addLifecycleBreadcrumb("agent.llm.call.started", {
                     call_index: runState.llmCallCount,
@@ -589,11 +770,11 @@ export async function createRunner(sandboxConfig, sessionKey, conversationId, co
                 });
                 log.logResponseStart(logCtx);
             }
+            return;
         }
-        else if (event.type === "message_end") {
-            const agentEvent = event;
-            if (agentEvent.message.role === "assistant") {
-                const assistantMsg = agentEvent.message;
+        if (event.type === "message_end") {
+            if (event.message.role === "assistant") {
+                const assistantMsg = event.message;
                 if (assistantMsg.stopReason) {
                     runState.stopReason = assistantMsg.stopReason;
                 }
@@ -610,7 +791,6 @@ export async function createRunner(sandboxConfig, sessionKey, conversationId, co
                     runState.totalUsage.cost.cacheRead += assistantMsg.usage.cost.cacheRead;
                     runState.totalUsage.cost.cacheWrite += assistantMsg.usage.cost.cacheWrite;
                     runState.totalUsage.cost.total += assistantMsg.usage.cost.total;
-                    // Per-turn LLM metrics
                     const llmAttributes = metricAttributes({
                         provider: model.provider,
                         model: agentConfig.model,
@@ -649,10 +829,9 @@ export async function createRunner(sandboxConfig, sessionKey, conversationId, co
                         cost_total_usd: assistantMsg.usage.cost.total,
                     });
                 }
-                const content = agentEvent.message.content;
                 const thinkingParts = [];
                 const textParts = [];
-                for (const part of content) {
+                for (const part of assistantMsg.content) {
                     if (part.type === "thinking") {
                         thinkingParts.push(part.thinking);
                     }
@@ -671,270 +850,160 @@ export async function createRunner(sandboxConfig, sessionKey, conversationId, co
                     queue.enqueue(() => responseCtx.respond(text), "response main");
                 }
             }
+            return;
         }
-        else if (event.type === "compaction_start") {
+        if (event.type === "compaction_start") {
             log.logInfo(`Auto-compaction started (reason: ${event.reason})`);
             queue.enqueue(() => responseCtx.respond("_Compacting context..._"), "compaction start");
+            return;
         }
-        else if (event.type === "compaction_end") {
-            const compEvent = event;
-            if (compEvent.result) {
-                log.logInfo(`Auto-compaction complete: ${compEvent.result.tokensBefore} tokens compacted`);
+        if (event.type === "compaction_end") {
+            if (event.result) {
+                log.logInfo(`Auto-compaction complete: ${event.result.tokensBefore} tokens compacted`);
             }
-            else if (compEvent.aborted) {
+            else if (event.aborted) {
                 log.logInfo("Auto-compaction aborted");
             }
+            return;
+        }
+        if (event.type === "auto_retry_start") {
+            log.logWarning(`Retrying (${event.attempt}/${event.maxAttempts})`, event.errorMessage);
+            queue.enqueue(() => responseCtx.respond(`_Retrying (${event.attempt}/${event.maxAttempts})..._`), "retry");
+        }
+    });
+}
+// Cap raw tool output before handing it to adapters. Bash output can be MB; without
+// this each adapter's splitter would fan it out into many sequential platform posts.
+const TOOL_RESULT_DIAGNOSTIC_CAP = 8000;
+function extractToolResultText(result) {
+    if (typeof result === "string") {
+        return result;
+    }
+    if (result &&
+        typeof result === "object" &&
+        "content" in result &&
+        Array.isArray(result.content)) {
+        const content = result.content;
+        const textParts = [];
+        for (const part of content) {
+            if (part.type === "text" && part.text) {
+                textParts.push(part.text);
+            }
         }
-        else if (event.type === "auto_retry_start") {
-            const retryEvent = event;
-            log.logWarning(`Retrying (${retryEvent.attempt}/${retryEvent.maxAttempts})`, retryEvent.errorMessage);
-            queue.enqueue(() => responseCtx.respond(`_Retrying (${retryEvent.attempt}/${retryEvent.maxAttempts})..._`), "retry");
+        if (textParts.length > 0) {
+            return textParts.join("\n");
         }
+    }
+    return JSON.stringify(result);
+}
+// ============================================================================
+// Agent runner
+// ============================================================================
+/**
+ * Create a new AgentRunner for a channel.
+ * Sets up the session and subscribes to events once.
+ *
+ * Runner caching is handled by the caller (channelStates in main.ts).
+ * This is a stateless factory function.
+ */
+export async function createRunner(sandboxConfig, sessionKey, conversationId, conversationDir, workspaceDir, sessionScope, vaultManager, provisioner) {
+    const agentConfig = loadAgentConfigForConversation(conversationDir);
+    // Initialize logger with settings from config
+    log.initLogger({
+        logFormat: agentConfig.logFormat,
+        logLevel: agentConfig.logLevel,
     });
+    const workspaceBase = join(conversationDir, "..");
+    const { executionResolver, executor, getWorkspacePath, resolveExecutorForRun } = createRunnerExecutionContext(sandboxConfig, vaultManager, provisioner, workspaceDir, workspaceBase);
+    let workspacePath = initialWorkspacePath(sandboxConfig, workspaceBase);
+    // Create tools (per-runner, with per-runner upload function setter)
+    const { tools, setUploadFunction, setEventContext } = createMamaTools(executor, workspaceDir);
+    // Resolve model from config
+    // Use 'as any' cast because agentConfig.provider/model are plain strings,
+    // while getModel() has constrained generic types for known providers.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const model = getModel(agentConfig.provider, agentConfig.model);
+    // Initial system prompt (will be updated each run with fresh memory/channels/users/skills)
+    const memory = await getMemory(conversationDir);
+    const skills = loadMamaSkills(conversationDir, workspacePath);
+    const emptyPlatform = {
+        name: "chat",
+        formattingGuide: "",
+        channels: [],
+        users: [],
+    };
+    const systemPrompt = buildSystemPrompt(workspacePath, conversationId, "shared", undefined, memory, sandboxConfig, emptyPlatform, skills);
+    // Create session manager and settings manager. Top-level/private sessions
+    // use the conversation's current pointer; scoped sessions use fixed files.
+    // Platform-specific branch/fork behavior is resolved before runner creation.
+    const isThread = sessionKey.includes(":");
+    const { sessionDir, contextFile, threadRootMessage } = sessionScope;
+    const sessionManager = openManagedSession(contextFile, sessionDir, workspacePath);
+    const threadSessionName = buildThreadSessionName(threadRootMessage);
+    if (isThread && threadSessionName && sessionManager.getSessionName() !== threadSessionName) {
+        sessionManager.appendSessionInfo(threadSessionName);
+    }
+    const sessionUuid = extractSessionUuid(contextFile);
+    const settingsManager = SettingsManager.inMemory();
+    const { agent, session } = await createConfiguredAgentSession({
+        conversationId,
+        workspaceDir,
+        workspacePath,
+        systemPrompt,
+        model,
+        thinkingLevel: agentConfig.thinkingLevel,
+        tools,
+        sessionManager,
+        settingsManager,
+    });
+    // Mutable per-run state - event handler references this
+    const runState = createRunState();
+    attachSessionEventHandlers({ session, runState, model, agentConfig });
     return {
         async run(message, responseCtx, platform) {
-            // Extract conversationId from sessionKey (format: "conversationId:rootTs" or just "conversationId")
-            const sessionConversation = message.sessionKey.split(":")[0];
-            // Ensure conversation workspace exists on the host side before it is mounted/routed.
-            await mkdir(join(conversationDir, "scratch"), { recursive: true });
-            if (executionResolver) {
-                executionResolver.refresh();
-                activeExecutor = await executionResolver.resolve({
-                    platform: platform.name,
-                    userId: message.userId,
-                    conversationId,
-                });
-                workspacePath = getWorkspacePath();
-            }
-            // Sync messages from log.jsonl that arrived while we were offline or busy
-            // Exclude the current message (it will be added via prompt())
-            // Default sync range is 10 days (handled by syncLogToSessionManager)
-            // Thread filter ensures only messages from this session's thread are synced
-            const threadFilter = message.sessionKey.includes(":")
-                ? { scope: "thread", rootTs, threadTs: message.threadTs }
-                : { scope: "top-level", rootTs };
-            const syncedCount = await syncLogToSessionManager(sessionManager, conversationDir, message.id, undefined, threadFilter);
-            if (syncedCount > 0) {
-                log.logInfo(`[${conversationId}] Synced ${syncedCount} messages from log.jsonl`);
-            }
-            // Reload messages from context.jsonl
-            // This picks up any messages synced above
-            const reloadedSession = sessionManager.buildSessionContext();
-            if (reloadedSession.messages.length > 0) {
-                agent.state.messages = reloadedSession.messages;
-                log.logInfo(`[${conversationId}] Reloaded ${reloadedSession.messages.length} messages from context`);
-            }
-            // Update system prompt with fresh memory, channel/user info, and skills
-            const memory = await getMemory(conversationDir);
-            const skills = loadMamaSkills(conversationDir, workspacePath);
-            const systemPrompt = buildSystemPrompt(workspacePath, conversationId, message.conversationKind, message.userId, memory, executor.getSandboxConfig(), platform, skills);
-            session.agent.state.systemPrompt = systemPrompt;
-            setEventContext({
-                platform: platform.name,
+            const prepared = await prepareRunContext({
+                message,
+                responseCtx,
+                platform,
                 conversationId,
-                conversationKind: message.conversationKind,
-                userId: message.userId,
-                sessionKey: message.sessionKey,
-                // For Slack scheduled events, preserve thread targeting only when the
-                // request was created inside an existing thread. Top-level reminders
-                // should come back as top-level messages.
-                threadTs: message.threadTs,
+                conversationDir,
+                sessionUuid,
+                runState,
+                executor,
+                executionResolver,
+                resolveExecutorForRun,
+                getWorkspacePath,
+                sessionManager,
+                session,
+                agent,
+                setEventContext,
+                setUploadFunction,
+                workspacePath,
             });
-            // Set up file upload function
-            setUploadFunction(async (filePath, title) => {
-                const hostPath = translateToHostPath(filePath, conversationDir, workspacePath, conversationId);
-                await responseCtx.uploadFile(hostPath, title);
-            });
-            // Reset per-run state
-            runState.responseCtx = responseCtx;
-            runState.logCtx = {
-                conversationId: sessionConversation,
-                userName: message.userName,
-                conversationName: undefined,
-                sessionId: sessionUuid,
-            };
-            runState.pendingTools.clear();
-            runState.totalUsage = {
-                input: 0,
-                output: 0,
-                cacheRead: 0,
-                cacheWrite: 0,
-                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-            };
-            runState.llmCallCount = 0;
-            runState.stopReason = "stop";
-            runState.errorMessage = undefined;
-            // Create queue for this run
-            let queueChain = Promise.resolve();
-            runState.queue = {
-                enqueue(fn, errorContext) {
-                    queueChain = queueChain.then(async () => {
-                        try {
-                            await fn();
-                        }
-                        catch (err) {
-                            const errMsg = err instanceof Error ? err.message : String(err);
-                            log.logWarning(`API error (${errorContext})`, errMsg);
-                            try {
-                                await responseCtx.respondDiagnostic(`Error: ${errMsg}`, { style: "error" });
-                            }
-                            catch {
-                                // Ignore
-                            }
-                        }
-                    });
-                },
-            };
-            // Log context info
-            log.logInfo(`Context sizes - system: ${systemPrompt.length} chars, memory: ${memory.length} chars`);
-            log.logInfo(`Channels: ${platform.channels.length}, Users: ${platform.users.length}`);
-            // Build user message with timestamp and username prefix
-            // Format: "[YYYY-MM-DD HH:MM:SS+HH:MM] [username]: message" so LLM knows when and who
-            const now = new Date();
-            const pad = (n) => n.toString().padStart(2, "0");
-            const offset = -now.getTimezoneOffset();
-            const offsetSign = offset >= 0 ? "+" : "-";
-            const offsetHours = pad(Math.floor(Math.abs(offset) / 60));
-            const offsetMins = pad(Math.abs(offset) % 60);
-            const timestamp = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}${offsetSign}${offsetHours}:${offsetMins}`;
-            const threadContext = message.threadTs ? ` [in-thread:${message.threadTs}]` : "";
-            let userMessage = `[${timestamp}] [${message.userName || "unknown"}]${threadContext}: ${message.text}`;
-            const imageAttachments = [];
-            const nonImagePaths = [];
-            for (const a of message.attachments || []) {
-                // a.localPath is the path relative to the workspace.
-                const fullPath = `${workspacePath}/${a.localPath}`;
-                const mimeType = getImageMimeType(a.localPath);
-                if (mimeType && existsSync(fullPath)) {
-                    try {
-                        imageAttachments.push({
-                            type: "image",
-                            mimeType,
-                            data: readFileSync(fullPath).toString("base64"),
-                        });
-                    }
-                    catch {
-                        nonImagePaths.push(fullPath);
-                    }
-                }
-                else {
-                    nonImagePaths.push(fullPath);
-                }
-            }
-            if (nonImagePaths.length > 0) {
-                userMessage += `\n\n<slack_attachments>\n${nonImagePaths.join("\n")}\n</slack_attachments>`;
-            }
-            // Debug: write context to last_prompt.jsonl
-            const debugContext = {
-                systemPrompt,
-                messages: session.messages,
-                newUserMessage: userMessage,
-                imageAttachmentCount: imageAttachments.length,
-            };
-            await writeFile(join(conversationDir, "last_prompt.jsonl"), JSON.stringify(debugContext, null, 2));
+            workspacePath = prepared.workspacePath;
             addLifecycleBreadcrumb("agent.prompt.sent", {
                 provider: model.provider,
                 model: agentConfig.model,
-                channel_id: sessionConversation,
+                channel_id: prepared.sessionConversation,
                 session_id: sessionUuid,
                 attachment_count: message.attachments?.length ?? 0,
-                image_attachment_count: imageAttachments.length,
+                image_attachment_count: prepared.imageAttachments.length,
             });
-            await session.prompt(userMessage, imageAttachments.length > 0 ? { images: imageAttachments } : undefined);
+            await session.prompt(prepared.userMessage, prepared.imageAttachments.length > 0 ? { images: prepared.imageAttachments } : undefined);
             // Wait for queued messages
-            await queueChain;
-            // Handle error case - update main message and post error to thread
-            if (runState.stopReason === "error" && runState.errorMessage) {
-                try {
-                    await responseCtx.replaceResponse("_Sorry, something went wrong_");
-                    await responseCtx.respondDiagnostic(`Error: ${runState.errorMessage}`, {
-                        style: "error",
-                    });
-                }
-                catch (err) {
-                    const errMsg = err instanceof Error ? err.message : String(err);
-                    log.logWarning("Failed to post error message", errMsg);
-                }
-            }
-            else {
-                // Final message update
-                const messages = session.messages;
-                const lastAssistant = messages.filter((m) => m.role === "assistant").pop();
-                const finalText = lastAssistant?.content
-                    .filter((c) => c.type === "text")
-                    .map((c) => c.text)
-                    .join("\n") || "";
-                // Check for [SILENT] marker - delete message and thread instead of posting
-                if (finalText.trim() === "[SILENT]" || finalText.trim().startsWith("[SILENT]")) {
-                    try {
-                        await responseCtx.deleteResponse();
-                        log.logInfo("Silent response - deleted message and thread");
-                    }
-                    catch (err) {
-                        const errMsg = err instanceof Error ? err.message : String(err);
-                        log.logWarning("Failed to delete message for silent response", errMsg);
-                    }
-                }
-                else if (finalText.trim()) {
-                    try {
-                        await responseCtx.replaceResponse(finalText);
-                    }
-                    catch (err) {
-                        const errMsg = err instanceof Error ? err.message : String(err);
-                        log.logWarning("Failed to replace message with final text", errMsg);
-                    }
-                }
-            }
-            // Log usage summary with context info
-            if (runState.totalUsage.cost.total > 0) {
-                // Get last non-aborted assistant message for context calculation
-                const messages = session.messages;
-                const lastAssistantMessage = messages
-                    .slice()
-                    .reverse()
-                    .find((m) => m.role === "assistant" && m.stopReason !== "aborted");
-                const contextTokens = lastAssistantMessage
-                    ? lastAssistantMessage.usage.input +
-                        lastAssistantMessage.usage.output +
-                        lastAssistantMessage.usage.cacheRead +
-                        lastAssistantMessage.usage.cacheWrite
-                    : 0;
-                const contextWindow = model.contextWindow || 200000;
-                // Run-level Sentry metrics
-                const { totalUsage } = runState;
-                const runMetricAttributes = metricAttributes({
-                    provider: model.provider,
-                    model: agentConfig.model,
-                    channel_id: sessionConversation,
-                    session_id: sessionUuid,
-                    stop_reason: runState.stopReason,
-                    llm_calls: runState.llmCallCount,
-                });
-                Sentry.metrics.distribution("agent.run.tokens_in", totalUsage.input, {
-                    attributes: runMetricAttributes,
-                });
-                Sentry.metrics.distribution("agent.run.tokens_out", totalUsage.output, {
-                    attributes: runMetricAttributes,
-                });
-                Sentry.metrics.distribution("agent.run.cache_read", totalUsage.cacheRead, {
-                    attributes: runMetricAttributes,
-                });
-                Sentry.metrics.distribution("agent.run.cache_write", totalUsage.cacheWrite, {
-                    attributes: runMetricAttributes,
-                });
-                Sentry.metrics.distribution("agent.run.cost", totalUsage.cost.total, {
-                    attributes: runMetricAttributes,
-                });
-                Sentry.metrics.gauge("agent.context.utilization", contextTokens / contextWindow, {
-                    unit: "ratio",
-                    attributes: runMetricAttributes,
-                });
-                const summary = log.logUsageSummary(runState.logCtx, runState.totalUsage, contextTokens, contextWindow);
-                if (platform.diagnostics?.showUsageSummary === true) {
-                    runState.queue.enqueue(() => responseCtx.respondDiagnostic(summary, { style: "muted" }), "usage summary");
-                    await queueChain;
-                }
-            }
+            await prepared.runQueue.wait();
+            await finalizeRunResponse(responseCtx, session, runState);
+            await reportUsageSummary({
+                session,
+                runState,
+                responseCtx,
+                platform,
+                model,
+                agentConfig,
+                sessionConversation: prepared.sessionConversation,
+                sessionUuid,
+                waitForQueue: () => prepared.runQueue.wait(),
+            });
             // Clear run state
             runState.responseCtx = null;
             runState.logCtx = null;