@gencode/agents 0.0.3 → 0.0.5

package/dist/runner/runner.js

@@ -1,46 +1,17 @@
-import { Agent } from "@mariozechner/pi-agent-core";
-import { registerApiProvider, registerBuiltInApiProviders } from "@mariozechner/pi-ai";
-import os from "node:os";
-import { createSession, ensureSession, loadTranscript, appendTranscriptEntry, saveSessionMetadata } from "../session/session.js";
 import { loadBootstrapFiles, buildBootstrapContextFiles } from "../bootstrap/bootstrap.js";
 import { loadSkillsWithPluginDirs } from "../skills/skills.js";
-import { buildSystemPrompt } from "../system-prompt/builder.js";
-import { createAgentTools } from "../tools/index.js";
-import { createBuiltinMemoryProvider } from "../memory/builtin-provider.js";
-import { resolveMemoryProvider } from "../memory/provider-registry.js";
-import { startMemoryWatchBridge } from "../memory/watch-bridge.js";
 import { SubagentRegistry } from "../subagent/registry.js";
-import { buildSubagentAnnounceMessage } from "../tools/subagent-spawn.js";
-import { manageHistory } from "../history/index.js";
-import { wrapToolsWithLoopDetection, } from "../loop-detection/tool-loop-detection.js";
-import { clearLoopDetectionState, getLoopDetectionState } from "../loop-detection/session-state.js";
-import path from "node:path";
-import { initializePluginSystem } from "../plugins/manager.js";
-import { PluginHookRegistry } from "../plugins/hooks.js";
-import { wrapToolsWithHooks } from "../plugins/tool-hooks.js";
-import { handleSlashCommand, parseResetCommand } from "../commands/index.js";
-import { handleNewCommand } from "../commands/new.js";
-import { handleResetCommand } from "../commands/reset.js";
-import { compactTranscriptNow } from "../commands/compact.js";
-import { LlmRequestError } from "../llm/client.js";
-import { streamOpenAICompletionsCompat, streamSimpleOpenAICompletionsCompat, } from "../llm/openai-completions-compat.js";
+import { clearLoopDetectionState } from "../loop-detection/session-state.js";
 import { SkillUsageTracker } from "./skill-usage.js";
-// Register built-in API providers (must be called once at startup)
-registerBuiltInApiProviders();
-registerApiProvider({
-    api: "openai-completions",
-    stream: streamOpenAICompletionsCompat,
-    streamSimple: streamSimpleOpenAICompletionsCompat,
-});
-/** Maximum rounds of subagent announce to prevent infinite delegation loops */
-const MAX_ANNOUNCE_ROUNDS = 10;
-const MEMORY_EVENT_DEDUPE_WINDOW_MS = 1_000;
-const EXTERNAL_WATCH_SUPPRESS_WINDOW_MS = 3_000;
-/** Generates a session title by truncating the first user message */
-export function generateSessionTitle(message, maxLength = 80) {
-    const trimmed = message.trim().replace(/\s+/g, " ");
-    return trimmed.length <= maxLength ? trimmed : trimmed.slice(0, maxLength - 1) + "…";
-}
+import { ensureRunnerRuntimeInitialized } from "./runtime.js";
+import { RunEventDispatcher } from "./event-dispatcher.js";
+import { finalizeCompletedRun } from "./finalizer.js";
+import { handleInvocation, prepareInvocation } from "./invocation-resolver.js";
+import { createAgentRuntime } from "./agent-runtime.js";
+import { executeAgentTurn, persistTurnEntriesWithWriter } from "./turn-executor.js";
+import { runAnnounceLoop } from "./announce-loop.js";
+import { createRunnerSession } from "./runner-session.js";
+export { generateSessionTitle } from "./title.js";
 /**
  * Creates a Model object for use with vLLM/OpenAI-compatible APIs.
  */
@@ -68,519 +39,39 @@ function createOpenAICompatModel(params, sessionId) {
         },
     };
 }
