@crewx/sdk 0.8.0-rc.72 → 0.8.0-rc.74

package/dist/facade/Crewx.js

@@ -0,0 +1,1299 @@
+"use strict";
+/**
+ * Crewx facade — main entry point for the CrewX SDK.
+ * Provides loadYaml(), fromConfig(), query(), execute(), renderAgentPromptFull(),
+ * and registerLayout() methods.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Crewx = void 0;
+const path_1 = require("path");
+const glob_match_1 = require("../utils/glob-match");
+const loader_1 = require("../config/loader");
+const resolver_1 = require("../agent/resolver");
+const bridge_1 = require("../provider/bridge");
+const engine_1 = require("../template/engine");
+const DocumentLoader_1 = require("../template/loader/DocumentLoader");
+const loader_2 = require("../layout/loader");
+const renderer_1 = require("../layout/renderer");
+const id_1 = require("../utils/id");
+const timestamp_1 = require("../utils/timestamp");
+const TypedEventEmitter_1 = require("../events/TypedEventEmitter");
+const scoped_store_1 = require("../adapter/scoped-store");
+const context_builder_1 = require("../adapter/context-builder");
+const router_1 = require("../parsers/router");
+const to_template_messages_1 = require("../conversation/to-template-messages");
+const handler_1 = require("../server/handler");
+const conversation_1 = require("../plugins/conversation");
+const workspace_1 = require("../utils/workspace");
+/**
+ * Extract exec policy from config.settings.template.exec if present.
+ */
+function extractExecPolicyFromConfig(config) {
+    if (!config)
+        return undefined;
+    const settings = config.settings;
+    const templateSettings = settings?.['template'];
+    const exec = templateSettings?.['exec'];
+    return exec;
+}
+/**
+ * Generate a random security key (16-char hex, same as global crewx).
+ * Uses crypto.getRandomValues (browser-safe) with Node crypto.randomBytes fallback.
+ */
+function generateSecurityKey() {
+    try {
+        // Works in both browser (globalThis.crypto) and Node 19+ (globalThis.crypto)
+        const bytes = new Uint8Array(8);
+        globalThis.crypto.getRandomValues(bytes);
+        return Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+    }
+    catch {
+        // Fallback: Node.js crypto module
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { randomBytes } = require('crypto');
+        return randomBytes(8).toString('hex');
+    }
+}
+/**
+ * Build the default SDK templates path.
+ */
+const SDK_TEMPLATES_PATH = (0, path_1.join)(__dirname, '../../templates/agents');
+class Crewx extends TypedEventEmitter_1.TypedEventEmitter {
+    _agents;
+    _templateEngine;
+    _documentLoader;
+    _layoutLoader;
+    _layoutRenderer;
+    _config;
+    _projectRoot;
+    _workspaceId;
+    _workspaceName;
+    _plugins = [];
+    _tools = new Map();
+    _activeAdapters = new Map();
+    _pendingThreads = new Map();
+    /**
+     * Bootstrap factory for target Crewx instances when delegating file:// remote agents.
+     * Consumers (CLI / server / Slack) provide their own bootstrap wrapper so that the
+     * target inherits the same plugin/environment setup as the caller.
+     */
+    _remoteFactory;
+    /** Lazily-created target Crewx instances, keyed by absolute configPath. */
+    _remoteTargets = new Map();
+    constructor(agents, options = {}, config, documentLoader, projectRoot) {
+        super();
+        this._agents = new Map(agents.map(a => [a.id, a]));
+        this._config = config;
+        this._projectRoot = projectRoot ?? (typeof process !== 'undefined' ? process.cwd() : '/');
+        // Workspace single source of truth (WI-CONV-003, WI-20260418-002):
+        // projectRoot takes priority so that a target crewx instance gets its own workspace ID
+        // rather than inheriting the caller's cwd.
+        const workspacePath = projectRoot ?? (typeof process !== 'undefined'
+            ? (process.env.CREWX_WORKSPACE ?? process.cwd())
+            : '/');
+        this._workspaceId = (0, workspace_1.hashWorkspaceId)(workspacePath);
+        this._workspaceName = (0, path_1.basename)(workspacePath);
+        const settingsPolicy = extractExecPolicyFromConfig(config);
+        this._templateEngine = new engine_1.TemplateEngine({
+            execPolicy: options.execPolicy ?? settingsPolicy,
+        });
+        this._documentLoader = documentLoader ?? new DocumentLoader_1.DocumentLoader();
+        this._layoutLoader = new loader_2.LayoutLoader({ templatesPath: SDK_TEMPLATES_PATH });
+        this._layoutRenderer = new renderer_1.LayoutRenderer();
+        this._remoteFactory = options.remoteFactory;
+    }
+    /**
+     * If `agentRef` resolves to a `remote/*` provider backed by `file://`, return
+     * the target Crewx (lazily bootstrapped) together with the agent ref to use
+     * inside the target. Returns null for local agents or non-file remotes.
+     *
+     * The caller's Crewx.query/execute delegates entirely to the returned target
+     * (including task:start/end emit, renderContext, plugins) so execution
+     * semantics exactly match running `crewx q` inside the target workspace.
+     */
+    async resolveFileRemoteTarget(agentRef) {
+        const agent = this.getAgent(agentRef);
+        const providerStr = Array.isArray(agent?.provider) ? agent?.provider[0] : agent?.provider;
+        if (!providerStr?.startsWith('remote/'))
+            return null;
+        const remoteId = providerStr.slice('remote/'.length);
+        const remoteConfig = this.getRemoteProviderConfig(remoteId);
+        if (!remoteConfig?.location?.startsWith('file://'))
+            return null;
+        const targetConfigPath = (0, path_1.resolve)(remoteConfig.location.replace('file://', ''));
+        const targetAgentId = remoteConfig.external_agent_id ?? agentRef.replace(/^@/, '');
+        let targetPromise = this._remoteTargets.get(targetConfigPath);
+        if (!targetPromise) {
+            const factory = this._remoteFactory ?? ((p) => Crewx.loadYaml(p));
+            targetPromise = factory(targetConfigPath);
+            this._remoteTargets.set(targetConfigPath, targetPromise);
+            // On failure, drop the cached Promise so the next call can retry.
+            targetPromise.catch(() => this._remoteTargets.delete(targetConfigPath));
+        }
+        const target = await targetPromise;
+        // Guard: target agent must not itself be a remote/ provider (chained remotes).
+        const targetAgent = target.getAgent('@' + targetAgentId);
+        const targetProviderStr = Array.isArray(targetAgent?.provider)
+            ? targetAgent?.provider[0]
+            : targetAgent?.provider;
+        if (targetProviderStr?.startsWith('remote/')) {
+            throw new Error(`Chained remotes not allowed: "${remoteId}" → "${targetProviderStr}"`);
+        }
+        return { target, agentRef: '@' + targetAgentId };
+    }
+    /**
+     * Load crewx.yaml from the given file path and create a Crewx instance.
+     */
+    static async loadYaml(path, options, fsAdapter) {
+        const config = (0, loader_1.loadYamlFile)(path);
+        const projectRoot = (0, path_1.dirname)(path);
+        const loader = new DocumentLoader_1.DocumentLoader(fsAdapter);
+        await loader.load(config.documents, projectRoot);
+        // Auto-register api/* provider factory if any agent uses api/ namespace
+        const agents = config.agents ?? [];
+        const hasApiProvider = agents.some((a) => {
+            const providers = Array.isArray(a.provider) ? a.provider : [a.provider];
+            return providers.some(p => p.startsWith('api/'));
+        });
+        if (hasApiProvider) {
+            const { registerApiProviders } = await Promise.resolve().then(() => __importStar(require('../provider/register-api.js')));
+            registerApiProviders(options?.api);
+        }
+        // Auto-register remote/* provider factory if any agent uses remote/ namespace
+        registerRemoteProvidersIfNeeded(agents, config);
+        // Auto-register plugin/* provider factory if any agent uses plugin/ namespace
+        registerPluginProvidersIfNeeded(agents, config);
+        const instance = new Crewx(agents, options ?? {}, config, loader, projectRoot);
+        await instance.use(new conversation_1.ConversationPlugin());
+        return instance;
+    }
+    /**
+     * Create a Crewx instance from an already-parsed config object.
+     */
+    static async fromConfig(config, options, projectRoot, fsAdapter) {
+        const loader = new DocumentLoader_1.DocumentLoader(fsAdapter);
+        await loader.load(config.documents, projectRoot ?? (typeof process !== 'undefined' ? process.cwd() : '/'));
+        // Auto-register remote/* provider factory
+        registerRemoteProvidersIfNeeded(config.agents ?? [], config);
+        // Auto-register plugin/* provider factory
+        registerPluginProvidersIfNeeded(config.agents ?? [], config);
+        const instance = new Crewx(config.agents ?? [], options ?? {}, config, loader, projectRoot);
+        await instance.use(new conversation_1.ConversationPlugin());
+        return instance;
+    }
+    /** All loaded agents, keyed by agent id. */
+    get agents() {
+        return this._agents;
+    }
+    /** The raw project config (includes providers, settings, etc.). */
+    get config() {
+        return this._config;
+    }
+    /** All registered plugins. */
+    get plugins() {
+        return this._plugins;
+    }
+    /** All registered custom tools. */
+    get tools() {
+        return this._tools;
+    }
+    /** Workspace ID (SHA-256 hash). Single source of truth for all plugins. */
+    get workspaceId() {
+        return this._workspaceId;
+    }
+    /** Human-readable workspace name (basename of cwd). */
+    get workspaceName() {
+        return this._workspaceName;
+    }
+    /**
+     * Return an agent config by ref (with or without leading '@').
+     * Returns undefined if the agent is not found.
+     */
+    getAgent(agentRef) {
+        const id = agentRef.startsWith('@') ? agentRef.slice(1) : agentRef;
+        return this._agents.get(id);
+    }
+    /**
+     * Return a remote provider config by provider ID from the crewx.yaml `providers:` section.
+     * Returns undefined if not found or if config has no providers.
+     */
+    getRemoteProviderConfig(providerId) {
+        const providersRaw = this._config?.['providers'];
+        if (!Array.isArray(providersRaw))
+            return undefined;
+        const entry = providersRaw.find(e => e['type'] === 'remote' && e['id'] === providerId);
+        return entry;
+    }
+    computeTaskLogPath(traceId, timestamp) {
+        const ts = (0, timestamp_1.formatTimestamp)(timestamp);
+        return (0, path_1.join)(this._projectRoot, '.crewx', 'logs', `${ts}_${traceId}.log`);
+    }
+    /**
+     * Register a custom tool for use in agent prompts.
+     *
+     * Registered tools are included in the `tools` context of renderAgentPromptFull(),
+     * and can be invoked programmatically (e.g. in browser environments with API providers).
+     *
+     * @param name - Unique tool name (overwrites if already registered)
+     * @param definition - Tool definition with description, parameters, and execute function
+     */
+    registerTool(name, definition) {
+        this._tools.set(name, { name, ...definition });
+    }
+    /**
+     * Register a plugin and immediately call attach().
+     * Same instance registered twice is silently ignored (by reference).
+     */
+    async use(plugin) {
+        if (this._plugins.includes(plugin))
+            return;
+        await plugin.attach(this);
+        this._plugins.push(plugin);
+    }
+    /**
+     * Create a Web Standard MCP HTTP handler for exposing agents over the network.
+     *
+     * @param options - Handler config. `agents` list is required for security.
+     * @returns `(req: Request) => Promise<Response>` handler
+     */
+    handler(options) {
+        return (0, handler_1.createHandler)(this, options);
+    }
+    /**
+     * Register a channel adapter and start it.
+     */
+    async registerChannelAdapter(reg) {
+        const { adapter, instanceId, config } = reg;
+        if (this._activeAdapters.has(instanceId)) {
+            throw new Error(`Adapter instance already registered: ${instanceId}`);
+        }
+        const capabilities = new Set(adapter.manifest.capabilities);
+        const store = reg.store ?? (0, scoped_store_1.createScopedAdapterStore)(instanceId);
+        const defaultMode = reg.defaultMode ?? 'query';
+        const adapterPlatform = adapter.manifest.platform;
+        const agentRunner = reg.agentRunner ?? {
+            run: async (agentId, message, opts) => {
+                const fn = defaultMode === 'execute' ? this.execute.bind(this) : this.query.bind(this);
+                const result = await fn(`@${agentId}`, message, { threadId: opts?.threadId, platform: adapterPlatform });
+                return { output: result.ok ? result.data : (result.error?.message ?? '') };
+            },
+        };
+        const onInbound = reg.onInbound ?? (async (msg) => {
+            const agentId = msg.routingHints?.agentId ?? reg.defaultAgent;
+            if (!agentId) {
+                return { accepted: false, reason: 'no_agent' };
+            }
+            const { output } = await agentRunner.run(agentId, msg.text, { threadId: msg.threadId });
+            return { accepted: true, output };
+        });
+        const ctx = (0, context_builder_1.createAdapterContext)({
+            instanceId,
+            config,
+            capabilities,
+            db: store,
+            agentRunner,
+            onInbound,
+        });
+        const entry = { adapter: adapter, ctx: ctx, state: 'starting' };
+        this._activeAdapters.set(instanceId, entry);
+        this.emit('adapter:lifecycle', {
+            adapterId: adapter.manifest.id,
+            instanceId,
+            state: 'starting',
+            timestamp: new Date(),
+        });
+        try {
+            await adapter.start(ctx);
+            entry.state = 'started';
+            this.emit('adapter:lifecycle', {
+                adapterId: adapter.manifest.id,
+                instanceId,
+                state: 'started',
+                timestamp: new Date(),
+            });
+        }
+        catch (err) {
+            entry.state = 'failed';
+            this.emit('adapter:lifecycle', {
+                adapterId: adapter.manifest.id,
+                instanceId,
+                state: 'failed',
+                error: err instanceof Error ? err : new Error(String(err)),
+                timestamp: new Date(),
+            });
+            this._activeAdapters.delete(instanceId);
+            throw err;
+        }
+    }
+    /**
+     * Unregister and stop a channel adapter by instanceId.
+     */
+    async unregisterChannelAdapter(instanceId) {
+        const entry = this._activeAdapters.get(instanceId);
+        if (!entry)
+            return;
+        entry.state = 'stopping';
+        this.emit('adapter:lifecycle', {
+            adapterId: entry.adapter.manifest.id,
+            instanceId,
+            state: 'stopping',
+            timestamp: new Date(),
+        });
+        try {
+            await entry.adapter.stop(entry.ctx);
+            entry.state = 'stopped';
+            this.emit('adapter:lifecycle', {
+                adapterId: entry.adapter.manifest.id,
+                instanceId,
+                state: 'stopped',
+                timestamp: new Date(),
+            });
+        }
+        catch (err) {
+            entry.state = 'failed';
+            this.emit('adapter:lifecycle', {
+                adapterId: entry.adapter.manifest.id,
+                instanceId,
+                state: 'failed',
+                error: err instanceof Error ? err : new Error(String(err)),
+                timestamp: new Date(),
+            });
+        }
+        finally {
+            this._activeAdapters.delete(instanceId);
+        }
+    }
+    /**
+     * Stop all registered adapters with a timeout.
+     */
+    async stopAllAdapters(opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? 10_000;
+        const instanceIds = Array.from(this._activeAdapters.keys());
+        const results = await Promise.allSettled(instanceIds.map(id => Promise.race([
+            this.unregisterChannelAdapter(id),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`Adapter stop timeout: ${id}`)), timeoutMs)),
+        ])));
+        for (let i = 0; i < results.length; i++) {
+            if (results[i].status === 'rejected') {
+                console.error(`[crewx] adapter stop error (${instanceIds[i]}): ${results[i].reason}`);
+            }
+        }
+    }
+    /**
+     * Detach all plugins in LIFO order and release resources.
+     * Call before process exit for clean shutdown.
+     */
+    async close() {
+        await this.stopAllAdapters({ timeoutMs: 10_000 });
+        // Cascade close target Crewx instances bootstrapped for file:// remotes.
+        const remoteTargets = [...this._remoteTargets.values()];
+        this._remoteTargets.clear();
+        await Promise.allSettled(remoteTargets.map(async (p) => {
+            try {
+                await (await p).close();
+            }
+            catch (err) {
+                console.error(`[crewx] remote target close error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }));
+        const reversed = [...this._plugins].reverse();
+        for (const plugin of reversed) {
+            try {
+                await plugin.detach(this);
+            }
+            catch (err) {
+                console.error(`[crewx] plugin ${plugin.name} detach error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        this._plugins.length = 0;
+    }
+    /**
+     * Filter agents by role, team, and/or provider.
+     */
+    filterAgents(filters) {
+        const parseFilter = (value) => value ? value.split(',').map(v => v.trim().toLowerCase()).filter(Boolean) : undefined;
+        const roleFilter = parseFilter(filters.role);
+        const teamFilter = parseFilter(filters.team);
+        const providerFilter = parseFilter(filters.provider);
+        let result = Array.from(this._agents.values());
+        if (roleFilter) {
+            result = result.filter(a => a.role && roleFilter.some(f => (0, glob_match_1.matchesPattern)(a.role.toLowerCase(), f)));
+        }
+        if (teamFilter) {
+            result = result.filter(a => a.team && teamFilter.some(f => (0, glob_match_1.matchesPattern)(a.team.toLowerCase(), f)));
+        }
+        if (providerFilter) {
+            result = result.filter(a => {
+                const providers = Array.isArray(a.provider) ? a.provider : [a.provider];
+                return providers.some(pv => providerFilter.some(f => (0, glob_match_1.matchesPattern)(pv.toLowerCase(), f)));
+            });
+        }
+        return result;
+    }
+    /**
+     * Return the raw system prompt for the given agent (no template expansion, no layout).
+     * @throws AgentNotFoundError if agentId is not found
+     */
+    renderAgentPrompt(agentId) {
+        const id = agentId.startsWith('@') ? agentId.slice(1) : agentId;
+        const agent = this._agents.get(id);
+        if (!agent) {
+            throw new resolver_1.AgentNotFoundError(id, Array.from(this._agents.keys()));
+        }
+        return (agent.inline?.prompt ??
+            agent.inline?.system_prompt ??
+            agent.description ??
+            `You are an expert ${id}.`);
+    }
+    /**
+     * Render a Handlebars template string with the given context.
+     * Documents from crewx.yaml are automatically merged into context.documents.
+     */
+    async renderPrompt(template, context) {
+        const loaderDocs = await this._documentLoader.buildContext();
+        const mergedDocs = { ...loaderDocs, ...(context?.documents ?? {}) };
+        const mergedContext = { ...context, documents: mergedDocs };
+        return this._templateEngine.render(template, mergedContext);
+    }
+    /**
+     * Register a custom layout template at runtime.
+     *
+     * @param name     - Layout identifier (used as-is, no forced namespace)
+     * @param template - Handlebars template string or CustomLayoutDefinition
+     */
+    registerLayout(name, template) {
+        this._layoutLoader.registerLayout(name, template);
+    }
+    /**
+     * Render the full agent prompt using the layout system.
+     *
+     * Resolution priority (first match wins):
+     *   1. options.layout           (call-site override)
+     *   2. agent.inline.layout      (agent YAML definition)
+     *   3. config.layouts.default   (project-level default)
+     *   4. SDK built-in default     (crewx/default)
+     *
+     * @param agentId - Agent ID (with or without leading '@')
+     * @param options - Optional layout/session/env/vars overrides
+     * @throws AgentNotFoundError if agentId is not found
+     */
+    async renderAgentPromptFull(agentId, options) {
+        const id = agentId.startsWith('@') ? agentId.slice(1) : agentId;
+        const agent = this._agents.get(id);
+        if (!agent) {
+            throw new resolver_1.AgentNotFoundError(id, Array.from(this._agents.keys()));
+        }
+        // ── Step 1: Resolve layout spec ─────────────────────────────────────────
+        const layoutSpec = this._resolveLayoutSpec(agent, options?.layout);
+        const layoutId = this._extractLayoutId(layoutSpec);
+        const layoutProps = this._extractLayoutProps(agent, layoutSpec, options?.layout);
+        // ── Step 2: Load layout definition ──────────────────────────────────────
+        const layout = this._layoutLoader.load(layoutId, layoutProps);
+        // ── Step 3: Pre-render agent.inline.prompt through TemplateEngine ────────
+        //    (expands exec, documents, env vars inside the prompt template)
+        const rawPrompt = agent.inline?.prompt ??
+            agent.inline?.system_prompt ??
+            agent.description ??
+            `You are an expert ${id}.`;
+        const loaderDocs = await this._documentLoader.buildContext();
+        const env = options?.env ?? (typeof process !== 'undefined' ? process.env : {});
+        const security_key = options?.vars?.['security_key'] ?? generateSecurityKey();
+        const preRenderCtx = {
+            ...(options?.vars ?? {}), // make vars available as top-level template variables
+            documents: loaderDocs,
+            env,
+            agent: {
+                id: agent.id,
+                name: agent.name ?? agent.id,
+                role: agent.role ?? '',
+                team: agent.team ?? '',
+                description: agent.description ?? '',
+            },
+        };
+        const renderedPrompt = await this._templateEngine.render(rawPrompt, preRenderCtx);
+        // ── Step 4: Build full RenderContext ─────────────────────────────────────
+        const session = {
+            mode: options?.session?.mode ?? 'query',
+            platform: options?.session?.platform ?? 'cli',
+            options: options?.session?.options ?? [],
+        };
+        const providerRaw = agent.provider;
+        const providerList = Array.isArray(providerRaw)
+            ? providerRaw
+            : typeof providerRaw === 'string' && providerRaw.length > 0
+                ? [providerRaw]
+                : [];
+        const providerDisplay = providerList.join(', ') || (typeof providerRaw === 'string' ? providerRaw : '');
+        const agentOptions = agent.options;
+        const optionsByMode = !Array.isArray(agentOptions) && typeof agentOptions === 'object' && agentOptions !== null
+            ? agentOptions
+            : undefined;
+        const optionsArray = Array.isArray(agentOptions) ? agentOptions : undefined;
+        // Build document context for layout (with toc/path metadata)
+        const documents = {};
+        for (const [k, v] of Object.entries(loaderDocs)) {
+            documents[k] = {
+                content: v.content ?? '',
+                toc: v.toc,
+                summary: v.summary,
+                path: v.path,
+            };
+        }
+        // Extract user_input from vars for top-level access (default.yaml uses {{user_input}})
+        const userInputRaw = options?.vars?.['user_input'] ?? undefined;
+        const renderContext = {
+            user_input: userInputRaw,
+            agent: {
+                id: agent.id,
+                name: agent.name ?? agent.id,
+                role: agent.role ?? '',
+                team: agent.team ?? '',
+                description: agent.description ?? '',
+                provider: providerDisplay,
+                providerList,
+                model: agent.inline?.model,
+                workingDirectory: agent.working_directory ?? agent.workingDirectory ?? '.',
+                inline: {
+                    ...(agent.inline ?? {}),
+                    prompt: renderedPrompt, // pre-rendered (exec expanded)
+                },
+                specialties: agent.specialties ?? [],
+                capabilities: agent.capabilities ?? [],
+                remote: agent.remote ?? null,
+                optionsByMode,
+                optionsArray,
+            },
+            agentMetadata: {
+                specialties: agent.specialties ?? [],
+                capabilities: agent.capabilities ?? [],
+                description: agent.description ?? '',
+            },
+            documents,
+            skills: options?.skills ?? [],
+            session,
+            env,
+            vars: {
+                security_key,
+                ...(options?.vars ?? {}),
+            },
+            props: {
+                ...(layoutProps ?? {}),
+                // TRAP 2: auto-gate showConversationHistory when messages are present
+                ...(options?.messages && options.messages.length > 0
+                    ? { showConversationHistory: true }
+                    : {}),
+            },
+            platform: session.platform,
+            mode: session.mode,
+            messages: options?.messages ?? [],
+            tools: this._tools.size > 0
+                ? {
+                    list: Array.from(this._tools.values()).map(t => ({
+                        name: t.name,
+                        description: t.description,
+                        parameters: t.parameters,
+                    })),
+                    json: JSON.stringify(Array.from(this._tools.values()).map(t => ({
+                        name: t.name,
+                        description: t.description,
+                        parameters: t.parameters,
+                    })), null, 2),
+                    count: this._tools.size,
+                }
+                : null,
+            metadata: {},
+        };
+        // ── Step 5: Render layout ────────────────────────────────────────────────
+        return this._layoutRenderer.render(layout, renderContext);
+    }
+    // ── Private helpers ─────────────────────────────────────────────────────────
+    /**
+     * Filter tools by allowed names from agent options (query/execute mode).
+     * If allowedNames is undefined, return all registered tools.
+     */
+    _filterToolsByMode(allowedNames) {
+        if (!allowedNames) {
+            return Array.from(this._tools.values());
+        }
+        return allowedNames
+            .map(name => this._tools.get(name))
+            .filter((t) => t !== undefined);
+    }
+    /**
+     * Resolve layout spec following the priority order.
+     */
+    _resolveLayoutSpec(agent, callLayout) {
+        // Priority 1: call-site options
+        if (callLayout !== undefined)
+            return callLayout;
+        // Priority 2: agent.inline.layout
+        const inlineLayout = agent.inline?.layout;
+        if (inlineLayout !== undefined)
+            return inlineLayout;
+        // Priority 3: project config layouts.default
+        const projectDefault = this._config?.layouts?.['default'];
+        if (typeof projectDefault === 'string' && projectDefault)
+            return projectDefault;
+        // Priority 4: SDK built-in default
+        return 'crewx/default';
+    }
+    /** Extract the layout ID string from a LayoutSpec. */
+    _extractLayoutId(spec) {
+        if (typeof spec === 'string')
+            return spec;
+        if ('id' in spec)
+            return spec.id;
+        // Inline template — register it temporarily and return its ID
+        const tempId = `crewx/__inline_${Date.now()}`;
+        this._layoutLoader.registerLayout(tempId, spec.template);
+        return tempId;
+    }
+    /** Extract layout props overrides from agent inline.layout and call-site options. */
+    _extractLayoutProps(agent, _resolvedSpec, callLayout) {
+        // Props from agent.inline.layout
+        const inlineLayout = agent.inline?.layout;
+        const agentProps = inlineLayout && typeof inlineLayout === 'object' && 'props' in inlineLayout
+            ? inlineLayout.props
+            : undefined;
+        // Props from call-site options
+        const callProps = callLayout && typeof callLayout === 'object' && 'id' in callLayout
+            ? callLayout.props
+            : undefined;
+        // Merge: call-site overrides agent props
+        if (agentProps || callProps) {
+            return { ...(agentProps ?? {}), ...(callProps ?? {}) };
+        }
+        return undefined;
+    }
+    /**
+     * Get the ConversationPlugin's provider for history auto-fetch (WI-CONV-002).
+     * Returns undefined if no ConversationPlugin is registered.
+     */
+    _getConversationProvider() {
+        const plugin = this._plugins.find(p => p.name === 'conversation');
+        return plugin?.conversationProvider;
+    }
+    /**
+     * Auto-fetch conversation history and convert to TemplateMessage[] (WI-CONV-002).
+     * Returns undefined if no threadId, no provider, or fetch fails.
+     */
+    async _fetchHistoryMessages(threadId, traceId, callerMessages) {
+        // Caller-provided messages take priority
+        if (callerMessages && callerMessages.length > 0)
+            return callerMessages;
+        if (!threadId)
+            return undefined;
+        const provider = this._getConversationProvider();
+        if (!provider)
+            return undefined;
+        try {
+            const thread = await provider.fetchHistory(threadId, { currentTraceId: traceId });
+            if (thread.messages.length === 0)
+                return undefined;
+            return (0, to_template_messages_1.toTemplateMessages)(thread);
+        }
+        catch {
+            // Non-fatal: history fetch failure must not block the query/execute
+            return undefined;
+        }
+    }
+    emitToolEvents(traceId, agentRef, provider, line, agentId, threadId, sessionId) {
+        try {
+            const entries = (0, router_1.parseStdoutEvent)(new Date().toISOString(), line);
+            for (const entry of entries) {
+                if (entry.type === 'tool_use' && entry.toolName) {
+                    this.emit('tool:observed:before', {
+                        traceId,
+                        timestamp: new Date(),
+                        agentRef,
+                        agentId,
+                        threadId,
+                        sessionId,
+                        provider,
+                        tool: {
+                            name: entry.toolName,
+                            rawName: entry.toolName,
+                            input: entry.toolInput ? this.tryParseJson(entry.toolInput) : undefined,
+                            toolUseId: entry.toolUseId,
+                        },
+                    });
+                }
+                if (entry.type === 'tool_result') {
+                    this.emit('tool:observed:after', {
+                        traceId,
+                        timestamp: new Date(),
+                        agentRef,
+                        agentId,
+                        threadId,
+                        sessionId,
+                        provider,
+                        tool: {
+                            name: entry.toolName ?? 'unknown',
+                            rawName: entry.toolName ?? 'unknown',
+                            toolUseId: entry.toolUseId,
+                            result: entry.resultPreview,
+                            isError: entry.isError,
+                        },
+                    });
+                }
+            }
+        }
+        catch {
+            // non-fatal: parsing failure must not block the main process
+        }
+    }
+    tryParseJson(s) {
+        try {
+            return JSON.parse(s);
+        }
+        catch {
+            return s;
+        }
+    }
+    /**
+     * Query an agent with a message.
+     *
+     * Emits task:start (with child pid when available) then task:output per
+     * stdout/stderr line, then task:end on completion or error.
+     */
+    async query(agentRef, message, options) {
+        // file:// remote agents: delegate entirely to the target Crewx so execution
+        // runs inside the target workspace (same as `crewx q` invoked in that dir).
+        const remoteTarget = await this.resolveFileRemoteTarget(agentRef);
+        if (remoteTarget) {
+            return remoteTarget.target.query(remoteTarget.agentRef, message, options);
+        }
+        const startMs = Date.now();
+        const traceId = (0, id_1.generateId)('tsk');
+        const timestamp = new Date();
+        let agent;
+        try {
+            agent = (0, resolver_1.resolveAgent)(agentRef, Array.from(this._agents.values()));
+        }
+        catch (err) {
+            if (err instanceof resolver_1.AgentNotFoundError) {
+                this.emit('task:start', { traceId, timestamp, agentRef, message: message, mode: 'query', metadata: { ...(options?.metadata ?? {}) }, threadId: options?.threadId, platform: options?.platform ?? 'cli', workspaceId: this._workspaceId, workspaceName: this._workspaceName });
+                const durationMs = Date.now() - startMs;
+                const error = { code: 'AGENT_NOT_FOUND', message: err.message };
+                this.emit('task:end', { traceId, timestamp: new Date(), agentRef, mode: 'query', durationMs, error, metadata: options?.metadata ? { ...options.metadata } : undefined });
+                return {
+                    ok: false,
+                    data: '',
+                    error,
+                    meta: { agentId: agentRef.replace(/^@/, ''), provider: '', durationMs },
+                };
+            }
+            throw err;
+        }
+        const providerStr = Array.isArray(agent.provider)
+            ? agent.provider[0] ?? 'cli/claude'
+            : agent.provider;
+        const effectiveProviderStr = options?.provider ?? providerStr;
+        const effectiveModel = options?.model ?? agent.inline?.model;
+        let provider;
+        try {
+            provider = (0, bridge_1.createProvider)(effectiveProviderStr);
+        }
+        catch (err) {
+            this.emit('task:start', { traceId, timestamp, agentRef, message: message, mode: 'query', metadata: { ...(options?.metadata ?? {}) }, threadId: options?.threadId, platform: options?.platform ?? 'cli', workspaceId: this._workspaceId, workspaceName: this._workspaceName });
+            const durationMs = Date.now() - startMs;
+            const error = { code: 'PROVIDER_ERROR', message: err.message };
+            this.emit('task:end', { traceId, timestamp: new Date(), agentRef, mode: 'query', durationMs, error, metadata: options?.metadata ? { ...options.metadata } : undefined });
+            return {
+                ok: false,
+                data: '',
+                error,
+                meta: { agentId: agent.id, provider: effectiveProviderStr, model: effectiveModel, durationMs },
+            };
+        }
+        // WI-CONV-002: Auto-fetch conversation history for thread context injection
+        const historyMessages = await this._fetchHistoryMessages(options?.threadId, traceId, options?.messages);
+        // Render agent prompt with user_input for <user_query> wrapping (non-fatal if it fails)
+        // Intentionally includes user_input in renderedPrompt for tracing/logging purposes.
+        let renderedPrompt;
+        try {
+            renderedPrompt = await this.renderAgentPromptFull(agentRef, {
+                session: { mode: 'query', platform: options?.platform },
+                vars: { user_input: message },
+                messages: historyMessages,
+            });
+        }
+        catch {
+            // Prompt rendering is best-effort; do not block the query
+        }
+        let codingAgentCommand;
+        let providerUsage;
+        let exitCode;
+        let resolvedModel = effectiveModel;
+        let taskStartEmitted = false;
+        const emitStartIfNeeded = (pid) => {
+            if (!taskStartEmitted) {
+                taskStartEmitted = true;
+                this.emit('task:start', {
+                    traceId, timestamp, agentRef, message: message, mode: 'query', pid,
+                    model: resolvedModel,
+                    provider: effectiveProviderStr,
+                    codingAgentCommand,
+                    renderedPrompt,
+                    metadata: { ...(options?.metadata ?? {}), provider: effectiveProviderStr },
+                    threadId: options?.threadId,
+                    platform: options?.platform ?? 'cli',
+                    workspaceId: this._workspaceId,
+                    workspaceName: this._workspaceName,
+                });
+            }
+        };
+        const agentCliOpts = agent.options;
+        // Filter tools for query mode
+        const queryToolNames = Array.isArray(agentCliOpts?.query?.tools)
+            ? agentCliOpts.query.tools
+            : undefined;
+        const filteredTools = this._tools.size > 0
+            ? this._filterToolsByMode(queryToolNames)
+            : [];
+        // maxSteps from agent inline config
+        const maxSteps = agent.inline?.max_steps;
+        // api/* providers don't emit pid — emit task:start early so plugins (FileLogger) can log tool calls
+        if (effectiveProviderStr.startsWith('api/')) {
+            emitStartIfNeeded();
+        }
+        try {
+            const response = await provider.query(message, {
+                model: effectiveModel,
+                context: options?.context,
+                systemPrompt: renderedPrompt ?? agent.inline?.system_prompt ?? agent.inline?.prompt,
+                additionalArgs: Array.isArray(agentCliOpts?.query) ? agentCliOpts.query : undefined,
+                tools: filteredTools.length > 0 ? filteredTools : undefined,
+                maxSteps,
+                env: {
+                    CREWX_AGENT_ID: agent.id,
+                    CREWX_AGENT_ROLE: agent.role ?? '',
+                    CREWX_AGENT_TEAM: agent.team ?? '',
+                    CREWX_USER_ID: process.env.USER || process.env.USERNAME || 'unknown',
+                    CREWX_TRACE_ID: traceId,
+                    CREWX_PARENT_TASK_ID: traceId,
+                    CREWX_TASK_ID: traceId,
+                    CREWX_CALLER_AGENT_ID: process.env.CREWX_AGENT_ID ?? '',
+                    CREWX_THREAD_ID: options?.threadId ?? '',
+                    CREWX_PROVIDER: effectiveProviderStr,
+                    CREWX_SESSION_ID: '',
+                    CREWX_TASK_LOG_PATH: this.computeTaskLogPath(traceId, timestamp),
+                },
+                onPid: (pid) => emitStartIfNeeded(pid),
+                onOutput: (line, level) => {
+                    this.emit('task:output', { traceId, timestamp: new Date(), agentRef, output: line, level });
+                    if (level === 'stdout') {
+                        this.emitToolEvents(traceId, agentRef, effectiveProviderStr, line, agent.id, options?.threadId ?? '', '');
+                    }
+                },
+                onCommand: (cmd) => { codingAgentCommand = cmd; },
+                onUsage: (u) => { providerUsage = u; },
+                onExitCode: (code) => { exitCode = code; },
+                onModel: (m) => { if (!resolvedModel)
+                    resolvedModel = m; },
+            });
+            emitStartIfNeeded();
+            const durationMs = Date.now() - startMs;
+            this.emit('task:end', {
+                traceId, timestamp: new Date(), agentRef, mode: 'query', result: response, durationMs,
+                exitCode,
+                inputTokens: providerUsage?.inputTokens,
+                outputTokens: providerUsage?.outputTokens,
+                cachedInputTokens: providerUsage?.cachedInputTokens,
+                costUsd: providerUsage?.costUsd,
+                model: resolvedModel,
+                metadata: { ...(options?.metadata ?? {}), ...(options?.threadId ? { threadId: options.threadId } : {}) },
+            });
+            return {
+                ok: true,
+                data: response,
+                meta: { agentId: agent.id, provider: effectiveProviderStr, model: effectiveModel, durationMs },
+            };
+        }
+        catch (err) {
+            // Client tool call required — return requires_action with thread state
+            if (err instanceof bridge_1.ClientToolCallRequiredError) {
+                const threadId = (0, id_1.generateId)('thd');
+                this._pendingThreads.set(threadId, {
+                    agentRef: agent.id,
+                    providerStr: effectiveProviderStr,
+                    continuationState: err.continuationState,
+                    toolCall: err.toolCall,
+                    traceId,
+                    startMs,
+                    model: effectiveModel,
+                });
+                return {
+                    ok: true,
+                    status: 'requires_action',
+                    data: '',
+                    toolCall: err.toolCall,
+                    threadId,
+                    meta: { agentId: agent.id, provider: effectiveProviderStr, model: effectiveModel, durationMs: Date.now() - startMs },
+                };
+            }
+            emitStartIfNeeded();
+            const durationMs = Date.now() - startMs;
+            const error = { code: 'QUERY_FAILED', message: err.message };
+            this.emit('task:end', {
+                traceId, timestamp: new Date(), agentRef, mode: 'query', durationMs, error,
+                exitCode,
+                inputTokens: providerUsage?.inputTokens,
+                outputTokens: providerUsage?.outputTokens,
+                cachedInputTokens: providerUsage?.cachedInputTokens,
+                costUsd: providerUsage?.costUsd,
+                model: resolvedModel,
+                metadata: options?.metadata ? { ...options.metadata } : undefined,
+            });
+            return {
+                ok: false,
+                data: '',
+                error,
+                meta: { agentId: agent.id, provider: effectiveProviderStr, model: effectiveModel, durationMs },
+            };
+        }
+    }
+    /**
+     * Continue a conversation after providing client-side tool results.
+     *
+     * Called when a previous query() returned status: 'requires_action'.
+     * Feeds the tool result back to the agent and resumes generation.
+     * May return 'requires_action' again if the agent calls another client tool.
+     */
+    async continueQuery(threadId, toolResults) {
+        const state = this._pendingThreads.get(threadId);
+        if (!state) {
+            return {
+                ok: false,
+                data: '',
+                error: { code: 'THREAD_NOT_FOUND', message: `No pending thread: ${threadId}` },
+                meta: { agentId: '', provider: '', durationMs: 0 },
+            };
+        }
+        this._pendingThreads.delete(threadId);
+        const provider = (0, bridge_1.createProvider)(state.providerStr);
+        if (!provider.continueWithToolResults) {
+            return {
+                ok: false,
+                data: '',
+                error: { code: 'UNSUPPORTED', message: 'Provider does not support client tool continuation' },
+                meta: { agentId: state.agentRef, provider: state.providerStr, durationMs: 0 },
+            };
+        }
+        // Enrich toolResults with toolName (looked up from stored toolCall by toolCallId)
+        const enrichedToolResults = toolResults.map(tr => ({
+            ...tr,
+            toolName: state.toolCall.toolCallId === tr.toolCallId
+                ? state.toolCall.toolName
+                : tr.toolCallId,
+        }));
+        try {
+            const response = await provider.continueWithToolResults(state.continuationState, enrichedToolResults);
+            const durationMs = Date.now() - state.startMs;
+            this.emit('task:end', {
+                traceId: state.traceId, timestamp: new Date(), agentRef: state.agentRef,
+                mode: 'query', result: response, durationMs,
+            });
+            return {
+                ok: true,
+                status: 'complete',
+                data: response,
+                meta: { agentId: state.agentRef, provider: state.providerStr, model: state.model, durationMs },
+            };
+        }
+        catch (err) {
+            if (err instanceof bridge_1.ClientToolCallRequiredError) {
+                // Another client tool needed — re-store thread state
+                this._pendingThreads.set(threadId, {
+                    ...state,
+                    continuationState: err.continuationState,
+                    toolCall: err.toolCall,
+                });
+                return {
+                    ok: true,
+                    status: 'requires_action',
+                    data: '',
+                    toolCall: err.toolCall,
+                    threadId,
+                    meta: { agentId: state.agentRef, provider: state.providerStr, model: state.model, durationMs: Date.now() - state.startMs },
+                };
+            }
+            const durationMs = Date.now() - state.startMs;
+            return {
+                ok: false,
+                data: '',
+                error: { code: 'CONTINUE_FAILED', message: err.message },
+                meta: { agentId: state.agentRef, provider: state.providerStr, model: state.model, durationMs },
+            };
+        }
+    }
+    /**
+     * Execute a task with an agent.
+     *
+     * Emits task:start (with child pid when available) then task:output per
+     * stdout/stderr line, then task:end on completion or error.
+     */
+    async execute(agentRef, message, options) {
+        // file:// remote agents: delegate entirely to the target Crewx so execution
+        // runs inside the target workspace (same as `crewx x` invoked in that dir).
+        const remoteTarget = await this.resolveFileRemoteTarget(agentRef);
+        if (remoteTarget) {
+            return remoteTarget.target.execute(remoteTarget.agentRef, message, options);
+        }
+        const startMs = Date.now();
+        const traceId = (0, id_1.generateId)('tsk');
+        const timestamp = new Date();
+        let agent;
+        try {
+            agent = (0, resolver_1.resolveAgent)(agentRef, Array.from(this._agents.values()));
+        }
+        catch (err) {
+            if (err instanceof resolver_1.AgentNotFoundError) {
+                this.emit('task:start', { traceId, timestamp, agentRef, message: message, mode: 'execute', metadata: { ...(options?.metadata ?? {}) }, threadId: options?.threadId, platform: options?.platform ?? 'cli', workspaceId: this._workspaceId, workspaceName: this._workspaceName });
+                const durationMs = Date.now() - startMs;
+                const error = { code: 'AGENT_NOT_FOUND', message: err.message };
+                this.emit('task:end', { traceId, timestamp: new Date(), agentRef, mode: 'execute', durationMs, error, metadata: options?.metadata ? { ...options.metadata } : undefined });
+                return {
+                    ok: false,
+                    data: '',
+                    error,
+                    meta: { agentId: agentRef.replace(/^@/, ''), provider: '', durationMs },
+                };
+            }
+            throw err;
+        }
+        const providerStr = Array.isArray(agent.provider)
+            ? agent.provider[0] ?? 'cli/claude'
+            : agent.provider;
+        const effectiveProviderStr = options?.provider ?? providerStr;
+        const effectiveModel = options?.model ?? agent.inline?.model;
+        let provider;
+        try {
+            provider = (0, bridge_1.createProvider)(effectiveProviderStr);
+        }
+        catch (err) {
+            this.emit('task:start', { traceId, timestamp, agentRef, message: message, mode: 'execute', metadata: { ...(options?.metadata ?? {}) }, threadId: options?.threadId, platform: options?.platform ?? 'cli', workspaceId: this._workspaceId, workspaceName: this._workspaceName });
+            const durationMs = Date.now() - startMs;
+            const error = { code: 'PROVIDER_ERROR', message: err.message };
+            this.emit('task:end', { traceId, timestamp: new Date(), agentRef, mode: 'execute', durationMs, error, metadata: options?.metadata ? { ...options.metadata } : undefined });
+            return {
+                ok: false,
+                data: '',
+                error,
+                meta: { agentId: agent.id, provider: effectiveProviderStr, model: effectiveModel, durationMs },
+            };
+        }
+        // WI-CONV-002: Auto-fetch conversation history for thread context injection
+        const historyMessages = await this._fetchHistoryMessages(options?.threadId, traceId, options?.messages);
+        // Render agent prompt with user_input for <user_query> wrapping (non-fatal if it fails)
+        // Intentionally includes user_input in renderedPrompt for tracing/logging purposes.
+        let renderedPrompt;
+        try {
+            renderedPrompt = await this.renderAgentPromptFull(agentRef, {
+                session: { mode: 'execute', platform: options?.platform },
+                vars: { user_input: message },
+                messages: historyMessages,
+            });
+        }
+        catch {
+            // Prompt rendering is best-effort; do not block the execute
+        }
+        let codingAgentCommand;
+        let providerUsage;
+        let exitCode;
+        let resolvedModel = effectiveModel;
+        let taskStartEmitted = false;
+        const emitStartIfNeeded = (pid) => {
+            if (!taskStartEmitted) {
+                taskStartEmitted = true;
+                this.emit('task:start', {
+                    traceId, timestamp, agentRef, message: message, mode: 'execute', pid,
+                    model: resolvedModel,
+                    provider: effectiveProviderStr,
+                    codingAgentCommand,
+                    renderedPrompt,
+                    metadata: { ...(options?.metadata ?? {}), provider: effectiveProviderStr },
+                    threadId: options?.threadId,
+                    platform: options?.platform ?? 'cli',
+                    workspaceId: this._workspaceId,
+                    workspaceName: this._workspaceName,
+                });
+            }
+        };
+        const agentCliOpts = agent.options;
+        // Filter tools for execute mode
+        const executeToolNames = Array.isArray(agentCliOpts?.execute?.tools)
+            ? agentCliOpts.execute.tools
+            : undefined;
+        const filteredTools = this._tools.size > 0
+            ? this._filterToolsByMode(executeToolNames)
+            : [];
+        // maxSteps from agent inline config
+        const maxSteps = agent.inline?.max_steps;
+        // api/* providers don't emit pid — emit task:start early so plugins (FileLogger) can log tool calls
+        if (effectiveProviderStr.startsWith('api/')) {
+            emitStartIfNeeded();
+        }
+        try {
+            const response = await provider.execute(message, {
+                model: effectiveModel,
+                context: options?.context,
+                systemPrompt: renderedPrompt ?? agent.inline?.system_prompt ?? agent.inline?.prompt,
+                additionalArgs: Array.isArray(agentCliOpts?.execute) ? agentCliOpts.execute : undefined,
+                tools: filteredTools.length > 0 ? filteredTools : undefined,
+                maxSteps,
+                env: {
+                    CREWX_AGENT_ID: agent.id,
+                    CREWX_AGENT_ROLE: agent.role ?? '',
+                    CREWX_AGENT_TEAM: agent.team ?? '',
+                    CREWX_USER_ID: process.env.USER || process.env.USERNAME || 'unknown',
+                    CREWX_TRACE_ID: traceId,
+                    CREWX_PARENT_TASK_ID: traceId,
+                    CREWX_TASK_ID: traceId,
+                    CREWX_CALLER_AGENT_ID: process.env.CREWX_AGENT_ID ?? '',
+                    CREWX_THREAD_ID: options?.threadId ?? '',
+                    CREWX_PROVIDER: effectiveProviderStr,
+                    CREWX_SESSION_ID: '',
+                    CREWX_TASK_LOG_PATH: this.computeTaskLogPath(traceId, timestamp),
+                },
+                onPid: (pid) => emitStartIfNeeded(pid),
+                onOutput: (line, level) => {
+                    this.emit('task:output', { traceId, timestamp: new Date(), agentRef, output: line, level });
+                    if (level === 'stdout') {
+                        this.emitToolEvents(traceId, agentRef, effectiveProviderStr, line, agent.id, options?.threadId ?? '', '');
+                    }
+                },
+                onCommand: (cmd) => { codingAgentCommand = cmd; },
+                onUsage: (u) => { providerUsage = u; },
+                onExitCode: (code) => { exitCode = code; },
+                onModel: (m) => { if (!resolvedModel)
+                    resolvedModel = m; },
+            });
+            emitStartIfNeeded();
+            const durationMs = Date.now() - startMs;
+            this.emit('task:end', {
+                traceId, timestamp: new Date(), agentRef, mode: 'execute', result: response, durationMs,
+                exitCode,
+                inputTokens: providerUsage?.inputTokens,
+                outputTokens: providerUsage?.outputTokens,
+                cachedInputTokens: providerUsage?.cachedInputTokens,
+                costUsd: providerUsage?.costUsd,
+                model: resolvedModel,
+                metadata: { ...(options?.metadata ?? {}), ...(options?.threadId ? { threadId: options.threadId } : {}) },
+            });
+            return {
+                ok: true,
+                data: response,
+                meta: { agentId: agent.id, provider: effectiveProviderStr, model: effectiveModel, durationMs },
+            };
+        }
+        catch (err) {
+            emitStartIfNeeded();
+            const durationMs = Date.now() - startMs;
+            const error = { code: 'EXECUTE_FAILED', message: err.message };
+            this.emit('task:end', {
+                traceId, timestamp: new Date(), agentRef, mode: 'execute', durationMs, error,
+                exitCode,
+                inputTokens: providerUsage?.inputTokens,
+                outputTokens: providerUsage?.outputTokens,
+                cachedInputTokens: providerUsage?.cachedInputTokens,
+                costUsd: providerUsage?.costUsd,
+                model: resolvedModel,
+                metadata: options?.metadata ? { ...options.metadata } : undefined,
+            });
+            return {
+                ok: false,
+                data: '',
+                error,
+                meta: { agentId: agent.id, provider: effectiveProviderStr, model: effectiveModel, durationMs },
+            };
+        }
+    }
+}
+exports.Crewx = Crewx;
+// ── Module-level helper ─────────────────────────────────────────────────────
+/**
+ * Auto-register the `remote` provider factory if any agent uses `remote/*` namespace.
+ * Reads remote provider configs from crewx.yaml `providers:` section.
+ */
+function registerRemoteProvidersIfNeeded(agents, config) {
+    const hasRemoteProvider = agents.some(a => {
+        const providers = Array.isArray(a.provider) ? a.provider : [a.provider];
+        return providers.some(p => p.startsWith('remote/'));
+    });
+    if (!hasRemoteProvider)
+        return;
+    // Read remote provider configs from crewx.yaml `providers:` array
+    const providersRaw = config.providers;
+    if (!Array.isArray(providersRaw))
+        return;
+    const { createRemoteProviderFactory } = require('../remote/remote-provider.js');
+    const remoteConfigs = new Map();
+    for (const entry of providersRaw) {
+        if (entry.type === 'remote' && typeof entry.id === 'string') {
+            remoteConfigs.set(entry.id, entry);
+        }
+    }
+    if (remoteConfigs.size > 0) {
+        (0, bridge_1.registerProviderFactory)('remote', createRemoteProviderFactory(remoteConfigs, bridge_1.createProvider));
+    }
+}
+/**
+ * Auto-register the `plugin` provider factory if any agent uses `plugin/*` namespace.
+ * Reads plugin provider configs from crewx.yaml `providers:` section.
+ */
+function registerPluginProvidersIfNeeded(agents, config) {
+    const hasPluginProvider = agents.some(a => {
+        const providers = Array.isArray(a.provider) ? a.provider : [a.provider];
+        return providers.some(p => p.startsWith('plugin/'));
+    });
+    if (!hasPluginProvider)
+        return;
+    const providersRaw = config.providers;
+    if (!Array.isArray(providersRaw))
+        return;
+    const { createPluginProviderFactory } = require('../plugin/plugin-provider.js');
+    const pluginConfigs = new Map();
+    for (const entry of providersRaw) {
+        if (entry.type === 'plugin' && typeof entry.id === 'string') {
+            pluginConfigs.set(entry.id, entry);
+        }
+    }
+    if (pluginConfigs.size > 0) {
+        (0, bridge_1.registerProviderFactory)('plugin', createPluginProviderFactory(pluginConfigs));
+    }
+}
+//# sourceMappingURL=Crewx.js.map