@apolloyh/apollo-agent 0.1.0

package/dist/runtime/query-engine.js

@@ -0,0 +1,1182 @@
+import { createHash } from "node:crypto";
+import { AnthropicApiError, AnthropicClient, MalformedStreamError, } from "../llm/anthropic.js";
+import { ContextManager, isContextSummary } from "./context.js";
+import { buildCompactionTranscript, COMPACTION_SYSTEM_PROMPT, normalizeCompactionSummary, } from "./compaction.js";
+import { createCliApprovalProvider } from "./permissions.js";
+import { SkillManager } from "../skills/skills.js";
+import { McpManager } from "../mcp/manager.js";
+import { createBuiltinRegistry } from "../tools/builtin.js";
+import { MAX_TOOL_RESULT_CHARS } from "../tools/registry.js";
+import { messageText, stringify, truncate, truncateMiddle } from "../utils.js";
+import { PromptBuilder } from "./prompt-builder.js";
+import { loadProjectInstructions } from "../project-instructions.js";
+import { HookRunner } from "../hooks/runner.js";
+import { memoryContextBlock } from "../memory/memdir.js";
+import { planModeSystemExtra, readPlan, } from "../plan/plan-mode.js";
+import { applyWorkflowMarkers, createWorkflow, workflowStatusBar, workflowSystemExtra, } from "../coordinator/workflow.js";
+import { createSession, loadLatestSession, loadSession, listSessions, saveSession, } from "../session/store.js";
+import { skillifySession } from "../skillify/skillify.js";
+import { applyGoalMarkers, createGoal, goalStatusBar, goalSystemExtra, nextGoalContinuePrompt, shouldAutoContinue, } from "../goal/goal-mode.js";
+const TASK_TOOL_NAMES = new Set(["Task"]);
+const MAX_API_RETRIES = 3;
+const MAX_RETRY_DELAY_MS = 30_000;
+const MAX_OUTPUT_RECOVERIES = 2;
+export class QueryEngine {
+    options;
+    client;
+    contextManager;
+    skillManager;
+    mcpManager;
+    hooks;
+    messages = [];
+    archivedMessages = [];
+    projectInstructionsCache;
+    stableSystemPrompt;
+    stableToolDefinitions;
+    mode = "normal";
+    plan = null;
+    workflow = null;
+    goal = null;
+    session = null;
+    askUser;
+    usage = emptyUsageCounters();
+    usageByCategory = {
+        main: emptyUsageCounters(),
+        task: emptyUsageCounters(),
+        compaction: emptyUsageCounters(),
+    };
+    latestUsageByCategory = {
+        main: null,
+        task: null,
+        compaction: null,
+    };
+    loadedSkillPaths = new Set();
+    seenMemoryBlocks = new Set();
+    lastPlanContext;
+    lastWorkflowState;
+    lastGoalState;
+    skillCatalogSnapshot;
+    lastCacheRequest = new Map();
+    cacheDiagnostics = {
+        prefixFingerprint: null,
+        configFingerprint: null,
+        systemFingerprint: null,
+        toolsFingerprint: null,
+        missesAfterHit: 0,
+        lastMissReason: null,
+    };
+    activeTurnAbort;
+    constructor(options) {
+        this.options = options;
+        this.client = new AnthropicClient(options.llmConfig);
+        this.contextManager = new ContextManager(options.agentConfig.context, options.emit);
+        this.skillManager = new SkillManager(options.agentConfig);
+        this.mcpManager = new McpManager(options.agentConfig);
+        this.hooks = new HookRunner(options.agentConfig.workspaceRoot);
+        this.askUser = options.askUser;
+    }
+    getMode() {
+        return this.mode;
+    }
+    getWorkflow() {
+        return this.workflow;
+    }
+    getGoal() {
+        return this.goal;
+    }
+    getPlan() {
+        return this.plan;
+    }
+    getSessionId() {
+        return this.session?.meta.id ?? null;
+    }
+    cancelCurrentTurn() {
+        if (!this.activeTurnAbort || this.activeTurnAbort.signal.aborted)
+            return false;
+        this.activeTurnAbort.abort();
+        return true;
+    }
+    getMessages() {
+        return this.messages;
+    }
+    setMessages(messages) {
+        this.messages = messages;
+        this.archivedMessages = [];
+    }
+    conversationSize() {
+        return this.messages.length;
+    }
+    getUsageStats() {
+        return {
+            ...usageStats(this.usage),
+            byCategory: {
+                main: usageStats(this.usageByCategory.main),
+                task: usageStats(this.usageByCategory.task),
+                compaction: usageStats(this.usageByCategory.compaction),
+            },
+            latestByCategory: {
+                main: this.latestUsageByCategory.main ? usageStats(this.latestUsageByCategory.main) : null,
+                task: this.latestUsageByCategory.task ? usageStats(this.latestUsageByCategory.task) : null,
+                compaction: this.latestUsageByCategory.compaction ? usageStats(this.latestUsageByCategory.compaction) : null,
+            },
+            cacheDiagnostics: { ...this.cacheDiagnostics },
+        };
+    }
+    getCacheMode() {
+        try {
+            if (new URL(this.options.llmConfig.baseUrl).hostname.endsWith("bigmodel.cn")) {
+                return "GLM implicit (provider-managed)";
+            }
+        }
+        catch {
+            /* display fallback below */
+        }
+        return `Anthropic-compatible (${this.options.llmConfig.cacheTtl ?? "5m"} requested)`;
+    }
+    async close() {
+        await this.mcpManager.closeAll();
+    }
+    async ensureSession(title) {
+        if (this.session)
+            return this.session;
+        this.session = await createSession(this.options.agentConfig.workspaceRoot, title, this.mode);
+        return this.session;
+    }
+    async saveCurrentSession() {
+        if (!this.session)
+            await this.ensureSession();
+        if (!this.session)
+            return null;
+        this.session.messages = this.messages;
+        this.session.archivedMessages = this.archivedMessages;
+        this.session.usage = {
+            total: { ...this.usage },
+            byCategory: {
+                main: { ...this.usageByCategory.main },
+                task: { ...this.usageByCategory.task },
+                compaction: { ...this.usageByCategory.compaction },
+            },
+            latestByCategory: {
+                ...(this.latestUsageByCategory.main ? { main: { ...this.latestUsageByCategory.main } } : {}),
+                ...(this.latestUsageByCategory.task ? { task: { ...this.latestUsageByCategory.task } } : {}),
+                ...(this.latestUsageByCategory.compaction ? { compaction: { ...this.latestUsageByCategory.compaction } } : {}),
+            },
+        };
+        this.session.meta.mode = this.mode;
+        this.session.plan = this.plan
+            ? { path: this.plan.path, content: this.plan.content, approved: this.plan.approved }
+            : null;
+        this.session.workflow = this.workflow
+            ? { goal: this.workflow.goal, phases: this.workflow.phases }
+            : null;
+        this.session.goal = this.goal
+            ? {
+                goal: this.goal.goal,
+                status: this.goal.status,
+                criteria: this.goal.criteria,
+                progress: this.goal.progress,
+                iteration: this.goal.iteration,
+                maxIterations: this.goal.maxIterations,
+                startedAt: this.goal.startedAt,
+                completedAt: this.goal.completedAt,
+                lastBlockedReason: this.goal.lastBlockedReason,
+            }
+            : null;
+        return saveSession(this.options.agentConfig.workspaceRoot, this.session);
+    }
+    async resumeSession(id) {
+        const snap = id
+            ? await loadSession(this.options.agentConfig.workspaceRoot, id)
+            : await loadLatestSession(this.options.agentConfig.workspaceRoot);
+        if (!snap)
+            return null;
+        this.session = snap;
+        this.messages = snap.messages ?? [];
+        this.archivedMessages = snap.archivedMessages ?? [];
+        this.usage = restoreUsageCounters(snap.usage?.total);
+        this.usageByCategory = {
+            main: restoreUsageCounters(snap.usage?.byCategory?.main),
+            task: restoreUsageCounters(snap.usage?.byCategory?.task),
+            compaction: restoreUsageCounters(snap.usage?.byCategory?.compaction),
+        };
+        this.latestUsageByCategory = {
+            main: restoreLatestUsage(snap.usage?.latestByCategory?.main),
+            task: restoreLatestUsage(snap.usage?.latestByCategory?.task),
+            compaction: restoreLatestUsage(snap.usage?.latestByCategory?.compaction),
+        };
+        this.lastCacheRequest.clear();
+        this.cacheDiagnostics = {
+            prefixFingerprint: null,
+            configFingerprint: null,
+            systemFingerprint: null,
+            toolsFingerprint: null,
+            missesAfterHit: 0,
+            lastMissReason: null,
+        };
+        this.mode = snap.meta.mode ?? "normal";
+        this.contextManager.clear();
+        this.resetRuntimeContextTracking();
+        this.skillCatalogSnapshot = undefined;
+        this.plan = null;
+        this.workflow = null;
+        this.goal = null;
+        if (snap.plan) {
+            this.plan = {
+                active: this.mode === "plan" || !snap.plan.approved,
+                path: snap.plan.path,
+                content: snap.plan.content,
+                approved: snap.plan.approved,
+                createdAt: snap.meta.createdAt,
+            };
+        }
+        if (snap.workflow) {
+            this.workflow = {
+                goal: snap.workflow.goal,
+                phases: snap.workflow.phases,
+                startedAt: snap.meta.createdAt,
+                maxRetries: 2,
+            };
+        }
+        if (snap.goal) {
+            this.goal = {
+                goal: snap.goal.goal,
+                status: snap.goal.status,
+                criteria: snap.goal.criteria ?? [],
+                progress: snap.goal.progress ?? [],
+                iteration: snap.goal.iteration ?? 0,
+                maxIterations: snap.goal.maxIterations ?? 12,
+                startedAt: snap.goal.startedAt,
+                completedAt: snap.goal.completedAt,
+                lastBlockedReason: snap.goal.lastBlockedReason,
+            };
+        }
+        this.options.emit({
+            type: "plan_mode",
+            active: this.mode === "plan",
+            approved: this.plan?.approved,
+            path: this.plan?.path,
+        });
+        if (this.workflow) {
+            this.options.emit({
+                type: "workflow_status",
+                goal: this.workflow.goal,
+                phases: this.workflow.phases.map((p) => ({
+                    name: p.name,
+                    label: p.label,
+                    status: p.status,
+                    summary: p.summary,
+                })),
+            });
+        }
+        return snap;
+    }
+    async listSessions() {
+        return listSessions(this.options.agentConfig.workspaceRoot);
+    }
+    async enterPlanMode() {
+        this.lastPlanContext = undefined;
+        this.mode = "plan";
+        this.plan = (await readPlan(this.options.agentConfig.workspaceRoot)) ?? {
+            active: true,
+            path: `${this.options.agentConfig.workspaceRoot}/.apollo/plan.md`,
+            content: "",
+            approved: false,
+            createdAt: new Date().toISOString(),
+        };
+        this.plan.active = true;
+        this.plan.approved = false;
+        this.options.emit({ type: "plan_mode", active: true, path: this.plan.path });
+        await this.saveCurrentSession();
+        return this.plan;
+    }
+    async approvePlan() {
+        const existing = await readPlan(this.options.agentConfig.workspaceRoot);
+        if (!existing?.content?.trim()) {
+            return null;
+        }
+        this.plan = { ...existing, active: false, approved: true };
+        this.lastPlanContext = undefined;
+        this.mode = "normal";
+        this.options.emit({
+            type: "plan_mode",
+            active: false,
+            approved: true,
+            path: this.plan.path,
+        });
+        await this.saveCurrentSession();
+        return this.plan;
+    }
+    async rejectPlan() {
+        this.plan = null;
+        this.lastPlanContext = undefined;
+        this.mode = "normal";
+        this.options.emit({ type: "plan_mode", active: false, approved: false });
+        await this.saveCurrentSession();
+    }
+    startWorkflow(goal) {
+        this.lastWorkflowState = undefined;
+        this.mode = "workflow";
+        this.workflow = createWorkflow(goal);
+        // kick first phase
+        this.workflow.phases[0].status = "running";
+        this.emitWorkflow();
+        void this.saveCurrentSession().catch(() => null);
+        return this.workflow;
+    }
+    stopWorkflow() {
+        this.workflow = null;
+        if (this.mode === "workflow")
+            this.mode = "normal";
+        void this.saveCurrentSession().catch(() => null);
+    }
+    startGoal(goal, maxIterations = 12, criteria = []) {
+        this.lastGoalState = undefined;
+        this.mode = "goal";
+        this.goal = createGoal(goal, maxIterations, criteria);
+        this.goal.iteration = 0;
+        this.emitGoal();
+        void this.saveCurrentSession().catch(() => null);
+        return this.goal;
+    }
+    stopGoal(status = "paused") {
+        if (this.goal) {
+            this.goal = { ...this.goal, status, completedAt: new Date().toISOString() };
+        }
+        if (this.mode === "goal")
+            this.mode = "normal";
+        this.emitGoal();
+        void this.saveCurrentSession().catch(() => null);
+    }
+    renderGoalBar(color) {
+        if (!this.goal)
+            return "(no active goal)\n";
+        return goalStatusBar(this.goal, color);
+    }
+    shouldContinueGoal() {
+        return Boolean(this.goal && shouldAutoContinue(this.goal));
+    }
+    continueGoalPrompt() {
+        if (!this.goal)
+            return "Continue.";
+        return nextGoalContinuePrompt(this.goal);
+    }
+    emitGoal() {
+        if (!this.goal)
+            return;
+        this.options.emit({
+            type: "goal_status",
+            goal: this.goal.goal,
+            status: this.goal.status,
+            iteration: this.goal.iteration,
+            maxIterations: this.goal.maxIterations,
+            progress: this.goal.progress.slice(-5),
+        });
+    }
+    renderWorkflowBar(color) {
+        if (!this.workflow)
+            return "(no active workflow)\n";
+        return workflowStatusBar(this.workflow, color);
+    }
+    async skillify(name, description) {
+        const skillsDir = this.options.agentConfig.skills.directories[0] ?? "./skills";
+        return skillifySession({
+            workspaceRoot: this.options.agentConfig.workspaceRoot,
+            skillName: name,
+            description,
+            messages: this.messages,
+            skillsDir,
+        });
+    }
+    listSkills() {
+        return this.skillManager.search("");
+    }
+    installSkill(sourcePath, name) {
+        return this.skillManager.installLocal(sourcePath, name);
+    }
+    /**
+     * Replace older model context with a semantic summary while retaining the
+     * removed raw messages in the persisted session archive.
+     */
+    async compactConversation(force = false) {
+        const plan = this.contextManager.prepare(this.messages, force);
+        if (!plan)
+            return "not_needed";
+        this.options.emit({ type: "context_compaction_start", beforeChars: plan.beforeChars });
+        try {
+            const transcript = buildCompactionTranscript(plan.older);
+            const { response } = await this.createMessageWithRecovery(() => ({
+                system: COMPACTION_SYSTEM_PROMPT,
+                messages: [
+                    {
+                        role: "user",
+                        content: `Summarize this conversation transcript:\n\n${transcript}`,
+                    },
+                ],
+                tools: [],
+                stream: false,
+            }), {
+                streamEnabled: false,
+                hasPartialStream: () => false,
+                allowContextCompaction: false,
+            });
+            this.recordUsage(response.usage, "compaction", {
+                prefixFingerprint: fingerprint({ system: COMPACTION_SYSTEM_PROMPT, tools: [] }),
+                configFingerprint: this.configFingerprint(),
+                systemFingerprint: fingerprint(COMPACTION_SYSTEM_PROMPT),
+                toolsFingerprint: fingerprint([]),
+            });
+            const summary = normalizeCompactionSummary(messageText(response.content));
+            const compacted = this.contextManager.apply(plan, summary);
+            // A compact model context is necessarily semantic rather than byte-for-byte
+            // lossless. The raw messages remain recoverable from the session JSON.
+            this.archivedMessages.push(...plan.older.filter((message) => !isContextSummary(message)));
+            this.messages = compacted;
+            this.resetRuntimeContextTracking();
+            await this.saveCurrentSession();
+            return "compacted";
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : stringify(error);
+            this.options.emit({ type: "context_compaction_failed", reason });
+            return "failed";
+        }
+    }
+    async submitMessage(input) {
+        const stateBeforeTurn = {
+            mode: this.mode,
+            plan: structuredClone(this.plan),
+            workflow: structuredClone(this.workflow),
+            goal: structuredClone(this.goal),
+            loadedSkillPaths: new Set(this.loadedSkillPaths),
+            seenMemoryBlocks: new Set(this.seenMemoryBlocks),
+            lastPlanContext: this.lastPlanContext,
+            lastWorkflowState: this.lastWorkflowState,
+            lastGoalState: this.lastGoalState,
+            skillCatalogSnapshot: this.skillCatalogSnapshot ? new Map(this.skillCatalogSnapshot) : undefined,
+        };
+        await this.ensureSession(input.slice(0, 60));
+        if (this.mode === "goal" && this.goal && this.goal.status === "active") {
+            // iteration already 1 on start; subsequent continues bump
+            if (this.goal.progress.length > 0 || this.goal.iteration > 0) {
+                /* keep */
+            }
+        }
+        const assumeYes = typeof this.options.assumeYes === "function" ? this.options.assumeYes() : this.options.assumeYes;
+        const approval = this.options.approvalProvider ??
+            createCliApprovalProvider(this.options.agentConfig, this.options.emit, assumeYes ?? false);
+        const isSubagent = Boolean(this.options.subagent);
+        const registry = createBuiltinRegistry({
+            config: this.options.agentConfig,
+            skillManager: this.skillManager,
+            mcpManager: this.mcpManager,
+            enableTask: !isSubagent,
+            allowedTools: this.options.subagent?.tools,
+            runTask: isSubagent ? undefined : (agent, prompt, emit) => this.runTask(agent, prompt, emit),
+        });
+        registry.setHooks(this.hooks);
+        registry.setPlanMode(this.mode === "plan");
+        const [availableSkills, matchedSkills, memBlock] = await Promise.all([
+            this.skillManager.metadata(),
+            this.matchedSkillsForPrompt(input),
+            isSubagent ? Promise.resolve("") : memoryContextBlock(this.options.agentConfig.workspaceRoot, input),
+        ]);
+        const modeExtra = this.runtimeModeContext();
+        const memoryExtra = this.takeMemoryContext(memBlock);
+        const { prompt, toolDefinitions } = await this.getStableRequestPrefix(registry.definitions());
+        const catalogExtra = this.takeSkillCatalogContext(availableSkills);
+        const runtimeContext = buildRuntimeContext(matchedSkills, [catalogExtra, modeExtra, memoryExtra].filter(Boolean).join("\n\n"));
+        const requestFingerprints = this.requestFingerprints(prompt, toolDefinitions);
+        if (this.activeTurnAbort)
+            throw new Error("A turn is already running.");
+        const turnAbort = new AbortController();
+        this.activeTurnAbort = turnAbort;
+        const toolContext = {
+            workspaceRoot: this.options.agentConfig.workspaceRoot,
+            emit: this.options.emit,
+            requestApproval: approval,
+            signal: turnAbort.signal,
+            askUser: this.askUser,
+            planMode: this.mode === "plan",
+        };
+        const userMessage = {
+            role: "user",
+            content: runtimeContext ? `${runtimeContext}\n\n# User Request\n${input}` : input,
+        };
+        this.messages.push(userMessage);
+        let finalText = "";
+        let turnHasToolResults = false;
+        let turnFinished = false;
+        const recoveredOutputParts = [];
+        let outputRecoveryCount = 0;
+        const highRiskToolCounts = new Map();
+        const maxHighRiskCallsPerTool = assumeYes ? Number.POSITIVE_INFINITY : 3;
+        try {
+            for (let turn = 1; turn <= this.options.agentConfig.maxTurns; turn += 1) {
+                await this.compactConversation();
+                const stream = typeof this.options.stream === "function" ? this.options.stream() : this.options.stream;
+                const streamEnabled = stream ?? true;
+                this.options.emit({ type: "llm_request", turn, toolCount: toolDefinitions.length });
+                let lastToolDeltaAt = 0;
+                let lastToolDeltaBytes = 0;
+                let lastToolDeltaDetail;
+                let streamedText = "";
+                const onTextDelta = isSubagent
+                    ? undefined
+                    : (text) => {
+                        streamedText += text;
+                        this.options.emit({ type: "assistant_delta", text });
+                    };
+                const buildRequest = (useStream) => ({
+                    system: prompt,
+                    messages: this.messages,
+                    tools: toolDefinitions,
+                    stream: useStream,
+                    onTextDelta: useStream ? onTextDelta : undefined,
+                    onToolInputDelta: useStream && !isSubagent
+                        ? (event) => {
+                            const now = Date.now();
+                            if (event.detail === lastToolDeltaDetail &&
+                                now - lastToolDeltaAt < 1200 &&
+                                event.bytes - lastToolDeltaBytes < 4000)
+                                return;
+                            lastToolDeltaAt = now;
+                            lastToolDeltaBytes = event.bytes;
+                            lastToolDeltaDetail = event.detail;
+                            this.options.emit({ type: "llm_tool_delta", ...event });
+                        }
+                        : undefined,
+                });
+                const recovered = await this.createMessageWithRecovery(buildRequest, {
+                    streamEnabled,
+                    hasPartialStream: () => Boolean(streamedText) || lastToolDeltaBytes > 0,
+                    allowContextCompaction: !isSubagent,
+                });
+                const response = recovered.response;
+                if (!isSubagent && streamEnabled && !recovered.streamed) {
+                    const recoveredText = messageText(response.content);
+                    if (recoveredText && recoveredText !== streamedText) {
+                        const missingText = recoveredText.startsWith(streamedText)
+                            ? recoveredText.slice(streamedText.length)
+                            : `${streamedText ? "\n" : ""}${recoveredText}`;
+                        if (missingText)
+                            this.options.emit({ type: "assistant_delta", text: missingText });
+                    }
+                }
+                this.recordUsage(response.usage, "main", requestFingerprints);
+                this.messages.push({ role: "assistant", content: response.content });
+                finalText = messageText(response.content);
+                this.options.emit({
+                    type: "llm_response",
+                    turn,
+                    stopReason: response.stop_reason,
+                    text: truncate(finalText, 1000),
+                });
+                // Workflow phase markers
+                if (this.workflow && finalText) {
+                    this.workflow = applyWorkflowMarkers(this.workflow, finalText);
+                    this.emitWorkflow();
+                }
+                // Goal markers
+                if (this.goal && finalText && this.mode === "goal") {
+                    this.goal = applyGoalMarkers(this.goal, finalText);
+                    if (this.goal.status === "active") {
+                        this.goal = {
+                            ...this.goal,
+                            iteration: Math.min(this.goal.iteration + 1, this.goal.maxIterations),
+                        };
+                        if (this.goal.iteration >= this.goal.maxIterations) {
+                            this.goal = {
+                                ...this.goal,
+                                status: "failed",
+                                lastBlockedReason: "max iterations reached",
+                                completedAt: new Date().toISOString(),
+                            };
+                            this.mode = "normal";
+                        }
+                    }
+                    this.emitGoal();
+                    if (this.goal.status === "completed" || this.goal.status === "failed") {
+                        this.mode = "normal";
+                    }
+                }
+                // Keep plan content in sync if model wrote it
+                if (this.mode === "plan") {
+                    const p = await readPlan(this.options.agentConfig.workspaceRoot);
+                    if (p)
+                        this.plan = { ...p, approved: false, active: true };
+                }
+                const toolUses = response.content.filter((block) => block.type === "tool_use");
+                if (toolUses.length === 0 &&
+                    isOutputLimitStop(response.stop_reason) &&
+                    outputRecoveryCount < MAX_OUTPUT_RECOVERIES) {
+                    if (finalText)
+                        recoveredOutputParts.push(finalText);
+                    outputRecoveryCount += 1;
+                    this.messages.push({
+                        role: "user",
+                        content: "Output token limit reached. Continue directly from where you stopped. Do not apologize or recap. Finish the remaining work in smaller pieces and use tools as needed.",
+                    });
+                    this.options.emit({
+                        type: "llm_retry",
+                        attempt: outputRecoveryCount,
+                        mode: "continue",
+                        reason: `model stopped with ${response.stop_reason}`,
+                    });
+                    continue;
+                }
+                if (toolUses.length === 0) {
+                    turnFinished = true;
+                    await this.saveCurrentSession();
+                    return `${recoveredOutputParts.join("")}${finalText}`;
+                }
+                const executeToolUse = async (toolUse) => {
+                    try {
+                        const risk = registry.riskOf(toolUse.name);
+                        if (risk === "high") {
+                            const count = highRiskToolCounts.get(toolUse.name) ?? 0;
+                            if (count >= maxHighRiskCallsPerTool) {
+                                const content = `High-risk tool ${toolUse.name} was already requested ${count} times in this user turn. Do not call it again for this turn. Summarize what you know, switch to a safer dedicated tool if available, or ask the user for explicit next steps.`;
+                                this.options.emit({ type: "tool_result", tool: toolUse.name, input: toolUse.input, isError: true, content });
+                                return {
+                                    type: "tool_result",
+                                    tool_use_id: toolUse.id,
+                                    content,
+                                    is_error: true,
+                                };
+                            }
+                            highRiskToolCounts.set(toolUse.name, count + 1);
+                        }
+                        const result = await registry.execute(toolUse.name, toolUse.input, toolContext);
+                        this.options.emit({
+                            type: "tool_result",
+                            tool: toolUse.name,
+                            input: toolUse.input,
+                            isError: result.isError,
+                            content: truncate(result.content, 1000),
+                            fileChange: result.fileChange,
+                        });
+                        // refresh plan after write
+                        if (toolUse.name === "write_file" && this.mode === "plan") {
+                            const p = await readPlan(this.options.agentConfig.workspaceRoot);
+                            if (p)
+                                this.plan = { ...p, approved: false, active: true };
+                        }
+                        return {
+                            type: "tool_result",
+                            tool_use_id: toolUse.id,
+                            content: result.content,
+                            is_error: result.isError,
+                        };
+                    }
+                    catch (error) {
+                        const content = truncateMiddle(error instanceof Error ? error.message : stringify(error), MAX_TOOL_RESULT_CHARS);
+                        this.options.emit({ type: "tool_result", tool: toolUse.name, input: toolUse.input, isError: true, content });
+                        return {
+                            type: "tool_result",
+                            tool_use_id: toolUse.id,
+                            content,
+                            is_error: true,
+                        };
+                    }
+                };
+                const toolResults = new Array(toolUses.length);
+                const taskJobs = [];
+                for (const [index, toolUse] of toolUses.entries()) {
+                    if (TASK_TOOL_NAMES.has(toolUse.name)) {
+                        taskJobs.push(executeToolUse(toolUse).then((result) => {
+                            toolResults[index] = result;
+                        }));
+                        continue;
+                    }
+                    toolResults[index] = await executeToolUse(toolUse);
+                }
+                await Promise.all(taskJobs);
+                this.messages.push({ role: "user", content: toolResults });
+                turnHasToolResults = true;
+            }
+            const stopped = `Stopped: max turns reached before a final answer was completed.${finalText ? ` Last assistant text: ${finalText}` : ""}`;
+            if (this.messages.at(-1)?.role === "user")
+                this.messages.push({ role: "assistant", content: stopped });
+            turnFinished = true;
+            await this.saveCurrentSession();
+            return stopped;
+        }
+        catch (error) {
+            if (!turnFinished) {
+                const turnStart = this.messages.indexOf(userMessage);
+                if (turnStart >= 0) {
+                    if (turnHasToolResults) {
+                        if (this.messages.at(-1)?.role === "user") {
+                            this.messages.push({
+                                role: "assistant",
+                                content: "The previous turn was interrupted after tool execution. Inspect the current state before retrying and do not repeat side effects blindly.",
+                            });
+                        }
+                    }
+                    else {
+                        this.messages.splice(turnStart);
+                        this.mode = stateBeforeTurn.mode;
+                        this.plan = stateBeforeTurn.plan;
+                        this.workflow = stateBeforeTurn.workflow;
+                        this.goal = stateBeforeTurn.goal;
+                        this.loadedSkillPaths.clear();
+                        stateBeforeTurn.loadedSkillPaths.forEach((path) => this.loadedSkillPaths.add(path));
+                        this.seenMemoryBlocks.clear();
+                        stateBeforeTurn.seenMemoryBlocks.forEach((block) => this.seenMemoryBlocks.add(block));
+                        this.lastPlanContext = stateBeforeTurn.lastPlanContext;
+                        this.lastWorkflowState = stateBeforeTurn.lastWorkflowState;
+                        this.lastGoalState = stateBeforeTurn.lastGoalState;
+                        this.skillCatalogSnapshot = stateBeforeTurn.skillCatalogSnapshot;
+                    }
+                }
+            }
+            throw error;
+        }
+        finally {
+            if (this.activeTurnAbort === turnAbort)
+                this.activeTurnAbort = undefined;
+            await this.saveCurrentSession().catch(() => null);
+        }
+    }
+    clearConversation() {
+        this.messages = [];
+        this.archivedMessages = [];
+        this.contextManager.clear();
+        this.resetRuntimeContextTracking();
+        this.skillCatalogSnapshot = undefined;
+        void this.saveCurrentSession().catch(() => null);
+    }
+    emitWorkflow() {
+        if (!this.workflow)
+            return;
+        this.options.emit({
+            type: "workflow_status",
+            goal: this.workflow.goal,
+            phases: this.workflow.phases.map((p) => ({
+                name: p.name,
+                label: p.label,
+                status: p.status,
+                summary: p.summary,
+            })),
+        });
+    }
+    async getProjectInstructions() {
+        if (this.options.subagent)
+            return null;
+        if (this.projectInstructionsCache !== undefined)
+            return this.projectInstructionsCache;
+        this.projectInstructionsCache = await loadProjectInstructions(this.options.agentConfig.workspaceRoot);
+        return this.projectInstructionsCache;
+    }
+    async getStableRequestPrefix(currentToolDefinitions) {
+        this.stableToolDefinitions ??= currentToolDefinitions;
+        this.stableSystemPrompt ??= new PromptBuilder({
+            agentConfig: this.options.agentConfig,
+            tools: this.stableToolDefinitions,
+            subagent: this.options.subagent,
+            projectInstructions: await this.getProjectInstructions(),
+        }).build();
+        return {
+            prompt: this.stableSystemPrompt,
+            toolDefinitions: this.stableToolDefinitions,
+        };
+    }
+    async createMessageWithRecovery(buildRequest, options) {
+        let useStream = options.streamEnabled;
+        let malformedStreamRecovered = false;
+        let contextCompactionAttempted = false;
+        let transientRetries = 0;
+        for (;;) {
+            try {
+                const request = buildRequest(useStream);
+                request.signal ??= this.activeTurnAbort?.signal;
+                return {
+                    response: await this.client.createMessage(request),
+                    streamed: useStream,
+                };
+            }
+            catch (error) {
+                if (error instanceof MalformedStreamError && useStream && !malformedStreamRecovered) {
+                    malformedStreamRecovered = true;
+                    useStream = false;
+                    this.options.emit({
+                        type: "llm_retry",
+                        attempt: 1,
+                        mode: "non-stream",
+                        reason: error.message,
+                    });
+                    continue;
+                }
+                if (options.allowContextCompaction &&
+                    !contextCompactionAttempted &&
+                    isContextOverflowError(error)) {
+                    contextCompactionAttempted = true;
+                    const compacted = await this.compactConversation(true);
+                    if (compacted === "compacted") {
+                        this.options.emit({
+                            type: "llm_retry",
+                            attempt: 1,
+                            mode: "after-compaction",
+                            reason: "provider rejected the prompt as too long",
+                        });
+                        continue;
+                    }
+                }
+                if (!isTransientLlmError(error) || transientRetries >= MAX_API_RETRIES)
+                    throw error;
+                transientRetries += 1;
+                if (useStream && options.hasPartialStream())
+                    useStream = false;
+                const delayMs = retryDelayMs(error, transientRetries);
+                this.options.emit({
+                    type: "llm_retry",
+                    attempt: transientRetries,
+                    mode: useStream || !options.streamEnabled ? "same-request" : "non-stream",
+                    reason: retryReason(error),
+                    delayMs,
+                });
+                if (delayMs > 0)
+                    await sleep(delayMs);
+            }
+        }
+    }
+    async matchedSkillsForPrompt(input) {
+        if (this.options.subagent)
+            return [];
+        const matches = (await this.skillManager.search(input)).slice(0, 2);
+        const loaded = [];
+        for (const match of matches) {
+            if (this.loadedSkillPaths.has(match.path))
+                continue;
+            try {
+                loaded.push({
+                    content: await this.skillManager.read(match.path),
+                    name: match.name,
+                    path: match.path,
+                });
+                this.loadedSkillPaths.add(match.path);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        return loaded;
+    }
+    async runTask(agent, prompt, emit) {
+        const depth = this.options.depth ?? 0;
+        if (depth >= 1) {
+            return "Task nesting is not allowed. Complete the work directly with your tools.";
+        }
+        const runtime = new QueryEngine({
+            ...this.options,
+            emit,
+            subagent: agent,
+            depth: depth + 1,
+            stream: false,
+        });
+        try {
+            return await runtime.submitMessage(prompt);
+        }
+        finally {
+            this.mergeUsage(runtime.getUsageStats(), "task");
+            await runtime.close();
+        }
+    }
+    recordUsage(usage, category, fingerprints) {
+        addUsage(this.usage, usage);
+        addUsage(this.usageByCategory[category], usage);
+        this.latestUsageByCategory[category] = requestUsageCounters(usage);
+        if (category === "main") {
+            this.recordCacheDiagnostics(usage, category, fingerprints);
+        }
+    }
+    mergeUsage(usage, category) {
+        mergeUsageCounters(this.usage, usage);
+        mergeUsageCounters(this.usageByCategory[category], usage);
+        const latest = usage.latestByCategory.main ?? usage.latestByCategory.compaction;
+        if (latest)
+            this.latestUsageByCategory[category] = rawUsageCounters(latest);
+    }
+    recordCacheDiagnostics(usage, category, current) {
+        this.cacheDiagnostics.prefixFingerprint = current.prefixFingerprint;
+        this.cacheDiagnostics.configFingerprint = current.configFingerprint;
+        this.cacheDiagnostics.systemFingerprint = current.systemFingerprint;
+        this.cacheDiagnostics.toolsFingerprint = current.toolsFingerprint;
+        if (!usage)
+            return;
+        const cacheRead = usage.cache_read_input_tokens ?? 0;
+        const previous = this.lastCacheRequest.get(category);
+        if (previous?.cacheRead && cacheRead === 0) {
+            const systemChanged = previous.systemFingerprint !== current.systemFingerprint;
+            const toolsChanged = previous.toolsFingerprint !== current.toolsFingerprint;
+            const configChanged = previous.configFingerprint !== current.configFingerprint;
+            const changed = [
+                configChanged ? "config" : "",
+                systemChanged ? "system" : "",
+                toolsChanged ? "tools" : "",
+            ].filter(Boolean);
+            this.cacheDiagnostics.missesAfterHit += 1;
+            this.cacheDiagnostics.lastMissReason = changed.length > 0
+                ? `${changed.join(" and ")} changed`
+                : "system/tools stable; config stable; message prefix changed, cache expired, or provider missed";
+        }
+        this.lastCacheRequest.set(category, {
+            cacheRead: cacheRead > 0,
+            ...current,
+        });
+    }
+    configFingerprint() {
+        return fingerprint({
+            baseUrl: this.options.llmConfig.baseUrl.replace(/\/$/, ""),
+            model: this.options.llmConfig.model,
+            maxTokens: this.options.llmConfig.maxTokens,
+            cacheControl: this.options.llmConfig.cacheTtl === "1h"
+                ? { type: "ephemeral", ttl: "1h" }
+                : { type: "ephemeral" },
+        });
+    }
+    requestFingerprints(prompt, tools) {
+        const configFingerprint = this.configFingerprint();
+        const systemFingerprint = fingerprint(prompt);
+        const toolsFingerprint = fingerprint(tools);
+        return {
+            configFingerprint,
+            systemFingerprint,
+            toolsFingerprint,
+            prefixFingerprint: fingerprint({ configFingerprint, systemFingerprint, toolsFingerprint }),
+        };
+    }
+    takeSkillCatalogContext(skills) {
+        if (this.options.subagent)
+            return "";
+        const next = new Map(skills.map((skill) => [skill.path, skill]));
+        if (!this.skillCatalogSnapshot) {
+            this.skillCatalogSnapshot = next;
+            if (skills.length === 0)
+                return "";
+            return `# Available Skills Catalog\nThis catalog is session context, not part of the cache-stable system prompt. Use these descriptions to decide when a skill applies.\n\n${skills.map(renderSkillMetadata).join("\n")}`;
+        }
+        const changes = [];
+        for (const [skillPath, skill] of next) {
+            const previous = this.skillCatalogSnapshot.get(skillPath);
+            if (!previous)
+                changes.push(`- Added ${renderSkillMetadata(skill).slice(2)}`);
+            else if (JSON.stringify(previous) !== JSON.stringify(skill)) {
+                changes.push(`- Updated ${renderSkillMetadata(skill).slice(2)}`);
+            }
+        }
+        for (const [skillPath, skill] of this.skillCatalogSnapshot) {
+            if (!next.has(skillPath))
+                changes.push(`- Removed ${skill.name}: ${skillPath}`);
+        }
+        this.skillCatalogSnapshot = next;
+        return changes.length > 0
+            ? `# Available Skills Catalog Update\nThis update supersedes the changed entries in the previous catalog.\n\n${changes.join("\n")}`
+            : "";
+    }
+    runtimeModeContext() {
+        const blocks = [];
+        const planContext = this.mode === "plan"
+            ? planModeSystemExtra(this.plan, "plan")
+            : this.plan?.approved
+                ? planModeSystemExtra(this.plan, "normal")
+                : "";
+        if (planContext && planContext !== this.lastPlanContext) {
+            blocks.push(planContext);
+            this.lastPlanContext = planContext;
+        }
+        if (this.mode === "workflow" && this.workflow) {
+            const state = JSON.stringify(this.workflow);
+            if (state !== this.lastWorkflowState) {
+                blocks.push(this.lastWorkflowState === undefined ? workflowSystemExtra(this.workflow) : workflowRuntimeUpdate(this.workflow));
+                this.lastWorkflowState = state;
+            }
+        }
+        if (this.mode === "goal" && this.goal) {
+            const state = JSON.stringify(this.goal);
+            if (state !== this.lastGoalState) {
+                blocks.push(this.lastGoalState === undefined ? goalSystemExtra(this.goal) : goalRuntimeUpdate(this.goal));
+                this.lastGoalState = state;
+            }
+        }
+        return blocks.join("\n\n");
+    }
+    takeMemoryContext(block) {
+        if (!block || this.seenMemoryBlocks.has(block))
+            return "";
+        this.seenMemoryBlocks.add(block);
+        return block;
+    }
+    resetRuntimeContextTracking() {
+        this.loadedSkillPaths.clear();
+        this.seenMemoryBlocks.clear();
+        this.lastPlanContext = undefined;
+        this.lastWorkflowState = undefined;
+        this.lastGoalState = undefined;
+    }
+}
+function emptyUsageCounters() {
+    return {
+        requests: 0,
+        requestsWithCacheRead: 0,
+        input_tokens: 0,
+        output_tokens: 0,
+        cache_creation_input_tokens: 0,
+        cache_read_input_tokens: 0,
+    };
+}
+function addUsage(target, usage) {
+    target.requests += 1;
+    if (!usage)
+        return;
+    target.input_tokens += usage.input_tokens ?? 0;
+    target.output_tokens += usage.output_tokens ?? 0;
+    target.cache_creation_input_tokens += usage.cache_creation_input_tokens ?? 0;
+    target.cache_read_input_tokens += usage.cache_read_input_tokens ?? 0;
+    if ((usage.cache_read_input_tokens ?? 0) > 0)
+        target.requestsWithCacheRead += 1;
+}
+function mergeUsageCounters(target, usage) {
+    target.requests += usage.requests;
+    target.requestsWithCacheRead += usage.requestsWithCacheRead;
+    target.input_tokens += usage.input_tokens;
+    target.output_tokens += usage.output_tokens;
+    target.cache_creation_input_tokens += usage.cache_creation_input_tokens;
+    target.cache_read_input_tokens += usage.cache_read_input_tokens;
+}
+function usageStats(usage) {
+    const totalInput = usage.input_tokens + usage.cache_creation_input_tokens + usage.cache_read_input_tokens;
+    return {
+        ...usage,
+        cacheHitRate: totalInput > 0 ? usage.cache_read_input_tokens / totalInput : null,
+        requestHitRate: usage.requests > 0 ? usage.requestsWithCacheRead / usage.requests : null,
+    };
+}
+function requestUsageCounters(usage) {
+    const counters = emptyUsageCounters();
+    addUsage(counters, usage);
+    return counters;
+}
+function rawUsageCounters(usage) {
+    return {
+        requests: usage.requests,
+        requestsWithCacheRead: usage.requestsWithCacheRead,
+        input_tokens: usage.input_tokens,
+        output_tokens: usage.output_tokens,
+        cache_creation_input_tokens: usage.cache_creation_input_tokens,
+        cache_read_input_tokens: usage.cache_read_input_tokens,
+    };
+}
+function restoreLatestUsage(usage) {
+    return usage ? restoreUsageCounters(usage) : null;
+}
+function restoreUsageCounters(usage) {
+    const restored = emptyUsageCounters();
+    if (!usage)
+        return restored;
+    for (const key of Object.keys(restored)) {
+        const value = usage[key];
+        if (typeof value === "number" && Number.isFinite(value) && value >= 0)
+            restored[key] = value;
+    }
+    return restored;
+}
+function fingerprint(value) {
+    const content = typeof value === "string" ? value : JSON.stringify(value);
+    return createHash("sha256").update(content).digest("hex").slice(0, 12);
+}
+function isTransientLlmError(error) {
+    if (error instanceof AnthropicApiError) {
+        const shouldRetry = error.responseHeaders.get("x-should-retry");
+        if (shouldRetry === "false")
+            return false;
+        if (shouldRetry === "true")
+            return true;
+        if (error.responseBody.includes("overloaded_error"))
+            return true;
+        return [408, 409, 425, 429, 500, 502, 503, 504, 529].includes(error.status);
+    }
+    if (!(error instanceof Error))
+        return false;
+    if (error.name === "TimeoutError")
+        return true;
+    if (error instanceof TypeError)
+        return true;
+    const code = error.code ??
+        error.cause?.code;
+    return ["ECONNRESET", "ECONNREFUSED", "EPIPE", "ETIMEDOUT", "ENETUNREACH", "EAI_AGAIN"].includes(code ?? "");
+}
+function isContextOverflowError(error) {
+    if (!(error instanceof AnthropicApiError))
+        return false;
+    if (error.status === 413)
+        return true;
+    if (error.status !== 400)
+        return false;
+    return /prompt.{0,20}too long|context (?:length|window|limit)|maximum context|too many tokens|input.{0,30}tokens.{0,30}exceed/i
+        .test(error.responseBody);
+}
+function retryDelayMs(error, attempt) {
+    if (error instanceof AnthropicApiError) {
+        const retryAfter = error.responseHeaders.get("retry-after");
+        if (retryAfter) {
+            const seconds = Number(retryAfter);
+            if (Number.isFinite(seconds) && seconds >= 0) {
+                return Math.min(seconds * 1000, MAX_RETRY_DELAY_MS);
+            }
+            const dateDelay = Date.parse(retryAfter) - Date.now();
+            if (Number.isFinite(dateDelay) && dateDelay > 0) {
+                return Math.min(dateDelay, MAX_RETRY_DELAY_MS);
+            }
+        }
+    }
+    const base = Math.min(500 * (2 ** (attempt - 1)), 8000);
+    return Math.round(base + Math.random() * base * 0.25);
+}
+function retryReason(error) {
+    if (error instanceof AnthropicApiError)
+        return `provider API ${error.status}`;
+    if (error instanceof Error && error.name === "TimeoutError")
+        return "provider request timed out";
+    return error instanceof Error ? error.message : String(error);
+}
+function isOutputLimitStop(reason) {
+    return reason === "max_tokens" || reason === "max_output_tokens";
+}
+function sleep(delayMs) {
+    return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+function renderSkillMetadata(skill) {
+    return `- ${skill.name}: ${skill.description || "No description."} Path: ${skill.path}`;
+}
+function workflowRuntimeUpdate(workflow) {
+    const phases = workflow.phases
+        .map((phase) => `- ${phase.name}: ${phase.status}${phase.summary ? ` — ${phase.summary}` : ""}`)
+        .join("\n");
+    return `# Coordinator Workflow Update
+This state supersedes the previous workflow state.
+
+Goal: ${workflow.goal}
+
+${phases}`;
+}
+function goalRuntimeUpdate(goal) {
+    const latestProgress = goal.progress.at(-1) ?? "(none)";
+    return `# Goal Mode Update
+This state supersedes the previous goal state.
+
+- Status: ${goal.status}
+- Iteration: ${goal.iteration} / ${goal.maxIterations}
+- Latest progress: ${latestProgress}${goal.lastBlockedReason ? `\n- Blocked: ${goal.lastBlockedReason}` : ""}`;
+}
+function buildRuntimeContext(matchedSkills, modeExtra) {
+    const skillBlocks = matchedSkills.map((skill) => `## ${skill.name}\nPath: ${skill.path}\n\n${skill.content}`);
+    return [
+        skillBlocks.length
+            ? `# Loaded Skill Instructions\nThese trusted local skill instructions matched this turn. Follow them when applicable.\n\n${skillBlocks.join("\n\n")}`
+            : "",
+        modeExtra.trim(),
+    ]
+        .filter(Boolean)
+        .join("\n\n");
+}