-function normalizeMemoryChangedFiles(files) {
-    const result = [];
-    const seen = new Set();
-    for (const raw of files) {
-        const normalized = raw.replace(/\\/g, "/").replace(/^\.\//, "").trim();
-        if (!normalized) {
-            continue;
-        }
-        const canonical = normalized.toLowerCase() === "memory.md" ? "MEMORY.md" : normalized;
-        const key = canonical.toLowerCase();
-        if (seen.has(key)) {
-            continue;
-        }
-        seen.add(key);
-        result.push(canonical);
-    }
-    return result;
-}
-function isTextRunParams(params) {
-    return typeof params.message === "string";
-}
-function extractLeadingUserTextMessage(messages) {
-    for (let index = 0; index < messages.length; index += 1) {
-        const candidate = messages[index];
-        if (candidate.role !== "user") {
-            continue;
-        }
-        if (typeof candidate.content === "string") {
-            return { index, text: candidate.content };
-        }
-        if (!Array.isArray(candidate.content) || candidate.content.length === 0) {
-            return null;
-        }
-        const firstBlock = candidate.content[0];
-        if (firstBlock?.type === "text" && typeof firstBlock.text === "string") {
-            return { index, text: firstBlock.text };
-        }
-        return null;
-    }
-    return null;
-}
-function replaceLeadingUserTextMessage(messages, replacement) {
-    const match = extractLeadingUserTextMessage(messages);
-    if (!match) {
-        return messages;
-    }
-    return messages.map((message, index) => {
-        if (index !== match.index) {
-            return message;
-        }
-        const candidate = message;
-        if (typeof candidate.content === "string") {
-            return { ...message, content: replacement };
-        }
-        if (Array.isArray(candidate.content) && candidate.content.length > 0) {
-            return {
-                ...message,
-                content: candidate.content.map((block, blockIndex) => {
-                    if (blockIndex !== 0) {
-                        return block;
-                    }
-                    const typedBlock = block;
-                    if (typedBlock?.type === "text" && typeof typedBlock.text === "string") {
-                        return { ...typedBlock, text: replacement };
-                    }
-                    return block;
-                }),
-            };
-        }
-        return message;
-    });
-}
-function serializeUserInput(input) {
-    return typeof input === "string" ? input : JSON.stringify(input);
-}
-/** Convert a captured AssistantMessage to an AssistantEntry for the transcript */
-function assistantMessageToEntry(msg) {
-    const text = msg.content
-        .filter((b) => b.type === "text")
-        .map((b) => b.text)
-        .join("");
-    const toolCalls = msg.content
-        .filter((b) => b.type === "toolCall")
-        .map((b) => ({ id: b.id, name: b.name, arguments: b.arguments }));
-    if (text.trim().length === 0 && toolCalls.length === 0) {
-        return null;
-    }
-    const entry = { role: "assistant", content: text, timestamp: new Date().toISOString() };
-    if (toolCalls.length > 0)
-        entry.toolCalls = toolCalls;
-    return entry;
-}
-/** Convert a captured tool result to a ToolResultEntry for the transcript */
-function capturedToolResultToEntry(tr) {
-    return {
-        role: "tool_result",
-        toolCallId: tr.toolCallId,
-        toolName: tr.toolName,
-        content: tr.content,
-        isError: tr.isError,
-        timestamp: new Date().toISOString(),
-    };
-}
-// ── Callbacks ─────────────────────────────────────────────────────────────
-/**
- * Sends an HTTP callback to the given URL.
- * Errors are silently ignored to not interfere with the main flow.
- */
-async function sendCallback(url, payload) {
-    try {
-        await fetch(url, {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify(payload),
-        });
-    }
-    catch {
-        // Callback failures are non-fatal
-    }
-}
-/**
- * Dispatches a progress event to both the in-process callback and the HTTP callback.
- */
-async function dispatchProgress(sessionId, event, params) {
-    const eventWithMessageId = params.messageId ? { ...event, messageId: params.messageId } : event;
-    await params.onProgress?.(eventWithMessageId);
-    if (params.callbackUrl) {
-        await sendCallback(params.callbackUrl, {
-            sessionId,
-            channel: params.channel,
-            messageId: params.messageId,
-            type: "progress",
-            event: eventWithMessageId,
-        });
-    }
-}
-// ── Helpers ───────────────────────────────────────────────────────────────
-/**
- * Builds a single announce message from a batch of completed subagent runs.
- * Batching reduces the number of extra LLM turns needed.
- */
-function buildBatchAnnounceMessage(completed) {
-    if (completed.length === 1) {
-        const r = completed[0];
-        return buildSubagentAnnounceMessage({
-            task: r.task,
-            label: r.label,
-            status: r.status,
-            result: r.result,
-            error: r.error,
-        });
-    }
-    const parts = completed.map((r) => buildSubagentAnnounceMessage({
-        task: r.task,
-        label: r.label,
-        status: r.status,
-        result: r.result,
-        error: r.error,
-    }));
-    return `[${completed.length} subagents completed]\n\n${parts.join("\n\n---\n\n")}`;
-}
-// ── Agent turn runner ─────────────────────────────────────────────────────
-/**
- * Runs one invocation of agent.prompt() and collects text output, usage, and
- * full turn records (via `turn_end` events when the SDK fires them).
- */
-async function runAgentTurn(agent, message, sessionId, modelId, historyMessages, params, skillUsageTracker, hooks, hookCtx, abortSignal) {
-    let pendingTextChunk = "";
-    let lastTextChunk = "";
-    let inputTokens = 0;
-    let outputTokens = 0;
-    let runError;
-    let sdkError;
-    const turnRecords = [];
-    const flushPendingTextChunk = async () => {
-        if (!pendingTextChunk) {
-            return;
-        }
-        lastTextChunk = pendingTextChunk;
-        await dispatchProgress(sessionId, { type: "text", text: pendingTextChunk }, params);
-        pendingTextChunk = "";
-    };
-    const unsubscribe = agent.subscribe(async (event) => {
-        if (event.type === "message_update") {
-            const assistantEvent = event.assistantMessageEvent;
-            if (assistantEvent.type === "text_delta" && typeof assistantEvent.delta === "string") {
-                pendingTextChunk += assistantEvent.delta;
-            }
-            if (assistantEvent.type === "done") {
-                const msg = assistantEvent.message;
-                if (msg.usage) {
-                    inputTokens = msg.usage.input;
-                    outputTokens = msg.usage.output;
-                }
-                await flushPendingTextChunk();
-            }
-        }
-        else if (event.type === "message_end") {
-            const msg = event.message;
-            if (msg.usage) {
-                inputTokens = msg.usage.input;
-                outputTokens = msg.usage.output;
-            }
-        }
-        else if (event.type === "turn_end") {
-            // Capture full turn for high-fidelity transcript persistence
-            const msg = event.message;
-            if (msg.stopReason === "error" || msg.stopReason === "aborted") {
-                sdkError = msg.errorMessage ?? (msg.stopReason === "aborted" ? "aborted" : "Unknown LLM error");
-            }
-            const rawResults = (event.toolResults ?? []);
-            const toolResults = rawResults.map((r) => ({
-                toolCallId: r.toolCallId,
-                toolName: r.toolName,
-                content: r.content
-                    .filter((c) => c.type === "text")
-                    .map((c) => c.text ?? "")
-                    .join(""),
-                isError: r.isError,
-            }));
-            turnRecords.push({ message: msg, toolResults });
-        }
-        else if (event.type === "tool_execution_start") {
-            await flushPendingTextChunk();
-            skillUsageTracker.onToolExecutionStart({ toolName: event.toolName, args: event.args });
-            await dispatchProgress(sessionId, { type: "tool_start", name: event.toolName, input: event.args }, params);
-        }
-        else if (event.type === "tool_execution_end") {
-            await skillUsageTracker.onToolExecutionEnd({ toolName: event.toolName, isError: event.isError });
-            const output = typeof event.result === "string" ? event.result : JSON.stringify(event.result);
-            await dispatchProgress(sessionId, { type: "tool_end", name: event.toolName, output, isError: event.isError }, params);
-        }
-    });
-    try {
-        await hooks.dispatch("llm_input", {
-            sessionId,
-            model: modelId,
-            prompt: typeof message === "string" ? message : JSON.stringify(message),
-            historyMessages,
-        }, hookCtx);
-        if (abortSignal?.aborted) {
-            throw new Error("aborted");
-        }
-        if (typeof message === "string") {
-            await agent.prompt(message);
-        }
-        else {
-            await agent.prompt(message);
-        }
-        if (!runError) {
-            const stateError = typeof agent.state.error === "string" ? agent.state.error : undefined;
-            const latentError = sdkError ?? stateError;
-            if (latentError) {
-                runError = formatRunError(latentError);
-                await dispatchProgress(sessionId, { type: "error", message: runError }, params);
-            }
-        }
-    }
-    catch (err) {
-        runError = formatRunError(err);
-        await dispatchProgress(sessionId, { type: "error", message: runError }, params);
-    }
-    finally {
-        unsubscribe();
-    }
-    const lastAssistant = turnRecords.length > 0 ? turnRecords[turnRecords.length - 1]?.message : undefined;
-    await hooks.dispatch("llm_output", {
-        sessionId,
-        model: modelId,
-        assistantTexts: lastTextChunk ? [lastTextChunk] : [],
-        lastAssistant,
-        usage: { input: inputTokens, output: outputTokens, total: inputTokens + outputTokens },
-    }, hookCtx);
-    return { text: lastTextChunk, inputTokens, outputTokens, error: runError, turnRecords };
-}
-function formatRunError(error) {
-    const llmError = toLlmRequestErrorLike(error);
-    if (llmError) {
-        if (llmError.code === "http_error" && llmError.statusCode) {
-            return llmError.providerMessage
-                ? `LLM upstream returned HTTP ${llmError.statusCode}${llmError.statusText ? ` ${llmError.statusText}` : ""}: ${llmError.providerMessage}`
-                : `LLM upstream returned HTTP ${llmError.statusCode}${llmError.statusText ? ` ${llmError.statusText}` : ""}`;
-        }
-        if (llmError.code === "timeout") {
-            return "LLM request timed out";
-        }
-        if (llmError.code === "network_error") {
-            return llmError.message;
-        }
-        if (llmError.code === "aborted") {
-            return "LLM request was aborted";
-        }
-        return llmError.message;
-    }
-    return error instanceof Error ? error.message : String(error);
-}
-function toLlmRequestErrorLike(error) {
-    if (error instanceof LlmRequestError) {
-        return error;
-    }
-    if (!(error instanceof Error)) {
-        return null;
-    }
-    const candidate = error;
-    if (error.name !== "LlmRequestError" && !candidate.code) {
-        return null;
-    }
-    return {
-        message: error.message,
-        code: candidate.code,
-        statusCode: candidate.statusCode,
-        statusText: candidate.statusText,
-        providerMessage: candidate.providerMessage,
-    };
-}
-/**
- * Persist the assistant's response to the transcript.
- * Uses turn_end records (with tool calls/results) when available;
- * falls back to a plain text entry otherwise.
- */
-async function persistTurnEntries(dataDir, sessionId, turn, options) {
-    if (turn.turnRecords.length > 0) {
-        for (const record of turn.turnRecords) {
-            const assistantEntry = assistantMessageToEntry(record.message);
-            if (assistantEntry) {
-                await appendTranscriptEntry(dataDir, sessionId, assistantEntry, options);
-            }
-            for (const tr of record.toolResults) {
-                await appendTranscriptEntry(dataDir, sessionId, capturedToolResultToEntry(tr), options);
-            }
-        }
-    }
-    else if (turn.text) {
-        await appendTranscriptEntry(dataDir, sessionId, {
-            role: "assistant",
-            content: turn.text,
-            timestamp: new Date().toISOString(),
-        }, options);
-    }
-}
 // ── Internal runner ───────────────────────────────────────────────────────
 /**
  * Internal runner shared by both top-level and subagent invocations.
  */
 async function runAgentInternal(params, registry) {
+    ensureRunnerRuntimeInitialized();
     const startTime = Date.now();
-    const inputMode = isTextRunParams(params) ? "text" : "messages";
-    const rawMessage = inputMode === "text" ? params.message : undefined;
-    const inputMessages = inputMode === "messages" ? params.messages : undefined;
-    const structuredUserText = inputMessages ? extractLeadingUserTextMessage(inputMessages) : null;
-    const slashCommandSource = rawMessage ?? structuredUserText?.text;
-    const resetCommand = slashCommandSource ? parseResetCommand(slashCommandSource) : null;
-    const resetRemainder = resetCommand?.remainder ?? "";
-    const resetShortCircuit = Boolean(resetCommand && !resetRemainder);
-    const messageForRun = resetCommand && resetRemainder ? resetRemainder : slashCommandSource;
-    const promptInput = inputMode === "text"
-        ? (messageForRun ?? "")
-        : (resetCommand && resetRemainder && inputMessages
-            ? replaceLeadingUserTextMessage(inputMessages, resetRemainder)
-            : inputMessages);
-    let transcriptMessage = inputMode === "text"
-        ? (resetShortCircuit ? rawMessage : (messageForRun ?? ""))
-        : serializeUserInput(promptInput);
+    const eventDispatcher = new RunEventDispatcher(params);
+    const invocation = prepareInvocation(params);
+    let transcriptMessage = invocation.transcriptMessage;
     let initialUserEntryPersisted = false;
-    const previousSessionId = resetCommand ? params.sessionId : undefined;
-    const workspaceDir = path.join(params.dataDir, "workspace");
-    // 1. Resolve or create session
-    let sessionId = resetCommand ? undefined : params.sessionId;
-    const isNewSession = !sessionId;
-    if (sessionId) {
-        await ensureSession(params.dataDir, sessionId);
-    }
-    else {
-        sessionId = await createSession(params.dataDir, params.channel);
-    }
-    const hookContext = {
-        sessionId,
-        workspaceDir,
-        channel: params.channel,
-    };
-    const pluginSystem = params.plugins
-        ? initializePluginSystem({
-            ...params.plugins,
-            runtime: {
-                llm: params.llm,
-                hookCtx: hookContext,
-                llmAllowlist: params.plugins.llmAllowlist,
-            },
-        })
-        : undefined;
-    const hookRegistry = pluginSystem?.registry.hooks ?? new PluginHookRegistry();
-    const memoryProviderId = params.memory?.providerId;
-    const memoryPluginId = params.memory?.pluginId ?? pluginSystem?.normalizedConfig.slots?.memory;
-    const recentMemoryWrites = new Map();
-    const recentMemoryEvents = new Map();
-    const emitMemoryChanged = async (event) => {
-        const now = Date.now();
-        const normalizedFiles = normalizeMemoryChangedFiles(event.files);
-        if (normalizedFiles.length === 0) {
-            return;
-        }
-        const filteredFiles = event.reason === "external-watch" && event.source === "memory"
-            ? normalizedFiles.filter((file) => {
-                const lastWriteAt = recentMemoryWrites.get(file.toLowerCase()) ?? 0;
-                return now - lastWriteAt > EXTERNAL_WATCH_SUPPRESS_WINDOW_MS;
-            })
-            : normalizedFiles;
-        if (filteredFiles.length === 0) {
-            return;
-        }
-        if (event.reason !== "external-watch" && event.source === "memory") {
-            for (const file of filteredFiles) {
-                recentMemoryWrites.set(file.toLowerCase(), now);
-            }
-        }
-        const dedupeKey = `${event.reason}|${event.source}|${filteredFiles
-            .map((file) => file.toLowerCase())
-            .sort()
-            .join("|")}`;
-        const previousEventAt = recentMemoryEvents.get(dedupeKey) ?? 0;
-        if (now - previousEventAt < MEMORY_EVENT_DEDUPE_WINDOW_MS) {
-            return;
-        }
-        recentMemoryEvents.set(dedupeKey, now);
-        const eventToEmit = {
-            ...event,
-            files: filteredFiles,
-        };
-        await dispatchProgress(event.sessionId ?? sessionId, {
-            type: "memory_changed",
-            reason: eventToEmit.reason,
-            files: eventToEmit.files,
-            source: eventToEmit.source,
-            providerId: eventToEmit.providerId,
-            timestamp: eventToEmit.timestamp,
-        }, params).catch(() => { });
-        await hookRegistry
-            .dispatch("memory_changed", eventToEmit, {
-            ...hookContext,
-            sessionId: eventToEmit.sessionId ?? hookContext.sessionId,
-        })
-            .catch(() => { });
-    };
-    const transcriptOptions = memoryProviderId || memoryPluginId
-        ? {
-            providerId: memoryProviderId,
-            pluginId: memoryPluginId,
-            onMemoryChanged: emitMemoryChanged,
-        }
-        : { onMemoryChanged: emitMemoryChanged };
-    const persistInitialUserEntry = async () => {
-        if (initialUserEntryPersisted) {
-            return;
-        }
-        await appendTranscriptEntry(params.dataDir, sessionId, {
-            role: "user",
-            content: transcriptMessage,
-            timestamp: new Date().toISOString(),
-        }, transcriptOptions);
-        initialUserEntryPersisted = true;
-    };
-    const memoryRoot = path.join(params.dataDir, ".aimax");
-    const resolvedProvider = resolveMemoryProvider({
-        providerId: memoryProviderId,
-        pluginId: memoryPluginId,
-        dataDir: params.dataDir,
-        memoryDir: memoryRoot,
-        sessionId,
+    const previousSessionId = invocation.previousSessionId;
+    const session = await createRunnerSession({
+        runParams: params,
+        requestedSessionId: invocation.requestedSessionId,
+        eventDispatcher,
     });
-    const provider = resolvedProvider?.provider ??
-        createBuiltinMemoryProvider({ dataDir: params.dataDir, memoryDir: memoryRoot, sessionId });
-    const stopMemoryWatchBridge = startMemoryWatchBridge({
-        dataDir: params.dataDir,
-        sessionId,
-        providerId: memoryProviderId ?? memoryPluginId ?? provider.id,
-        provider,
-        onMemoryChanged: emitMemoryChanged,
+    const sessionId = session.sessionId;
+    const isNewSession = session.isNewSession;
+    const workspaceDir = session.workspaceDir;
+    const hookContext = session.hookContext;
+    const hookRegistry = session.hookRegistry;
+    const pluginContext = session.pluginContext;
+    const runContext = session.runContext;
+    if (invocation.resetCommand) {
+        initialUserEntryPersisted = await runContext.persistInitialUserEntry(transcriptMessage);
+    }
+    await session.start({
+        resetCommand: invocation.resetCommand,
+        previousSessionId,
+        rawMessage: invocation.rawMessage,
+        startMessage: typeof invocation.promptInput === "string" ? invocation.promptInput : transcriptMessage,
     });
-    if (provider.sync) {
-        void provider.sync("session-start").catch(() => { });
-    }
-    if (resetCommand) {
-        await persistInitialUserEntry();
-    }
-    if (resetCommand && params.callbackUrl) {
-        await sendCallback(params.callbackUrl, {
-            sessionId,
-            channel: params.channel,
-            messageId: params.messageId,
-            type: "session_reset",
-            action: resetCommand.action,
-            previousSessionId,
-            message: rawMessage,
-        });
-    }
-    if (resetCommand) {
-        await hookRegistry.dispatch("session_reset", {
-            action: resetCommand.action,
-            sessionId,
-            previousSessionId,
-            message: rawMessage,
-        }, hookContext);
-    }
-    if (params.callbackUrl) {
-        await sendCallback(params.callbackUrl, {
-            sessionId,
-            channel: params.channel,
-            messageId: params.messageId,
-            type: "start",
-            message: typeof promptInput === "string" ? promptInput : transcriptMessage,
-        });
-    }
-    await hookRegistry.dispatch("session_start", { sessionId }, hookContext);
     // 2. Set up abort controller early (needed for manageHistory signal)
     const abortController = new AbortController();
     if (params.abortSignal?.aborted) {
@@ -596,219 +87,57 @@ async function runAgentInternal(params, registry) {
         warn: (message) => bootstrapWarnings.push(message),
     });
     // 4. Load skills (user + plugin skills)
-    const pluginSkillDirs = pluginSystem?.registry.skills ?? [];
-    const skills = await loadSkillsWithPluginDirs(params.dataDir, pluginSkillDirs);
+    const skills = await loadSkillsWithPluginDirs(params.dataDir, pluginContext.pluginSkillDirs);
     const skillUsageTracker = new SkillUsageTracker({
         workspaceDir,
         sessionId,
         skills,
-        report: (event) => dispatchProgress(sessionId, event, params),
+        report: (event) => eventDispatcher.dispatchProgress(sessionId, event),
     });
-    if (resetShortCircuit) {
-        const resetReply = resetCommand?.action === "reset" ? handleResetCommand() : handleNewCommand();
-        return finalizeSlashCommandResult({
-            replyText: resetReply.text,
-            sessionId,
-            isNewSession,
-            transcriptMessage,
-            initialUserEntryPersisted,
-            params,
-            hookRegistry,
-            hookContext,
-            startTime,
-        });
-    }
-    let effectivePrompt = promptInput;
-    if (slashCommandSource) {
-        const slashResult = handleSlashCommand({ message: messageForRun ?? "", skills });
-        if (slashResult.kind === "reply") {
-            return finalizeSlashCommandResult({
-                replyText: slashResult.text,
-                sessionId,
-                isNewSession,
-                transcriptMessage,
-                params,
-                hookRegistry,
-                hookContext,
-                startTime,
-            });
-        }
-        if (slashResult.kind === "compact") {
-            const rawHistory = params.channel === "CRON" ? [] : await loadTranscript(params.dataDir, sessionId);
-            const compactResult = await compactTranscriptNow({
-                entries: rawHistory,
-                contextWindowTokens: params.llm.contextWindow ?? 200_000,
-                llm: {
-                    baseUrl: params.llm.baseUrl,
-                    apiKey: params.llm.apiKey,
-                    model: params.llm.model,
-                },
-                instructions: slashResult.instructions,
-                signal: params.abortSignal,
-                hooks: hookRegistry,
-                hookCtx: hookContext,
-            });
-            const compactText = compactResult.status === "compacted"
-                ? `⚙️ Compacted (kept ${compactResult.keptCount}, dropped ${compactResult.droppedCount}).`
-                : `⚙️ Compaction skipped: ${compactResult.reason}`;
-            return finalizeSlashCommandResult({
-                replyText: compactText,
-                sessionId,
-                isNewSession,
-                transcriptMessage,
-                initialUserEntryPersisted,
-                params,
-                hookRegistry,
-                hookContext,
-                startTime,
-                compactionEntry: compactResult.status === "compacted" ? compactResult.entry : undefined,
-            });
-        }
-        if (slashResult.kind === "rewrite") {
-            effectivePrompt = inputMode === "text"
-                ? slashResult.message
-                : replaceLeadingUserTextMessage(promptInput, slashResult.message);
-            transcriptMessage = serializeUserInput(effectivePrompt);
-        }
-        else if (inputMode === "text") {
-            effectivePrompt = messageForRun ?? "";
-            transcriptMessage = typeof effectivePrompt === "string" ? effectivePrompt : transcriptMessage;
-        }
+    const appendEntry = (entry) => runContext.appendTranscriptEntry(entry);
+    const invocationExecution = await handleInvocation({
+        invocation,
+        skills,
+        sessionId,
+        isNewSession,
+        initialUserEntryPersisted,
+        runParams: params,
+        hookRegistry,
+        hookContext,
+        startTime,
+        eventDispatcher,
+    });
+    if (invocationExecution.kind === "completed") {
+        return invocationExecution.result;
     }
+    const effectivePrompt = invocationExecution.effectivePrompt;
+    transcriptMessage = invocationExecution.transcriptMessage;
     const effectivePromptText = typeof effectivePrompt === "string" ? effectivePrompt : transcriptMessage;
-    // 5. Load and manage conversation history
-    const skipHistory = params.channel === "CRON";
-    const rawHistory = skipHistory ? [] : await loadTranscript(params.dataDir, sessionId);
-    await hookRegistry.dispatch("before_compaction", { messageCount: rawHistory.length }, hookContext);
-    const modelInfo = { model: params.llm.model, api: "openai-completions" };
-    const historyResult = skipHistory
-        ? {
-            messages: [],
-            priorSummary: undefined,
-            compactionEntry: undefined,
-            stats: { originalCount: 0, keptCount: 0, estimatedTokens: 0, compacted: false },
-        }
-        : await manageHistory({
-            entries: rawHistory,
-            modelInfo,
-            contextWindowTokens: params.llm.contextWindow ?? 200_000,
-            llm: {
-                baseUrl: params.llm.baseUrl,
-                apiKey: params.llm.apiKey,
-                model: params.llm.model,
-            },
-            historyLimit: params.historyLimit,
-            compactionEnabled: true,
-            signal: abortController.signal,
-            hooks: hookRegistry,
-            hookCtx: hookContext,
-        });
-    const depth = params.subagentContext?.depth ?? 0;
-    const baseTools = createAgentTools(params.dataDir, {
-        registry,
-        parentSessionId: sessionId,
-        depth,
-        channel: params.channel,
-        llm: params.llm,
-        loopDetection: params.loopDetection,
-        memoryOptions: {
-            providerId: memoryProviderId,
-            pluginId: memoryPluginId,
+    const runtime = await createAgentRuntime({
+        session: {
+            runParams: params,
             sessionId,
-            onMemoryChanged: emitMemoryChanged,
-        },
-        spawnFn: (childParams) => runAgentInternal(childParams, new SubagentRegistry()),
-    });
-    const pluginTools = pluginSystem?.registry.tools.resolveEnabled(params.plugins?.toolAllowlist) ?? [];
-    const rawTools = [...baseTools, ...pluginTools];
-    const toolNames = rawTools
-        .map((tool) => (typeof tool.name === "string" ? tool.name.trim() : ""))
-        .filter(Boolean);
-    const toolSummaries = {};
-    for (const tool of rawTools) {
-        const name = typeof tool.name === "string" ? tool.name.trim() : "";
-        const description = typeof tool.description === "string" ? tool.description.trim() : "";
-        if (!name || !description || toolSummaries[name])
-            continue;
-        toolSummaries[name] = description;
-    }
-    const messagingEnabled = params.messaging?.enabled ?? params.channel !== "CRON";
-    const messagingChannels = params.messaging?.channels && params.messaging.channels.length > 0
-        ? params.messaging.channels
-        : [params.channel];
-    // 6. Build system prompt (with prior summary injected when available)
-    let systemPrompt = buildSystemPrompt({
-        dataDir: params.dataDir,
-        skills,
-        contextFiles,
-        toolNames,
-        toolSummaries,
-        promptMode: depth > 0 ? "minimal" : "full",
-        bootstrapWarnings,
-        memoryCitationsMode: params.memory?.citationsMode ?? "off",
-        messaging: {
-            enabled: messagingEnabled,
-            channels: messagingChannels,
-        },
-        docs: {
-            localPath: params.docs?.localPath,
-            webUrl: params.docs?.webUrl,
-            sourceUrl: params.docs?.sourceUrl,
+            hookRegistry,
+            hookContext,
+            runContext,
+            eventDispatcher,
         },
-        sandboxInfo: {
-            enabled: true,
-            hostWorkspaceDir: workspaceDir,
-            containerWorkspaceDir: workspaceDir,
+        runtimeInputs: {
+            contextFiles,
+            bootstrapWarnings,
+            skills,
+            effectivePromptText,
+            pluginTools: pluginContext.pluginTools,
         },
-        runtimeInfo: {
-            os: process.platform,
-            node: process.version,
-            model: params.llm.model,
-            hostname: os.hostname(),
+        dependencies: {
+            registry,
+            spawnFn: (childParams) => runAgentInternal(childParams, new SubagentRegistry()),
+            createModel: createOpenAICompatModel,
+            abortSignal: abortController.signal,
         },
-        currentDate: new Date().toISOString().split("T")[0],
-        priorConversationSummary: historyResult.priorSummary,
-    });
-    // 7. Persist new compaction entry (if history was summarised this run)
-    if (historyResult.compactionEntry) {
-        await appendTranscriptEntry(params.dataDir, sessionId, historyResult.compactionEntry, transcriptOptions);
-        await dispatchProgress(sessionId, {
-            type: "compaction",
-            reason: `Summarised ${historyResult.stats.originalCount - historyResult.stats.keptCount} older entries`,
-        }, params);
-        await hookRegistry.dispatch("after_compaction", {
-            messageCount: historyResult.stats.originalCount,
-            compactedCount: historyResult.stats.originalCount - historyResult.stats.keptCount,
-        }, hookContext);
-    }
-    const beforePromptResults = await hookRegistry.dispatch("before_prompt_build", { prompt: effectivePromptText }, hookContext);
-    for (const result of beforePromptResults) {
-        if (!result)
-            continue;
-        if (result.systemPrompt) {
-            systemPrompt = result.systemPrompt;
-        }
-        if (result.prependContext) {
-            systemPrompt = `${result.prependContext}\n\n${systemPrompt}`;
-        }
-    }
-    // 8. Create tools (subagent tools included for all agents)
-    const toolsWithHooks = wrapToolsWithHooks(rawTools, hookRegistry, hookContext);
-    const tools = wrapToolsWithLoopDetection(toolsWithHooks, { sessionId, config: params.loopDetection }, getLoopDetectionState);
-    // 9. Create the model and agent
-    let resolvedModelId = params.llm.model;
-    const beforeModelResults = await hookRegistry.dispatch("before_model_resolve", { prompt: effectivePromptText }, hookContext);
-    for (const result of beforeModelResults) {
-        if (result && result.modelOverride) {
-            resolvedModelId = result.modelOverride;
-        }
-    }
-    const model = createOpenAICompatModel({ ...params.llm, model: resolvedModelId }, sessionId);
-    const apiKey = params.llm.apiKey;
-    const agent = new Agent({
-        initialState: { systemPrompt, model, tools, messages: [] },
-        getApiKey: (_provider) => apiKey,
     });
+    const agent = runtime.agent;
+    const resolvedModelId = runtime.resolvedModelId;
     // 10. Wire timeout to abort the agent
     const timeoutMs = params.timeoutMs ?? 600_000;
     const timeoutHandle = setTimeout(() => {
@@ -817,10 +146,6 @@ async function runAgentInternal(params, registry) {
     }, timeoutMs);
     // Also propagate future aborts to the agent
     abortController.signal.addEventListener("abort", () => agent.abort());
-    // 11. Restore managed history into the agent
-    if (historyResult.messages.length > 0) {
-        agent.replaceMessages(historyResult.messages);
-    }
     let totalInputTokens = 0;
     let totalOutputTokens = 0;
     let lastResponseText = "";
@@ -828,155 +153,71 @@ async function runAgentInternal(params, registry) {
     try {
         // 12. Persist the initial user turn before the first model call so the
         // transcript still records the request if the turn aborts or fails.
-        await persistInitialUserEntry();
+        initialUserEntryPersisted = (await runContext.persistInitialUserEntry(transcriptMessage)) || initialUserEntryPersisted;
         // 13. First agent turn
-        const turn = await runAgentTurn(agent, effectivePrompt, sessionId, resolvedModelId, historyResult.messages, params, skillUsageTracker, hookRegistry, hookContext, abortController.signal);
+        const turn = await executeAgentTurn({
+            agent,
+            message: effectivePrompt,
+            sessionId,
+            modelId: resolvedModelId,
+            historyMessages: runtime.historyMessages,
+            eventDispatcher,
+            skillUsageTracker,
+            hooks: hookRegistry,
+            hookCtx: hookContext,
+            abortSignal: abortController.signal,
+        });
         lastResponseText = turn.text;
         totalInputTokens += turn.inputTokens;
         totalOutputTokens += turn.outputTokens;
         if (turn.error)
             runError = turn.error;
         // 14. Persist the assistant/tool outputs from the first turn.
-        await persistTurnEntries(params.dataDir, sessionId, turn, transcriptOptions);
-        // 15. Announce loop — deliver subagent results back to the parent agent.
-        let announceRound = 0;
-        while (!abortController.signal.aborted &&
-            registry.needsAnnounce(sessionId) &&
-            announceRound < MAX_ANNOUNCE_ROUNDS) {
-            announceRound++;
-            await registry.waitForAll(sessionId);
-            const completed = registry.consumeCompleted(sessionId);
-            if (completed.length === 0)
-                break;
-            for (const r of completed) {
-                await dispatchProgress(sessionId, {
-                    type: "subagent_complete",
-                    childSessionId: r.childSessionId,
-                    task: r.task,
-                    status: r.status,
-                }, params);
-            }
-            const announceMsg = buildBatchAnnounceMessage(completed);
-            await appendTranscriptEntry(params.dataDir, sessionId, {
-                role: "user",
-                content: announceMsg,
-                timestamp: new Date().toISOString(),
-            }, transcriptOptions);
-            const announceTurn = await runAgentTurn(agent, announceMsg, sessionId, resolvedModelId, [], params, skillUsageTracker, hookRegistry, hookContext, abortController.signal);
-            lastResponseText = announceTurn.text;
-            totalInputTokens += announceTurn.inputTokens;
-            totalOutputTokens += announceTurn.outputTokens;
-            if (announceTurn.error && !runError)
-                runError = announceTurn.error;
-            await persistTurnEntries(params.dataDir, sessionId, announceTurn, transcriptOptions);
+        await persistTurnEntriesWithWriter(appendEntry, turn);
+        const announceResult = await runAnnounceLoop({
+            agent,
+            registry,
+            sessionId,
+            resolvedModelId,
+            eventDispatcher,
+            skillUsageTracker,
+            hookRegistry,
+            hookContext,
+            abortSignal: abortController.signal,
+            appendEntry,
+        });
+        if (announceResult.text) {
+            lastResponseText = announceResult.text;
+        }
+        totalInputTokens += announceResult.inputTokens;
+        totalOutputTokens += announceResult.outputTokens;
+        if (announceResult.error && !runError) {
+            runError = announceResult.error;
         }
     }
     finally {
         clearTimeout(timeoutHandle);
         clearLoopDetectionState(sessionId);
-        stopMemoryWatchBridge();
+        runContext.stop();
     }
-    // 15. Save session metadata for new sessions
-    if (isNewSession) {
-        const title = generateSessionTitle(transcriptMessage);
-        const now = new Date().toISOString();
-        await saveSessionMetadata(params.dataDir, {
-            id: sessionId,
-            title,
-            channel: params.channel,
-            createdAt: now,
-            updatedAt: now,
-        });
-    }
-    const durationMs = Date.now() - startTime;
     const usage = {
         input: totalInputTokens,
         output: totalOutputTokens,
         total: totalInputTokens + totalOutputTokens,
     };
-    const result = {
+    return finalizeCompletedRun({
         sessionId,
+        isNewSession,
+        transcriptMessage,
+        runParams: params,
+        hookRegistry,
+        hookContext,
+        startTime,
+        eventDispatcher,
         text: lastResponseText,
         usage,
-        durationMs,
         error: runError,
-    };
-    await hookRegistry.dispatch("agent_end", { success: !runError, error: runError, durationMs }, hookContext);
-    const finalTranscript = await loadTranscript(params.dataDir, sessionId);
-    await hookRegistry.dispatch("session_end", { sessionId, messageCount: finalTranscript.length, durationMs }, hookContext);
-    // 16. Send final callback
-    if (params.callbackUrl) {
-        if (runError) {
-            await sendCallback(params.callbackUrl, {
-                sessionId,
-                channel: params.channel,
-                messageId: params.messageId,
-                type: "error",
-                message: runError,
-            });
-        }
-        else {
-            await sendCallback(params.callbackUrl, {
-                sessionId,
-                channel: params.channel,
-                messageId: params.messageId,
-                type: "done",
-                result: { text: lastResponseText, usage, durationMs },
-            });
-        }
-    }
-    return result;
-}
-async function finalizeSlashCommandResult(params) {
-    const { replyText, sessionId, isNewSession, transcriptMessage, initialUserEntryPersisted = false, params: runParams, hookRegistry, hookContext, startTime, compactionEntry, } = params;
-    if (!initialUserEntryPersisted) {
-        await appendTranscriptEntry(runParams.dataDir, sessionId, {
-            role: "user",
-            content: transcriptMessage,
-            timestamp: new Date().toISOString(),
-        });
-    }
-    if (compactionEntry) {
-        await appendTranscriptEntry(runParams.dataDir, sessionId, compactionEntry);
-    }
-    await appendTranscriptEntry(runParams.dataDir, sessionId, {
-        role: "assistant",
-        content: replyText,
-        timestamp: new Date().toISOString(),
     });
-    if (isNewSession) {
-        const titleSource = transcriptMessage.trim() ? transcriptMessage : "New session";
-        const title = generateSessionTitle(titleSource);
-        const now = new Date().toISOString();
-        await saveSessionMetadata(runParams.dataDir, {
-            id: sessionId,
-            title,
-            channel: runParams.channel,
-            createdAt: now,
-            updatedAt: now,
-        });
-    }
-    const durationMs = Date.now() - startTime;
-    const usage = { input: 0, output: 0, total: 0 };
-    const result = {
-        sessionId,
-        text: replyText,
-        usage,
-        durationMs,
-    };
-    await hookRegistry.dispatch("agent_end", { success: true, error: undefined, durationMs }, hookContext);
-    const finalTranscript = await loadTranscript(runParams.dataDir, sessionId);
-    await hookRegistry.dispatch("session_end", { sessionId, messageCount: finalTranscript.length, durationMs }, hookContext);
-    if (runParams.callbackUrl) {
-        await sendCallback(runParams.callbackUrl, {
-            sessionId,
-            channel: runParams.channel,
-            messageId: runParams.messageId,
-            type: "done",
-            result: { text: replyText, usage, durationMs },
-        });
-    }
-    return result;
 }
 /**
  * Runs an agent session end-to-end.