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

package/dist/esm/facade/Crewx.js

@@ -0,0 +1,941 @@
+/**
+ * Crewx facade — main entry point for the CrewX SDK.
+ * Provides loadYaml(), fromConfig(), query(), execute(), renderAgentPromptFull(),
+ * and registerLayout() methods.
+ */
+import { dirname, join } from 'path';
+import { matchesPattern } from '../utils/glob-match';
+import { loadYamlFile } from '../config/loader';
+import { resolveAgent, AgentNotFoundError } from '../agent/resolver';
+import { createProvider, ClientToolCallRequiredError, registerProviderFactory } from '../provider/bridge';
+import { TemplateEngine } from '../template/engine';
+import { DocumentLoader } from '../template/loader/DocumentLoader';
+import { LayoutLoader } from '../layout/loader';
+import { LayoutRenderer } from '../layout/renderer';
+import { generateId } from '../utils/id';
+import { TypedEventEmitter } from '../events/TypedEventEmitter';
+import { parseStdoutEvent } from '../parsers/router';
+import { createHandler } from '../server/handler';
+/**
+ * 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 = join(__dirname, '../../templates/agents');
+export class Crewx extends TypedEventEmitter {
+    _agents;
+    _templateEngine;
+    _documentLoader;
+    _layoutLoader;
+    _layoutRenderer;
+    _config;
+    _plugins = [];
+    _tools = new Map();
+    _pendingThreads = new Map();
+    constructor(agents, options = {}, config, documentLoader) {
+        super();
+        this._agents = new Map(agents.map(a => [a.id, a]));
+        this._config = config;
+        const settingsPolicy = extractExecPolicyFromConfig(config);
+        this._templateEngine = new TemplateEngine({
+            execPolicy: options.execPolicy ?? settingsPolicy,
+        });
+        this._documentLoader = documentLoader ?? new DocumentLoader();
+        this._layoutLoader = new LayoutLoader({ templatesPath: SDK_TEMPLATES_PATH });
+        this._layoutRenderer = new LayoutRenderer();
+    }
+    /**
+     * Load crewx.yaml from the given file path and create a Crewx instance.
+     */
+    static async loadYaml(path, options, fsAdapter) {
+        const config = loadYamlFile(path);
+        const projectRoot = dirname(path);
+        const loader = new 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 import('../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);
+        return new Crewx(agents, options ?? {}, config, loader);
+    }
+    /**
+     * Create a Crewx instance from an already-parsed config object.
+     */
+    static async fromConfig(config, options, projectRoot, fsAdapter) {
+        const loader = new 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);
+        return new Crewx(config.agents ?? [], options ?? {}, config, loader);
+    }
+    /** 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;
+    }
+    /**
+     * 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 createHandler(this, options);
+    }
+    /**
+     * Detach all plugins in LIFO order and release resources.
+     * Call before process exit for clean shutdown.
+     */
+    async close() {
+        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 => matchesPattern(a.role.toLowerCase(), f)));
+        }
+        if (teamFilter) {
+            result = result.filter(a => a.team && teamFilter.some(f => 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 => 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 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 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 },
+        };
+        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,
+            };
+        }
+        const renderContext = {
+            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 ?? {},
+            platform: session.platform,
+            mode: session.mode,
+            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;
+    }
+    emitToolEvents(traceId, agentRef, provider, line, agentId, threadId, sessionId) {
+        try {
+            const entries = 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) {
+        const startMs = Date.now();
+        const traceId = generateId('tsk');
+        const timestamp = new Date();
+        let agent;
+        try {
+            agent = resolveAgent(agentRef, Array.from(this._agents.values()));
+        }
+        catch (err) {
+            if (err instanceof AgentNotFoundError) {
+                this.emit('task:start', { traceId, timestamp, agentRef, message: message, mode: 'query', metadata: { ...(options?.metadata ?? {}) } });
+                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 = createProvider(effectiveProviderStr);
+        }
+        catch (err) {
+            this.emit('task:start', { traceId, timestamp, agentRef, message: message, mode: 'query', metadata: { ...(options?.metadata ?? {}) } });
+            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 },
+            };
+        }
+        // Render agent prompt for tracing (non-fatal if it fails)
+        let renderedPrompt;
+        try {
+            renderedPrompt = await this.renderAgentPromptFull(agentRef, { session: { mode: 'query' } });
+        }
+        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,
+                });
+            }
+        };
+        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_USER_ID: process.env.USER || process.env.USERNAME || 'unknown',
+                    CREWX_TRACE_ID: traceId,
+                    CREWX_PARENT_TASK_ID: traceId,
+                    CREWX_CALLER_AGENT_ID: process.env.CREWX_AGENT_ID ?? '',
+                    CREWX_THREAD_ID: options?.threadId ?? '',
+                    CREWX_PROVIDER: effectiveProviderStr,
+                    CREWX_SESSION_ID: '',
+                },
+                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.metadata } : undefined,
+            });
+            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 ClientToolCallRequiredError) {
+                const threadId = 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 = 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 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) {
+        const startMs = Date.now();
+        const traceId = generateId('tsk');
+        const timestamp = new Date();
+        let agent;
+        try {
+            agent = resolveAgent(agentRef, Array.from(this._agents.values()));
+        }
+        catch (err) {
+            if (err instanceof AgentNotFoundError) {
+                this.emit('task:start', { traceId, timestamp, agentRef, message: message, mode: 'execute', metadata: { ...(options?.metadata ?? {}) } });
+                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 = createProvider(effectiveProviderStr);
+        }
+        catch (err) {
+            this.emit('task:start', { traceId, timestamp, agentRef, message: message, mode: 'execute', metadata: { ...(options?.metadata ?? {}) } });
+            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 },
+            };
+        }
+        // Render agent prompt for tracing (non-fatal if it fails)
+        let renderedPrompt;
+        try {
+            renderedPrompt = await this.renderAgentPromptFull(agentRef, { session: { mode: 'execute' } });
+        }
+        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,
+                });
+            }
+        };
+        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_USER_ID: process.env.USER || process.env.USERNAME || 'unknown',
+                    CREWX_TRACE_ID: traceId,
+                    CREWX_PARENT_TASK_ID: traceId,
+                    CREWX_CALLER_AGENT_ID: process.env.CREWX_AGENT_ID ?? '',
+                    CREWX_THREAD_ID: options?.threadId ?? '',
+                    CREWX_PROVIDER: effectiveProviderStr,
+                    CREWX_SESSION_ID: '',
+                },
+                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.metadata } : undefined,
+            });
+            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 },
+            };
+        }
+    }
+}
+// ── 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) {
+        registerProviderFactory('remote', createRemoteProviderFactory(remoteConfigs));
+    }
+}
+/**
+ * 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) {
+        registerProviderFactory('plugin', createPluginProviderFactory(pluginConfigs));
+    }
+}
+//# sourceMappingURL=Crewx.js.map