@backendkit-labs/agent-core 0.14.0

package/dist/engine/AgentEngine.js

@@ -0,0 +1,1037 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentEngine = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const atomic_write_1 = require("../shared/utils/atomic-write");
+const DelegationBus_1 = require("../delegation/DelegationBus");
+const SessionMemory_1 = require("../memory/SessionMemory");
+const activator_1 = require("../skills/activator");
+const WorkflowRunner_1 = require("../workflow/WorkflowRunner");
+const IterationManager_1 = require("./IterationManager");
+const qa_orchestrator_1 = require("./qa-orchestrator");
+/**
+ * Remove messages that would cause a 400 from any OpenAI-compatible provider:
+ * - `tool` messages that are not part of an active assistant→tool chain
+ * - `assistant` messages that declare tool_calls but have no following tool results
+ *   (only stripped when the next non-tool message is NOT another turn of the same chain)
+ *
+ * Walking forward: we track whether we're "inside" a tool_calls chain.
+ * A chain starts with assistant(tool_calls) and ends once all IDs have a result.
+ * Any `tool` result that arrives outside an open chain is dropped.
+ */
+function sanitizeMessages(messages) {
+    const out = [];
+    // IDs still waiting for a tool result in the current chain
+    let pendingIds = new Set();
+    for (const msg of messages) {
+        if (msg.role === 'assistant') {
+            // A new assistant message closes any previous chain (even if incomplete)
+            // and optionally opens a new one.
+            pendingIds = new Set();
+            if (msg.tool_calls?.length) {
+                for (const tc of msg.tool_calls) {
+                    if (tc.id)
+                        pendingIds.add(tc.id);
+                }
+            }
+            out.push(msg);
+        }
+        else if (msg.role === 'tool') {
+            if (pendingIds.size === 0) {
+                // Orphaned tool result — no open chain. Drop it.
+                continue;
+            }
+            if (msg.tool_call_id)
+                pendingIds.delete(msg.tool_call_id);
+            out.push(msg);
+        }
+        else {
+            // user / system — close any open chain
+            pendingIds = new Set();
+            out.push(msg);
+        }
+    }
+    return out;
+}
+const MAX_INPUT_BYTES = 100_000; // Fix #17: 100 KB hard cap on user input
+const ASK_AGENT_TOOL = {
+    name: 'ask_agent',
+    description: 'Invokes another AI agent in the system. Multiple ask_agent calls in the same response ' +
+        'run concurrently (up to 6 at a time via a bulkhead). Use to split large independent ' +
+        'tasks across 2-5 specialist agents per response.',
+    parameters: {
+        type: 'object',
+        properties: {
+            agent_id: { type: 'string', description: 'ID of the agent to invoke' },
+            question: { type: 'string', description: 'The task or question for the agent' },
+            context: { type: 'string', description: 'Additional context the agent needs' },
+        },
+        required: ['agent_id', 'question'],
+    },
+    execute: async () => '',
+};
+class AgentEngine {
+    opts;
+    memory;
+    bus;
+    skillActivator = new activator_1.SkillActivator();
+    currentAgentId;
+    messages = [];
+    aborted = false;
+    abortController = null;
+    allSkills;
+    iterationManager;
+    activeSkillAddition = '';
+    yamlSkillsLoaded = false;
+    mcpInitialized = false;
+    mcpInitAttempts = 0;
+    mcpRegisteredServers = new Set();
+    mcpTriggers = new Map(); // agentId → triggers
+    mcpToolTriggers = new Map(); // keyword → {agentId, tool}
+    approvalDisabled = false; // set to true after 'approve_all'
+    static WRITE_TOOLS = new Set(['write_file', 'edit_file', 'run_command']);
+    /** Tracks what each MCP server blocked/assigned so it can be fully reverted on disconnect. */
+    mcpAgentBlocks = new Map();
+    /**
+     * Commands that always require user approval regardless of iteration mode or
+     * approvalDisabled flag. These are irreversible or high-blast-radius operations:
+     * installing new packages, removing packages, running destructive npm scripts.
+     */
+    static ALWAYS_ASK_PATTERNS = [
+        /^\s*npm\s+(install|i|add)\s+[^-]/i, // npm install <pkg> — new package install
+        /^\s*npm\s+uninstall\b/i, // npm uninstall
+        /^\s*yarn\s+add\s+[^-]/i, // yarn add <pkg>
+        /^\s*pnpm\s+add\s+[^-]/i, // pnpm add <pkg>
+        /^\s*pip\s+install\b/i, // pip install
+        /^\s*pip3\s+install\b/i,
+    ];
+    agentsLoaded = false;
+    memoryContextBlock = '';
+    constructor(opts) {
+        this.opts = opts;
+        this.memory = opts.sessionMemory ?? new SessionMemory_1.SessionMemory();
+        this.currentAgentId = opts.defaultAgentId;
+        this.allSkills = opts.skills ?? [];
+        this.iterationManager = new IterationManager_1.IterationManager({
+            mode: opts.iterationMode ?? 'interactive',
+            maxIterations: opts.maxIterations ?? 100,
+            onLimitReached: opts.onIterationLimit,
+            onStep: opts.onStep,
+        });
+        if (opts.auditLog) {
+            try {
+                (0, fs_1.mkdirSync)((0, path_1.dirname)(opts.auditLog), { recursive: true });
+            }
+            catch { }
+        }
+        if (opts.historyPath && (0, fs_1.existsSync)(opts.historyPath)) {
+            try {
+                const raw = JSON.parse((0, fs_1.readFileSync)(opts.historyPath, 'utf-8'));
+                this.messages = raw.filter(m => m.role !== 'system');
+            }
+            catch { /* corrupt or missing — start fresh */ }
+        }
+        this.bus = new DelegationBus_1.DelegationBus({
+            maxParallel: opts.maxParallelAgents ?? 6,
+            agents: opts.agents,
+            tools: opts.tools,
+            transport: opts.transport,
+            workingDir: opts.workingDir,
+            runAgent: (id, question, context) => this.runAgentInternal(id, question, context),
+        });
+    }
+    /** Access the observability manager when configured via createBaseEngine({ observability }). */
+    get observability() {
+        return this.opts.observabilityManager;
+    }
+    /** Access the MCP client manager to inspect connected servers and their tools. */
+    getMCPManager() {
+        return this.opts.mcpManager;
+    }
+    /**
+     * Updates the working directory used by tools and the system prompt.
+     * Call after a workspace/project switch so file operations target the new
+     * project root without recreating the entire engine.
+     * Also triggers a skill reload so project-scoped skills are refreshed.
+     */
+    updateWorkingDir(newCwd) {
+        this.opts.workingDir = newCwd;
+        this.reloadSkills();
+    }
+    /**
+     * Marks YAML skills as stale so the next run() reloads them from disk.
+     * Call after installing, creating, or generating skills so changes take effect
+     * without restarting the engine.
+     * Built-in (in-memory) skills are never affected — only the YAML layers are reloaded.
+     */
+    reloadSkills() {
+        const builtins = this.opts.skills ?? [];
+        this.allSkills = [...builtins];
+        this.yamlSkillsLoaded = false;
+    }
+    /**
+     * Direct single-turn LLM call — no tools, no conversation history, no transport events.
+     * Useful for slash commands that need AI-generated content (e.g. /skills generate).
+     * Uses the engine's default provider and model.
+     */
+    async callLLM(prompt) {
+        const provider = this.opts.providers.resolve(undefined, this.opts.defaultProvider);
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            provider.chat([{ role: 'user', content: prompt }], [], {
+                onChunk(delta) { chunks.push(delta); },
+                onDone() { resolve(chunks.join('')); },
+                onError(err) { reject(err); },
+            });
+        });
+    }
+    getProviderForProfile(profile) {
+        return this.opts.providers.resolve(profile.provider, this.opts.defaultProvider);
+    }
+    async run(input) {
+        this.aborted = false;
+        this.opts.transport.emit({ type: 'ready' });
+        // Fix #17: reject inputs that exceed the hard cap to prevent prompt injection via huge payloads
+        if (Buffer.byteLength(input, 'utf-8') > MAX_INPUT_BYTES) {
+            this.opts.transport.emit({
+                type: 'error',
+                message: `Input too large (${Buffer.byteLength(input, 'utf-8').toLocaleString()} bytes). Maximum is ${MAX_INPUT_BYTES.toLocaleString()} bytes.`,
+            });
+            this.opts.transport.emit({ type: 'done' });
+            return;
+        }
+        await this.ensureMCPInitialized();
+        await this.ensureAgentsLoaded();
+        // Direct MCP routing: bypass general when input matches a configured trigger
+        const mcpRoute = this.findMCPRoute(input);
+        if (mcpRoute) {
+            if (mcpRoute.tool) {
+                // Tool trigger: call the MCP tool directly — no intermediate LLM
+                const toolName = `mcp__${mcpRoute.agentId}__${mcpRoute.tool}`;
+                const toolDef = this.opts.tools.get(toolName);
+                if (toolDef) {
+                    const required = toolDef.parameters.required;
+                    const firstParam = required?.[0] ?? 'input';
+                    const ctx = this.buildContext();
+                    const profile = this.opts.agents.get(mcpRoute.agentId);
+                    this.opts.transport.emit({
+                        type: 'block_start',
+                        agent_id: mcpRoute.agentId,
+                        agent_name: profile?.name ?? mcpRoute.agentId,
+                        agent_icon: profile?.icon ?? '◎',
+                    });
+                    const result = await toolDef.execute({ [firstParam]: input }, ctx);
+                    this.opts.transport.emit({ type: 'token', content: result, agent_id: mcpRoute.agentId });
+                    this.opts.transport.emit({ type: 'block_end', status: 'ok', agent_id: mcpRoute.agentId });
+                    this.opts.transport.emit({ type: 'done' });
+                    return;
+                }
+            }
+            // Agent trigger fallback: route to the agent's LLM session
+            await this.runAgentInternal(mcpRoute.agentId, input);
+            this.opts.transport.emit({ type: 'done' });
+            return;
+        }
+        // Pre-compute memory context block for this input
+        if (this.opts.memorySystem) {
+            this.memoryContextBlock = await this.opts.memorySystem.buildContextBlock(input).catch(() => '');
+        }
+        // Lazy-load user YAML skills (global + packs + project) on first call
+        if (!this.yamlSkillsLoaded && this.opts.loadSkills) {
+            try {
+                const yamlSkills = await this.opts.loadSkills();
+                this.allSkills = [...this.allSkills, ...yamlSkills];
+            }
+            catch { /* non-fatal: skip if filesystem skills unavailable */ }
+            this.yamlSkillsLoaded = true;
+        }
+        // Activate skills relevant to this specific input
+        if (this.allSkills.length > 0) {
+            const active = this.skillActivator.activate(input, this.allSkills, this.opts.detectedStack ?? []);
+            this.activeSkillAddition = this.skillActivator.buildSystemPromptAddition(active);
+        }
+        const profile = this.getCurrentProfile();
+        if (!profile)
+            throw new Error(`Default agent "${this.currentAgentId}" not registered`);
+        // Orquestar la tarea para obtener clasificacion, risk scoring y gates requeridos
+        let orchestrationResult;
+        if (this.opts.orchestrator) {
+            orchestrationResult = await this.opts.orchestrator.orchestrate(input).catch(() => undefined);
+        }
+        this.messages.push({ role: 'user', content: input });
+        await this.runLoop(profile, orchestrationResult);
+        this.saveHistory();
+        this.opts.transport.emit({ type: 'done' });
+    }
+    async runWorkflow(defOrBuilder, opts = {}) {
+        await this.ensureMCPInitialized();
+        await this.ensureAgentsLoaded();
+        const def = 'build' in defOrBuilder ? defOrBuilder.build() : defOrBuilder;
+        const runner = new WorkflowRunner_1.WorkflowRunner(def, {
+            ...opts,
+            runAgent: (agentId, input, context) => this.runAgentInternal(agentId, input, context),
+            transport: this.opts.transport,
+        });
+        return runner.run();
+    }
+    abort() {
+        this.aborted = true;
+        this.abortController?.abort();
+        this.abortController = null;
+    }
+    /** Change the iteration mode at runtime — takes effect on the next run(). */
+    setIterationMode(mode) {
+        this.iterationManager.setMode(mode);
+    }
+    /** Returns the current iteration mode. */
+    getIterationMode() {
+        return this.iterationManager.mode;
+    }
+    /** Delete persisted history file and reset in-memory conversation. */
+    clearHistory() {
+        this.messages = [];
+        if (!this.opts.historyPath)
+            return;
+        try {
+            (0, atomic_write_1.atomicWriteSync)(this.opts.historyPath, '[]');
+        }
+        catch { /* non-fatal */ }
+    }
+    /** Serialize current conversation to disk (called automatically after each run). */
+    saveHistory() {
+        if (!this.opts.historyPath)
+            return;
+        const cap = this.opts.maxContextMessages ?? 100;
+        const toSave = this.messages.filter(m => m.role !== 'system').slice(-cap);
+        try {
+            (0, fs_1.mkdirSync)((0, path_1.dirname)(this.opts.historyPath), { recursive: true });
+            (0, atomic_write_1.atomicWriteSync)(this.opts.historyPath, JSON.stringify(toSave, null, 2));
+        }
+        catch { /* non-fatal — history loss is preferable to a crash */ }
+    }
+    /**
+     * Trim conversation history to maxContextMessages by dropping oldest messages
+     * at a user-turn boundary. Preserves all assistant↔tool pairs intact.
+     */
+    trimHistory() {
+        const max = this.opts.maxContextMessages;
+        if (!max || this.messages.length <= max)
+            return;
+        // Walk forward from the target offset to find the next 'user' message.
+        // Cutting there avoids orphaning assistant tool_calls / tool results.
+        const target = this.messages.length - max;
+        let cutAt = target;
+        while (cutAt < this.messages.length && this.messages[cutAt].role !== 'user') {
+            cutAt++;
+        }
+        if (cutAt > 0 && cutAt < this.messages.length) {
+            this.messages = this.messages.slice(cutAt);
+            this.opts.transport.emit({
+                type: 'system',
+                level: 'warn',
+                text: `[ContextWindow] Dropped ${cutAt} messages — history capped at ${max} (maxContextMessages)`,
+            });
+        }
+    }
+    async ensureAgentsLoaded() {
+        if (this.agentsLoaded || !this.opts.loadAgents)
+            return;
+        this.agentsLoaded = true; // set early to prevent concurrent double-loads
+        try {
+            const discovered = await this.opts.loadAgents();
+            for (const agent of discovered)
+                this.opts.agents.upsert(agent);
+            // If the current default agent still isn't registered, fall back to first available
+            if (!this.opts.agents.has(this.currentAgentId)) {
+                const all = this.opts.agents.getAll();
+                if (all.length > 0)
+                    this.currentAgentId = all[0].id;
+            }
+        }
+        catch (err) {
+            this.opts.transport.emit({
+                type: 'system', level: 'warn',
+                text: `[AgentDiscovery] Failed to load agents: ${err.message}`,
+            });
+        }
+    }
+    async ensureMCPInitialized() {
+        if (!this.opts.mcpManager)
+            return;
+        try {
+            if (!this.mcpInitialized) {
+                await this.opts.mcpManager.initialize();
+                this.mcpInitialized = true;
+            }
+            else {
+                // Subsequent runs: retry only servers that are still offline — bounded by their own counter
+                const offline = this.opts.mcpManager.getConfiguredNames()
+                    .filter(n => !this.mcpRegisteredServers.has(n));
+                if (offline.length > 0 && this.mcpInitAttempts < 3) {
+                    this.mcpInitAttempts++;
+                    await this.opts.mcpManager.reconnectFailed();
+                }
+            }
+        }
+        catch (err) {
+            this.opts.transport.emit({
+                type: 'system', level: 'warn',
+                text: `MCP initialization error: ${err.message}`,
+            });
+        }
+        // Always register any server that is now connected but not yet registered as agent.
+        // This runs regardless of the retry counter so late-starting servers get picked up.
+        for (const { name, toolCount } of this.opts.mcpManager.getServerInfo()) {
+            if (toolCount > 0 && !this.mcpRegisteredServers.has(name)) {
+                const tools = this.opts.mcpManager.getServerTools(name);
+                const config = this.opts.mcpManager.getConfig(name);
+                this.registerMCPAgent(config, tools);
+                this.mcpRegisteredServers.add(name);
+            }
+        }
+        // Warn about servers still offline (only while retries remain)
+        const stillOffline = this.opts.mcpManager.getConfiguredNames()
+            .filter(n => !this.mcpRegisteredServers.has(n));
+        if (stillOffline.length > 0) {
+            const retriesLeft = 3 - this.mcpInitAttempts;
+            const suffix = retriesLeft > 0
+                ? `Retrying on next message (${retriesLeft} attempts left).`
+                : `No more automatic retries — call engine.getMCPManager()?.reconnectFailed() to retry manually.`;
+            this.opts.transport.emit({
+                type: 'system', level: 'warn',
+                text: `MCP agents offline: ${stillOffline.join(', ')} — start their servers to enable them. ${suffix}`,
+            });
+        }
+    }
+    registerMCPAgent(config, tools) {
+        // safeName mirrors the sanitization done by MCPClientManager.wrapTool() so that
+        // tool lookup `mcp__${safeName}__${tool}` always resolves correctly.
+        const safeName = config.name.replace(/[^a-zA-Z0-9_-]/g, '_');
+        // Register tools in the ToolRegistry — skip already-registered ones
+        // (safe for reconnection scenarios; mcpRegisteredServers normally prevents duplicates)
+        for (const tool of tools) {
+            if (!this.opts.tools.has(tool.name)) {
+                this.opts.tools.register(tool);
+            }
+        }
+        // toolTriggers work in both modes — direct keyword → tool execution, zero LLM hops
+        if (config.toolTriggers) {
+            for (const [keyword, tool] of Object.entries(config.toolTriggers)) {
+                this.mcpToolTriggers.set(keyword.toLowerCase(), { agentId: safeName, tool });
+            }
+        }
+        const mode = config.mode ?? 'tools';
+        if (mode === 'tools') {
+            this.registerMCPToolPack(config, tools, safeName);
+        }
+        else {
+            this.registerMCPAgentWrapper(config, tools, safeName);
+        }
+    }
+    /**
+     * mode='tools' (default): assigns MCP tools directly to local agent allowedTools.
+     * Also applies blocksCommands to those agents while the server is connected —
+     * forcing them to use the MCP tools instead of equivalent shell commands.
+     * Both tool assignments and command blocks are tracked so they can be
+     * fully reverted when the server disconnects via unregisterMCPServer().
+     */
+    registerMCPToolPack(config, tools, safeName) {
+        const toolNames = tools.map(t => t.name);
+        const blocksCommands = config.blocksCommands ?? [];
+        // Resolve target agents: explicit assignTo list, or all registered agents
+        const assignTo = config.assignTo?.filter(id => id !== '*') ?? [];
+        const targets = assignTo.length > 0
+            ? assignTo
+            : this.opts.agents.getAll().map(a => a.id);
+        const blockRecord = [];
+        for (const agentId of targets) {
+            const agent = this.opts.agents.get(agentId);
+            if (!agent) {
+                this.opts.transport.emit({
+                    type: 'system', level: 'warn',
+                    text: `[MCP:${config.name}] assignTo agent "${agentId}" not found — skipped.`,
+                });
+                continue;
+            }
+            this.opts.agents.upsert({
+                ...agent,
+                allowedTools: [...new Set([...agent.allowedTools, ...toolNames])],
+                blockedCommands: [...new Set([...(agent.blockedCommands ?? []), ...blocksCommands])],
+            });
+            blockRecord.push({ agentId, toolNames, blockedCmds: blocksCommands });
+        }
+        this.mcpAgentBlocks.set(safeName, blockRecord);
+        if (config.triggers?.length) {
+            this.opts.transport.emit({
+                type: 'system', level: 'warn',
+                text: `[MCP:${config.name}] 'triggers' is ignored in mode='tools'. Use 'toolTriggers' for direct keyword routing.`,
+            });
+        }
+        const shortNames = tools.map(t => t.name.split('__')[2] ?? t.name).join(', ');
+        const agentList = targets.join(', ') || 'all agents';
+        const blockedLabel = blocksCommands.length ? `  blocked: [${blocksCommands.join(', ')}]` : '';
+        this.opts.transport.emit({
+            type: 'system', level: 'info',
+            text: `[MCP:${config.name}] tools [${shortNames}] assigned to: ${agentList}${blockedLabel}`,
+        });
+    }
+    /**
+     * mode='agent': wraps the MCP server as a delegatable agent in the roster.
+     * Use only when the remote service has its own reasoning layer or its output
+     * is so large it needs a dedicated summarization turn.
+     */
+    registerMCPAgentWrapper(config, tools, safeName) {
+        const toolList = tools
+            .map(t => {
+            const shortName = t.name.split('__')[2] ?? t.name;
+            const desc = t.description.replace(/^\[MCP:[^\]]+\]\s*/, '').slice(0, 80);
+            return `- ${shortName}: ${desc}`;
+        })
+            .join('\n');
+        const enrichedDesc = tools
+            .map(t => {
+            const shortName = t.name.split('__')[2] ?? t.name;
+            const desc = t.description.replace(/^\[MCP:[^\]]+\]\s*/, '').slice(0, 70);
+            return `${shortName}: ${desc}`;
+        })
+            .join(' | ');
+        this.opts.agents.upsert({
+            id: safeName,
+            name: config.agentName ?? toTitleCase(config.name),
+            icon: config.icon ?? '◎',
+            description: config.agentDescription ?? `External specialist — ${enrichedDesc}`,
+            systemPrompt: `You are a specialized remote agent: ${config.name}.\n` +
+                `Use ONLY your available tools to answer the request. ` +
+                `Do NOT use run_command, read_file, or other local tools.\n\n` +
+                `Your tools:\n${toolList}`,
+            allowedTools: tools.map(t => t.name),
+            source: 'mcp',
+        });
+        if (config.triggers?.length) {
+            this.mcpTriggers.set(safeName, config.triggers);
+        }
+    }
+    findMCPRoute(input) {
+        const lower = input.toLowerCase();
+        for (const [keyword, route] of this.mcpToolTriggers) {
+            if (lower.includes(keyword))
+                return route;
+        }
+        for (const [agentId, triggers] of this.mcpTriggers) {
+            if (triggers.some(t => lower.includes(t.toLowerCase())))
+                return { agentId };
+        }
+        return undefined;
+    }
+    switchAgent(agentId) {
+        if (!this.opts.agents.has(agentId))
+            throw new Error(`Agent "${agentId}" not found`);
+        this.currentAgentId = agentId;
+    }
+    getCurrentProfile() {
+        return this.opts.agents.get(this.currentAgentId);
+    }
+    buildAgentRoster(excludeId) {
+        const all = this.opts.agents.getAll().filter(a => a.id !== excludeId);
+        const mcp = all.filter(a => a.source === 'mcp');
+        const local = all.filter(a => a.source !== 'mcp');
+        const parts = [];
+        if (mcp.length > 0) {
+            parts.push('## External Agents [MCP] — CHECK FIRST. If the task matches any of these, you MUST delegate to them via ask_agent before considering local agents.');
+            for (const a of mcp) {
+                parts.push(`- ${a.id} (${a.icon}): ${a.description} [MCP]`);
+            }
+        }
+        parts.push('## Local Agents — use only when no [MCP] agent covers the task.');
+        for (const a of local) {
+            const tag = a.source === 'project' ? ' [PROJECT]' : a.source === 'global' ? ' [GLOBAL]' : '';
+            parts.push(`- ${a.id} (${a.icon}): ${a.description}${tag}`);
+        }
+        return parts.join('\n');
+    }
+    buildSystemPrompt(profile, orchestrationResult) {
+        const isOrchestrator = profile.id === this.opts.defaultAgentId;
+        const parts = [profile.systemPrompt];
+        if (isOrchestrator)
+            parts.push(this.buildAgentRoster(profile.id));
+        if (this.opts.workingDir) {
+            parts.push(`## Working Directory\n` +
+                `\`${this.opts.workingDir}\`\n\n` +
+                `ALWAYS use RELATIVE paths with tools (e.g. \`src/index.ts\`, \`package.json\`). ` +
+                `NEVER invent absolute paths like \`/workspace/...\` or \`/home/...\`.`);
+        }
+        if (this.opts.projectContext)
+            parts.push(this.opts.projectContext);
+        // Per-agent session notes (tool quirks, learnings routed by LearningRouter)
+        const agentNotes = this.opts.store?.getAgentNotes?.(profile.id);
+        if (agentNotes)
+            parts.push(`## Agent Session Notes\n${agentNotes}`);
+        if (this.memoryContextBlock)
+            parts.push(this.memoryContextBlock);
+        if (this.activeSkillAddition)
+            parts.push(this.activeSkillAddition);
+        if (isOrchestrator && orchestrationResult) {
+            parts.push(this.buildOrchestrationBrief(orchestrationResult));
+        }
+        return parts.join('\n\n');
+    }
+    /**
+     * Converts an OrchestrationResult into a system-prompt section that tells the
+     * default agent which specialists to use, in what order, and what gates apply.
+     * This closes the gap between the deterministic policy layer and the LLM layer.
+     */
+    buildOrchestrationBrief(result) {
+        const { task, selectedAgents, agentPipeline, requiredGates } = result;
+        const lines = ['## Orchestrator Analysis — Current Task'];
+        const domains = task.domains.length > 0 ? task.domains.join(', ') : 'general';
+        lines.push(`**Intent:** ${task.actionType} | **Risk:** ${task.riskLevel} | **Domains:** ${domains}`);
+        // Only surface non-trivial agent selections (skip sole-fallback case)
+        const nonFallback = selectedAgents.filter(a => !(a.agentId === 'general' && a.score <= 50));
+        if (nonFallback.length > 0) {
+            lines.push('\n**Recommended agents for this task (highest priority first):**');
+            for (const a of nonFallback) {
+                lines.push(`- ${a.agentId} — ${a.reason}`);
+            }
+            lines.push('\nWhen delegating via ask_agent, prioritize the agents listed above. ' +
+                'Do not delegate to unlisted agents unless the task explicitly requires it.');
+        }
+        if (agentPipeline && agentPipeline.length > 0) {
+            lines.push('\n**Suggested execution pipeline (respect this order):**');
+            agentPipeline.forEach((phase, i) => {
+                lines.push(`${i + 1}. [${phase.phase}] ${phase.agentId} — ${phase.purpose}`);
+            });
+        }
+        if (requiredGates.length > 0) {
+            lines.push(`\n**Required gates before commit:** ${requiredGates.join(', ')}`);
+            lines.push('Ensure each gate is satisfied before considering the task complete.');
+        }
+        return lines.join('\n');
+    }
+    resolvesDelegateTo(profile) {
+        if (!profile.delegatesTo || profile.delegatesTo.length === 0)
+            return [];
+        if (profile.delegatesTo[0] === '*') {
+            return this.opts.agents.getAll()
+                .map(a => a.id)
+                .filter(id => id !== profile.id);
+        }
+        return profile.delegatesTo;
+    }
+    getToolsForAgent(profile) {
+        const tools = this.opts.tools.getForAgent(profile.allowedTools);
+        if (profile.id === this.opts.defaultAgentId) {
+            tools.push(ASK_AGENT_TOOL);
+        }
+        return tools;
+    }
+    /**
+     * Merges the orchestrator's current-turn analysis with the explicit context the
+     * LLM provided in the ask_agent call. The analysis (streamBuffer) gives specialists
+     * the reasoning and data the orchestrator gathered before delegating.
+     */
+    buildSubAgentContext(explicit, orchestratorAnalysis) {
+        const trimmed = orchestratorAnalysis.trim();
+        if (!explicit && !trimmed)
+            return undefined;
+        const parts = [];
+        if (explicit)
+            parts.push(explicit);
+        if (trimmed)
+            parts.push(`## Análisis del orquestador\n${trimmed}`);
+        return parts.join('\n\n');
+    }
+    async runLoop(profile, orchestrationResult) {
+        let currentProfile = profile;
+        this.iterationManager.reset();
+        const iterManager = this.iterationManager;
+        this.opts.transport.emit({
+            type: 'block_start',
+            agent_id: profile.id,
+            agent_name: profile.name,
+            agent_icon: profile.icon,
+        });
+        while (!this.aborted) {
+            const shouldContinue = await iterManager.advance();
+            if (!shouldContinue)
+                break;
+            this.trimHistory();
+            const systemMsg = { role: 'system', content: this.buildSystemPrompt(currentProfile, orchestrationResult) };
+            const tools = this.getToolsForAgent(currentProfile);
+            const safeHistory = sanitizeMessages(this.messages);
+            let streamBuffer = '';
+            const askAgentCalls = [];
+            const otherCalls = [];
+            let finalMessage = null;
+            this.abortController = new AbortController();
+            const signal = this.abortController.signal;
+            await this.getProviderForProfile(currentProfile).chat([systemMsg, ...safeHistory], tools, {
+                onChunk: (delta) => {
+                    streamBuffer += delta;
+                    this.opts.transport.emit({ type: 'token', content: delta, agent_id: currentProfile.id });
+                },
+                onToolCall: (name, args, id) => {
+                    this.opts.transport.emit({ type: 'tool_call', name, args_preview: args.slice(0, 80) });
+                    if (name === 'ask_agent') {
+                        try {
+                            const parsed = JSON.parse(args);
+                            askAgentCalls.push({ id, agentId: parsed.agent_id, question: parsed.question, context: parsed.context });
+                        }
+                        catch {
+                            otherCalls.push({ id, name, args });
+                        }
+                    }
+                    else {
+                        otherCalls.push({ id, name, args });
+                    }
+                },
+                onDone: (msg) => { finalMessage = msg; },
+                onError: (err) => {
+                    if (!this.aborted)
+                        this.opts.transport.emit({ type: 'error', message: err.message });
+                },
+                onMetrics: (inputTokens, outputTokens) => {
+                    this.opts.transport.emit({ type: 'metrics', input_tokens: inputTokens, output_tokens: outputTokens });
+                },
+                signal,
+            });
+            this.abortController = null;
+            if (this.aborted)
+                break;
+            if (!finalMessage)
+                break;
+            this.messages.push(finalMessage);
+            const toolResults = [];
+            // ── ask_agent: parallel if 2+ calls ──────────────────────────────
+            if (askAgentCalls.length > 0) {
+                const validCalls = askAgentCalls.filter(c => c.agentId !== currentProfile.id);
+                const selfCalls = askAgentCalls.filter(c => c.agentId === currentProfile.id);
+                for (const call of selfCalls) {
+                    const msg = `Self-delegation blocked: agent "${currentProfile.id}" cannot delegate to itself. Execute the task directly.`;
+                    this.opts.transport.emit({ type: 'tool_result', name: 'ask_agent', success: false, preview: msg });
+                    toolResults.push({ role: 'tool', tool_call_id: call.id, content: msg });
+                }
+                if (validCalls.length > 0) {
+                    const requests = validCalls.map(c => ({
+                        agentId: c.agentId,
+                        question: c.question,
+                        context: this.buildSubAgentContext(c.context, streamBuffer),
+                    }));
+                    const results = validCalls.length >= 2
+                        ? await this.bus.runParallel(requests)
+                        : [await this.bus.runSingle(requests[0])];
+                    for (let i = 0; i < validCalls.length; i++) {
+                        const call = validCalls[i];
+                        const result = results[i];
+                        const content = result.error ? `Error: ${result.error}` : result.content;
+                        this.opts.transport.emit({ type: 'tool_result', name: 'ask_agent', success: !result.error, preview: content.slice(0, 120) });
+                        toolResults.push({ role: 'tool', tool_call_id: call.id, content });
+                    }
+                }
+            }
+            // ── other tools: sequential ───────────────────────────────────────
+            for (const call of otherCalls) {
+                if (this.aborted)
+                    break;
+                iterManager.recordToolCall();
+                const result = await this.executeToolCall(call, currentProfile);
+                toolResults.push({ role: 'tool', tool_call_id: call.id, content: result });
+            }
+            // ── QA orchestration: runs when response is final (no tool calls) ─
+            if (toolResults.length === 0 && this.opts.orchestrator && this.opts.qaService && orchestrationResult) {
+                const qaAgentId = this.opts.agents.has('qa-engineer') ? 'qa-engineer' : undefined;
+                const qaCtx = {
+                    clean: streamBuffer,
+                    orchestrationResult,
+                    orchestrator: this.opts.orchestrator,
+                    qaService: this.opts.qaService,
+                    allAgents: this.opts.agents.getAll(),
+                    messages: this.messages,
+                    effectiveAgentId: currentProfile.id,
+                    defaultAgentId: this.opts.defaultAgentId,
+                    qaAgentId,
+                    noQA: this.opts.noQA,
+                    onQAReview: this.opts.onQAReview,
+                    setEffectiveAgent: (agentId) => {
+                        const p = this.opts.agents.get(agentId);
+                        if (p)
+                            currentProfile = p;
+                    },
+                };
+                await (0, qa_orchestrator_1.advanceRequiredGates)(qaCtx);
+                const qaProfile = (0, qa_orchestrator_1.activateQaEngineerIfNeeded)(qaCtx);
+                if (qaProfile) {
+                    currentProfile = qaProfile;
+                    continue; // re-enter loop as qa-engineer
+                }
+                if (qaAgentId && currentProfile.id === qaAgentId) {
+                    await (0, qa_orchestrator_1.processQaEngineerResponse)(qaCtx);
+                    currentProfile = profile; // reset to original agent
+                }
+                else {
+                    await (0, qa_orchestrator_1.processInlineQaReview)(qaCtx);
+                }
+            }
+            if (toolResults.length === 0)
+                break;
+            this.messages.push(...toolResults);
+        }
+        this.opts.transport.emit({ type: 'block_end', status: 'ok', agent_id: profile.id });
+    }
+    async runAgentInternal(agentId, question, context) {
+        const profile = this.opts.agents.get(agentId);
+        if (!profile)
+            throw new Error(`Agent "${agentId}" not registered`);
+        const start = Date.now();
+        // Inject recent history from the orchestrator's conversation so specialists
+        // can see previously gathered data (file reads, command outputs, etc.)
+        // without requiring the orchestrator to manually copy it into context.
+        let historySlice = [];
+        const maxCtxMsgs = this.opts.subAgentContextMessages;
+        if (maxCtxMsgs && maxCtxMsgs > 0 && this.messages.length > 0) {
+            historySlice = this.messages.slice(-maxCtxMsgs);
+            // Trim to the first user-turn boundary to avoid orphaning tool results.
+            const firstUser = historySlice.findIndex(m => m.role === 'user');
+            if (firstUser > 0)
+                historySlice = historySlice.slice(firstUser);
+            else if (firstUser < 0)
+                historySlice = [];
+            // Sanitize: drop any tool messages whose assistant(tool_calls) was cut off
+            historySlice = sanitizeMessages(historySlice);
+        }
+        const messages = [
+            { role: 'system', content: this.buildSystemPrompt(profile) },
+            ...historySlice,
+            { role: 'user', content: context ? `${question}\n\nContexto:\n${context}` : question },
+        ];
+        let finalContent = '';
+        let totalInputTokens = 0;
+        let totalOutputTokens = 0;
+        const maxIter = 30;
+        let iter = 0;
+        this.opts.transport.emit({ type: 'block_start', agent_id: profile.id, agent_name: profile.name, agent_icon: profile.icon });
+        while (iter < maxIter) {
+            iter++;
+            let streamContent = '';
+            const toolCalls = [];
+            let finalMessage = null;
+            await this.getProviderForProfile(profile).chat(messages, this.getToolsForAgent(profile), {
+                onChunk: (delta) => {
+                    streamContent += delta;
+                    this.opts.transport.emit({ type: 'token', content: delta, agent_id: profile.id });
+                },
+                onToolCall: (name, args, id) => {
+                    this.opts.transport.emit({ type: 'tool_call', name, args_preview: args.slice(0, 80) });
+                    toolCalls.push({ id, name, args });
+                },
+                onDone: (msg) => { finalMessage = msg; },
+                onError: (err) => { throw err; },
+                onMetrics: (inputTokens, outputTokens) => {
+                    totalInputTokens += inputTokens;
+                    totalOutputTokens += outputTokens;
+                    this.opts.transport.emit({ type: 'metrics', input_tokens: inputTokens, output_tokens: outputTokens });
+                },
+            });
+            if (!finalMessage)
+                break;
+            if (streamContent)
+                finalContent = streamContent;
+            messages.push(finalMessage);
+            if (toolCalls.length === 0)
+                break;
+            const toolResults = [];
+            for (const call of toolCalls) {
+                const result = await this.executeToolCall(call, profile);
+                toolResults.push({ role: 'tool', tool_call_id: call.id, content: result });
+            }
+            messages.push(...toolResults);
+        }
+        this.opts.transport.emit({ type: 'block_end', status: 'ok', agent_id: profile.id });
+        return { agentId, content: finalContent, inputTokens: totalInputTokens, outputTokens: totalOutputTokens, elapsedMs: Date.now() - start };
+    }
+    /**
+     * Unified tool execution used by both runLoop (primary agent) and
+     * runAgentInternal (sub-agents via ask_agent).
+     * Handles: allowedTools authorization → onToolApproval gate → execute → audit → transport.
+     */
+    async executeToolCall(call, profile) {
+        const callStart = Date.now();
+        const toolDef = this.opts.tools.get(call.name);
+        let result;
+        if (!toolDef) {
+            result = `Tool "${call.name}" not found`;
+        }
+        else if (!profile.allowedTools.includes(call.name) &&
+            (profile.allowedTools.length > 0 || (profile.delegatesTo && profile.delegatesTo.length > 0))) {
+            result = `Tool "${call.name}" is not authorized for agent "${profile.id}". ` +
+                `Use ask_agent to delegate to a specialist.`;
+        }
+        else if (this.opts.onToolApproval && this.requiresAlwaysAsk(call)) {
+            // High-blast-radius operations (npm install, pip install, etc.) always
+            // require approval — cannot be bypassed by approve_all or auto mode.
+            const preview = call.args.slice(0, 200);
+            this.opts.transport.emit({
+                type: 'tool_approval_request',
+                tool_name: call.name,
+                agent_id: profile.id,
+                args_preview: preview,
+            });
+            const decision = await this.opts.onToolApproval(call.name, profile.id, preview);
+            result = decision === 'reject'
+                ? `Tool call "${call.name}" was rejected by the user.`
+                : await this.runToolDef(call, toolDef, profile.id);
+        }
+        else if (!this.approvalDisabled &&
+            this.opts.onToolApproval &&
+            AgentEngine.WRITE_TOOLS.has(call.name)) {
+            const preview = call.args.slice(0, 200);
+            this.opts.transport.emit({
+                type: 'tool_approval_request',
+                tool_name: call.name,
+                agent_id: profile.id,
+                args_preview: preview,
+            });
+            const decision = await this.opts.onToolApproval(call.name, profile.id, preview);
+            if (decision === 'approve_all')
+                this.approvalDisabled = true;
+            result = decision === 'reject'
+                ? `Tool call "${call.name}" was rejected by the user.`
+                : await this.runToolDef(call, toolDef, profile.id);
+        }
+        else {
+            result = await this.runToolDef(call, toolDef, profile.id);
+        }
+        const success = !result.startsWith('Error:');
+        this.writeAuditRecord(profile.id, call.name, call.args, success, Date.now() - callStart);
+        this.opts.transport.emit({ type: 'tool_result', name: call.name, success, preview: result.slice(0, 120) });
+        return result;
+    }
+    async runToolDef(call, toolDef, agentId) {
+        const ctx = this.buildContext(agentId);
+        try {
+            const args = JSON.parse(call.args);
+            return await toolDef.execute(args, ctx);
+        }
+        catch (err) {
+            return `Error: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    /**
+     * Returns true when a tool call matches a high-blast-radius pattern that
+     * always requires explicit approval — cannot be bypassed by approve_all or
+     * auto iteration mode.
+     */
+    requiresAlwaysAsk(call) {
+        if (call.name !== 'run_command')
+            return false;
+        try {
+            const { command } = JSON.parse(call.args);
+            if (!command)
+                return false;
+            return AgentEngine.ALWAYS_ASK_PATTERNS.some(re => re.test(command));
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Disconnects an MCP server at runtime — reverts all tool assignments and
+     * command blocks it applied to local agents. After calling this, agents that
+     * had tools from this server lose them from allowedTools, and any commands
+     * that were blocked via blocksCommands are unblocked.
+     *
+     * For mode='agent' servers, the wrapper agent is also removed from the roster.
+     * For mode='tools' servers, agents fall back to shell commands automatically.
+     */
+    unregisterMCPServer(serverName) {
+        const safeName = serverName.replace(/[^a-zA-Z0-9_-]/g, '_');
+        // Revert tool assignments and command blocks on affected agents
+        const records = this.mcpAgentBlocks.get(safeName) ?? [];
+        for (const { agentId, toolNames, blockedCmds } of records) {
+            const agent = this.opts.agents.get(agentId);
+            if (agent) {
+                this.opts.agents.upsert({
+                    ...agent,
+                    allowedTools: agent.allowedTools.filter(t => !toolNames.includes(t)),
+                    blockedCommands: (agent.blockedCommands ?? []).filter(c => !blockedCmds.includes(c)),
+                });
+            }
+            for (const toolName of toolNames) {
+                this.opts.tools.unregister(toolName);
+            }
+        }
+        this.mcpAgentBlocks.delete(safeName);
+        // Remove wrapper agent if mode='agent'
+        this.opts.agents.delete(safeName);
+        // Clean up routing tables
+        this.mcpTriggers.delete(safeName);
+        for (const [keyword, route] of this.mcpToolTriggers) {
+            if (route.agentId === safeName)
+                this.mcpToolTriggers.delete(keyword);
+        }
+        this.mcpRegisteredServers.delete(serverName);
+        this.opts.transport.emit({
+            type: 'system', level: 'info',
+            text: `[MCP:${serverName}] unregistered — tools removed, commands unblocked.`,
+        });
+    }
+    /** Disable approval gate for the rest of this session (approve_all). */
+    disableToolApproval() { this.approvalDisabled = true; }
+    /** Re-enable approval gate (e.g. after /iteration manual). */
+    enableToolApproval() { this.approvalDisabled = false; }
+    writeAuditRecord(agentId, tool, inputPreview, success, durationMs) {
+        if (!this.opts.auditLog)
+            return;
+        const line = JSON.stringify({
+            ts: new Date().toISOString(),
+            session: this.opts.sessionId ?? 'default',
+            agent: agentId,
+            tool,
+            input: inputPreview.slice(0, 200),
+            success,
+            durationMs,
+        });
+        (0, fs_1.appendFileSync)(this.opts.auditLog, line + '\n');
+    }
+    buildContext(agentId) {
+        const id = agentId ?? this.currentAgentId;
+        const profile = this.opts.agents.get(id);
+        return {
+            agentId: id,
+            sessionId: this.opts.sessionId ?? 'default',
+            workingDir: this.opts.workingDir,
+            memory: this.memory,
+            store: this.opts.store,
+            advancedMemory: this.opts.memorySystem,
+            ...(profile?.blockedCommands?.length ? { blockedCommands: profile.blockedCommands } : {}),
+            askAgent: async (agentId, question, context) => {
+                const result = await this.bus.runSingle({ agentId, question, context });
+                return result.content;
+            },
+            emitCompacting: (phase, label) => {
+                this.opts.transport.emit({ type: 'compacting', phase, label });
+            },
+            llmCall: async (prompt) => {
+                const profile = this.opts.agents.get(this.currentAgentId);
+                if (!profile)
+                    return '';
+                const provider = this.getProviderForProfile(profile);
+                let result = '';
+                await provider.chat([{ role: 'user', content: prompt }], [], {
+                    onChunk: (d) => { result += d; },
+                    onToolCall: () => { },
+                    onDone: () => { },
+                    onError: () => { },
+                });
+                return result.trim();
+            },
+        };
+    }
+}
+exports.AgentEngine = AgentEngine;
+function toTitleCase(s) {
+    return s
+        .replace(/[-_](.)/g, (_, c) => ' ' + c.toUpperCase())
+        .replace(/^(.)/, (c) => c.toUpperCase());
+}
+//# sourceMappingURL=AgentEngine.js.map