@vybestack/llxprt-code-agents 0.10.0-nightly.260613.1adad3b34

package/dist/src/tools/task.js

@@ -0,0 +1,932 @@
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/* eslint-disable complexity, max-lines -- Phase 5: legacy core boundary retained while larger decomposition continues. */
+import { BaseDeclarativeTool, BaseToolInvocation, Kind, } from '@vybestack/llxprt-code-tools';
+import { SubagentOrchestrator, } from '../core/subagentOrchestrator.js';
+import { ContextState, SubagentTerminateMode, } from '@vybestack/llxprt-code-core/core/subagentTypes.js';
+import { ToolErrorType } from '@vybestack/llxprt-code-tools';
+import { DEFAULT_AGENT_ID } from '@vybestack/llxprt-code-core/core/turn.js';
+import { DebugLogger } from '@vybestack/llxprt-code-core/debug/DebugLogger.js';
+import { canonicalizeToolName, buildToolGovernance, isToolBlocked, } from '../core/toolGovernance.js';
+const taskLogger = new DebugLogger('llxprt:task');
+// Tool timeout settings (Issue #1049)
+const DEFAULT_TASK_TIMEOUT_SECONDS = 900;
+const MAX_TASK_TIMEOUT_SECONDS = 1800;
+const normalizeToolNameForPolicy = (name) => canonicalizeToolName(name);
+function normalizeSubagentStreamingText(text) {
+    if (!text) {
+        return '';
+    }
+    const lf = text.replace(/\r\n?/g, '\n');
+    return lf.endsWith('\n') ? lf : lf + '\n';
+}
+function launchRequestName(launchResult) {
+    return launchResult.config.name;
+}
+/**
+ * Formats a human readable summary for successful subagent execution.
+ */
+function formatSuccessDisplay(subagentName, agentId, output) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- BN4-C-P01: preserve defensive runtime boundary guard despite current static types.
+    const emittedVars = Object.entries(output.emitted_vars ?? {});
+    const finalMessageSection = output.final_message
+        ? `Final message:\n${output.final_message}`
+        : 'Final message: _(none)_';
+    const emittedSection = emittedVars.length === 0
+        ? 'Emitted variables: _(none)_'
+        : `Emitted variables:\n${emittedVars
+            .map(([key, value]) => `- **${key}**: ${value}`)
+            .join('\n')}`;
+    return [
+        `Subagent **${subagentName}** (\`${agentId}\`) completed with status \`${output.terminate_reason}\`.`,
+        finalMessageSection,
+        emittedSection,
+    ].join('\n\n');
+}
+/**
+ * Summarizes the subagent output as JSON for inclusion in tool history.
+ */
+function formatSuccessContent(agentId, output) {
+    const payload = {
+        agent_id: agentId,
+        terminate_reason: output.terminate_reason,
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- BN4-C-P01: preserve defensive runtime boundary guard despite current static types.
+        emitted_vars: output.emitted_vars ?? {},
+    };
+    if (output.final_message !== undefined) {
+        payload.final_message = output.final_message;
+    }
+    return JSON.stringify(payload, null, 2);
+}
+class TaskToolInvocation extends BaseToolInvocation {
+    config;
+    normalized;
+    deps;
+    constructor(config, params, normalized, deps, messageBus) {
+        super(params, messageBus);
+        this.config = config;
+        this.normalized = normalized;
+        this.deps = deps;
+    }
+    getDescription() {
+        return `Run subagent '${this.normalized.subagentName}' to accomplish: ${this.normalized.goalPrompt}`;
+    }
+    buildExcludedToolNames() {
+        return new Set(['task', 'list_subagents']
+            .map((name) => normalizeToolNameForPolicy(name))
+            .filter((name) => name.length > 0));
+    }
+    isExcludedToolName(name, excluded) {
+        const canonical = normalizeToolNameForPolicy(name);
+        return canonical.length > 0 && excluded.has(canonical);
+    }
+    buildGovernedToolWhitelist(candidateTools, registry) {
+        if (!candidateTools || candidateTools.length === 0) {
+            return undefined;
+        }
+        const excluded = this.buildExcludedToolNames();
+        const governance = buildToolGovernance(this.config);
+        const allowedRegistryTools = registry
+            .getEnabledTools()
+            .map((tool) => tool.name)
+            .filter((name) => !!name && !this.isExcludedToolName(name, excluded));
+        const allowedByCanonical = new Map();
+        for (const toolName of allowedRegistryTools) {
+            const canonical = normalizeToolNameForPolicy(toolName);
+            if (canonical && !allowedByCanonical.has(canonical)) {
+                allowedByCanonical.set(canonical, toolName);
+            }
+        }
+        const filteredTools = candidateTools.map((name) => {
+            if (!name || this.isExcludedToolName(name, excluded)) {
+                return undefined;
+            }
+            const canonical = normalizeToolNameForPolicy(name);
+            if (!canonical || isToolBlocked(canonical, governance)) {
+                return undefined;
+            }
+            return allowedByCanonical.get(canonical);
+        });
+        const validTools = filteredTools.filter((name) => typeof name === 'string' && name.length > 0);
+        if (validTools.length === 0) {
+            return undefined;
+        }
+        const uniqueByCanonical = new Set();
+        const deduped = [];
+        for (const tool of validTools) {
+            const canonical = normalizeToolNameForPolicy(tool);
+            if (!canonical || uniqueByCanonical.has(canonical)) {
+                continue;
+            }
+            uniqueByCanonical.add(canonical);
+            deduped.push(tool);
+        }
+        return deduped.length > 0 ? deduped : undefined;
+    }
+    createLaunchRequest(timeoutMs) {
+        const { subagentName, behaviourPrompts, toolWhitelist, outputSpec } = this.normalized;
+        const launchRequest = {
+            name: subagentName,
+        };
+        if (timeoutMs !== undefined) {
+            launchRequest.runConfig = {
+                max_time_minutes: timeoutMs / 60_000,
+            };
+        }
+        if (this.params.grace_period_seconds !== undefined) {
+            launchRequest.runConfig = {
+                max_time_minutes: launchRequest.runConfig?.max_time_minutes ?? Number.POSITIVE_INFINITY,
+                grace_period_seconds: this.params.grace_period_seconds,
+            };
+        }
+        if (behaviourPrompts.length > 0) {
+            launchRequest.behaviourPrompts = behaviourPrompts;
+        }
+        const registry = this.deps.getToolRegistry?.();
+        let effectiveWhitelist = toolWhitelist;
+        const hasExplicitWhitelist = Array.isArray(this.params.tool_whitelist) ||
+            Array.isArray(this.params.toolWhitelist);
+        if (registry) {
+            if (effectiveWhitelist && effectiveWhitelist.length > 0) {
+                effectiveWhitelist = this.buildGovernedToolWhitelist(effectiveWhitelist, registry);
+            }
+            if (!hasExplicitWhitelist &&
+                (!effectiveWhitelist || effectiveWhitelist.length === 0)) {
+                effectiveWhitelist = this.buildGovernedToolWhitelist(registry.getEnabledTools().map((tool) => tool.name), registry);
+            }
+        }
+        if (effectiveWhitelist && effectiveWhitelist.length > 0) {
+            const whitelistSet = new Set(effectiveWhitelist.filter((name) => Boolean(name)));
+            launchRequest.toolConfig = {
+                tools: Array.from(whitelistSet),
+            };
+        }
+        taskLogger.debug(() => {
+            const summary = launchRequest.toolConfig?.tools &&
+                launchRequest.toolConfig.tools.length > 0
+                ? `${launchRequest.toolConfig.tools.length} tools`
+                : 'no tools provided';
+            return `Prepared launch request for '${subagentName}': toolConfig=${summary}`;
+        });
+        if (outputSpec && Object.keys(outputSpec).length > 0) {
+            launchRequest.outputConfig = {
+                outputs: outputSpec,
+            };
+        }
+        return launchRequest;
+    }
+    async execute(signal, updateOutput) {
+        if (this.normalized.async) {
+            return this.executeAsync(signal, updateOutput);
+        }
+        const { timeoutMs, timeoutSeconds, timeoutController, timeoutId, onUserAbort, } = this.createTimeoutControllers(signal);
+        if (signal.aborted) {
+            onUserAbort();
+            signal.removeEventListener('abort', onUserAbort);
+            if (timeoutId !== null) {
+                clearTimeout(timeoutId);
+            }
+            return this.createCancelledResult('Task execution aborted before launch.');
+        }
+        let orchestrator;
+        try {
+            orchestrator = this.deps.createOrchestrator();
+        }
+        catch (error) {
+            taskLogger.warn(() => `Failed to create orchestrator for '${this.normalized.subagentName}': ${error instanceof Error ? error.message : String(error)}`);
+            signal.removeEventListener('abort', onUserAbort);
+            if (timeoutId !== null) {
+                clearTimeout(timeoutId);
+            }
+            return this.createErrorResult(error, 'Task tool could not initialize subagent orchestrator.');
+        }
+        const launchRequest = this.createLaunchRequest(timeoutMs);
+        taskLogger.debug(() => `Launching subagent '${launchRequest.name}'`);
+        const abortResult = await this.launchSubagent(orchestrator, launchRequest, signal, timeoutController, timeoutSeconds, onUserAbort, timeoutId, updateOutput);
+        return abortResult;
+    }
+    async launchSubagent(orchestrator, launchRequest, signal, timeoutController, timeoutSeconds, onUserAbort, timeoutId, updateOutput) {
+        const abortState = this.createAbortState(launchRequest, signal);
+        signal.addEventListener('abort', abortState.abortHandler, { once: true });
+        if (signal.aborted) {
+            abortState.abortHandler();
+            abortState.removeAbortHandler();
+            signal.removeEventListener('abort', onUserAbort);
+            if (timeoutId !== null) {
+                clearTimeout(timeoutId);
+            }
+            return this.createCancelledResult('Task execution aborted before launch.');
+        }
+        const launchResult = await this.attemptLaunch(orchestrator, launchRequest, signal, timeoutController, timeoutSeconds, onUserAbort, timeoutId, abortState);
+        if (launchResult === null) {
+            if (this.lastLaunchError !== undefined) {
+                const error = this.lastLaunchError;
+                this.lastLaunchError = undefined;
+                return this.createErrorResult(error, `Unable to launch subagent '${this.normalized.subagentName}'.`);
+            }
+            if (abortState.aborted.timedOut) {
+                return this.createTimeoutResult(timeoutSeconds);
+            }
+            return this.createCancelledResult('Task aborted during launch.');
+        }
+        return this.runSubagentExecution(launchResult, signal, timeoutController, timeoutSeconds, onUserAbort, timeoutId, abortState, updateOutput);
+    }
+    createAbortState(launchRequest, signal) {
+        const state = { aborted: false, timedOut: false };
+        let liveScope;
+        const abortHandler = () => {
+            if (state.aborted)
+                return;
+            state.aborted = true;
+            taskLogger.warn(() => `Cancellation requested for subagent '${launchRequest.name}'`);
+            try {
+                const candidate = liveScope?.scope;
+                candidate?.cancel?.('User aborted task execution.');
+            }
+            catch (error) {
+                taskLogger.warn(() => `Error while cancelling subagent '${launchRequest.name}': ${error instanceof Error ? error.message : String(error)}`);
+            }
+        };
+        const removeAbortHandler = () => {
+            signal.removeEventListener('abort', abortHandler);
+        };
+        const setLaunchResult = (result) => {
+            liveScope = result;
+        };
+        return {
+            aborted: state,
+            abortHandler,
+            removeAbortHandler,
+            setLaunchResult,
+        };
+    }
+    async attemptLaunch(orchestrator, launchRequest, signal, timeoutController, timeoutSeconds, onUserAbort, timeoutId, abortState) {
+        let launchResult;
+        try {
+            launchResult = await orchestrator.launch(launchRequest, timeoutController.signal);
+            abortState.setLaunchResult(launchResult);
+            return launchResult;
+        }
+        catch (error) {
+            abortState.removeAbortHandler();
+            signal.removeEventListener('abort', onUserAbort);
+            if (timeoutId !== null) {
+                clearTimeout(timeoutId);
+            }
+            if (this.isTimeoutError(signal, timeoutController, error)) {
+                abortState.aborted.timedOut = true;
+                return null;
+            }
+            if (this.isAbortError(error) ||
+                abortState.aborted.aborted ||
+                signal.aborted) {
+                return null;
+            }
+            taskLogger.warn(() => `Launch failure for '${launchRequest.name}': ${error instanceof Error ? error.message : String(error)}`);
+            this.lastLaunchError = error;
+            return null;
+        }
+    }
+    lastLaunchError = undefined;
+    async runSubagentExecution(launchResult, signal, timeoutController, timeoutSeconds, onUserAbort, timeoutId, abortState, updateOutput) {
+        const { scope, agentId, dispose } = launchResult;
+        taskLogger.debug(() => `Subagent '${launchRequestName(launchResult)}' started with agentId=${agentId}`);
+        const contextState = this.buildContextState();
+        const teardown = this.buildTeardown(dispose, abortState.removeAbortHandler, signal, onUserAbort, timeoutId);
+        if (signal.aborted || abortState.aborted.aborted) {
+            await teardown();
+            return this.createCancelledResult('Task aborted during launch.', agentId, scope.output);
+        }
+        const { emitClosingSubagentTag } = this.setupStreaming(launchResult, agentId, scope, updateOutput);
+        try {
+            await this.runSubagent(scope, contextState);
+            return await this.handleExecutionResult(scope, agentId, signal, timeoutController, timeoutSeconds, teardown, abortState.aborted);
+        }
+        catch (error) {
+            return await this.handleExecutionError(error, signal, timeoutController, timeoutSeconds, agentId, scope, teardown, abortState.aborted);
+        }
+        finally {
+            emitClosingSubagentTag();
+        }
+    }
+    buildTeardown(dispose, removeAbortHandler, signal, onUserAbort, timeoutId) {
+        return async () => {
+            removeAbortHandler();
+            signal.removeEventListener('abort', onUserAbort);
+            if (timeoutId !== null) {
+                clearTimeout(timeoutId);
+            }
+            try {
+                await dispose();
+            }
+            catch {
+                // Swallow dispose errors to avoid masking primary error.
+            }
+        };
+    }
+    setupStreaming(launchResult, agentId, scope, updateOutput) {
+        const subagentName = launchRequestName(launchResult) || this.normalized.subagentName;
+        let xmlOutputOpen = false;
+        const emitClosingSubagentTag = () => {
+            if (!xmlOutputOpen || !updateOutput) {
+                return;
+            }
+            updateOutput(`</subagent name="${subagentName}" id="${agentId}">\n`);
+            xmlOutputOpen = false;
+        };
+        if (updateOutput) {
+            updateOutput(`<subagent name="${subagentName}" id="${agentId}">\n`);
+            xmlOutputOpen = true;
+            const existingHandler = scope.onMessage;
+            scope.onMessage = (message) => {
+                const cleaned = normalizeSubagentStreamingText(message);
+                if (cleaned.trim().length > 0) {
+                    updateOutput(cleaned);
+                }
+                existingHandler?.(message);
+            };
+        }
+        return { emitClosingSubagentTag };
+    }
+    async runSubagent(scope, contextState) {
+        const environmentInteractive = this.deps.isInteractiveEnvironment?.() ?? true;
+        if (environmentInteractive && typeof scope.runInteractive === 'function') {
+            const schedulerFactory = this.deps.getSchedulerFactory?.();
+            const interactiveOptions = schedulerFactory
+                ? { schedulerFactory }
+                : undefined;
+            await scope.runInteractive(contextState, interactiveOptions);
+        }
+        else {
+            await scope.runNonInteractive(contextState);
+        }
+    }
+    async handleExecutionError(error, signal, timeoutController, timeoutSeconds, agentId, scope, teardown, abortedState) {
+        if (this.isTimeoutError(signal, timeoutController, error)) {
+            await teardown();
+            return this.createTimeoutResult(timeoutSeconds, scope.output, agentId);
+        }
+        if (this.isAbortError(error) || abortedState.aborted || signal.aborted) {
+            await teardown();
+            return this.createCancelledResult('Task execution aborted before completion.', agentId, scope.output);
+        }
+        const result = this.createErrorResult(error, `Subagent '${this.normalized.subagentName}' failed during execution.`, agentId);
+        await teardown();
+        taskLogger.warn(() => `Subagent execution error: ${result.error?.message ?? 'unknown'}`);
+        return result;
+    }
+    async handleExecutionResult(scope, agentId, signal, timeoutController, timeoutSeconds, teardown, abortedState) {
+        if (abortedState.aborted) {
+            await teardown();
+            taskLogger.warn(() => `Subagent aborted before completion`);
+            return this.createCancelledResult('Task execution aborted before completion.', agentId, scope.output);
+        }
+        if (this.isTimeoutError(signal, timeoutController)) {
+            await teardown();
+            return this.createTimeoutResult(timeoutSeconds, scope.output);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- BN4-C-P01: preserve defensive runtime boundary guard despite current static types.
+        const output = scope.output ?? {
+            terminate_reason: SubagentTerminateMode.ERROR,
+            emitted_vars: {},
+        };
+        taskLogger.debug(() => 
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- BN4-C-P01: preserve defensive runtime boundary guard despite current static types.
+        `Subagent finished with reason=${output.terminate_reason} emittedKeys=${Object.keys(output.emitted_vars ?? {}).join(', ')}`);
+        const llmContent = formatSuccessContent(agentId, output);
+        const returnDisplay = formatSuccessDisplay(this.normalized.subagentName, agentId, output);
+        await teardown();
+        return {
+            llmContent,
+            returnDisplay,
+            metadata: {
+                agentId,
+                terminateReason: output.terminate_reason,
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- BN4-C-P01: preserve defensive runtime boundary guard despite current static types.
+                emittedVars: output.emitted_vars ?? {},
+                ...(output.final_message ? { finalMessage: output.final_message } : {}),
+            },
+        };
+    }
+    isAbortError(error) {
+        if (error === null || error === undefined || typeof error !== 'object') {
+            return false;
+        }
+        const result = error.name === 'AbortError';
+        return result;
+    }
+    buildContextState() {
+        const context = new ContextState();
+        context.set('task_goal', this.normalized.goalPrompt);
+        context.set('task_name', this.normalized.subagentName);
+        const sessionId = this.config.getSessionId();
+        if (sessionId.length > 0) {
+            context.set('sessionId', sessionId);
+        }
+        for (const [key, value] of Object.entries(this.normalized.context)) {
+            context.set(key, value);
+        }
+        context.set('task_behaviour_prompts', [
+            ...this.normalized.behaviourPrompts,
+        ]);
+        return context;
+    }
+    createErrorResult(error, fallbackMessage, agentId) {
+        const detail = error instanceof Error && error.message ? error.message : null;
+        const displayMessage = detail
+            ? `${fallbackMessage}\nDetails: ${detail}`
+            : fallbackMessage;
+        const message = detail ?? fallbackMessage;
+        taskLogger.warn(() => `Task tool error: ${displayMessage}`);
+        return {
+            llmContent: displayMessage,
+            returnDisplay: displayMessage,
+            metadata: agentId
+                ? {
+                    agentId,
+                    error: message,
+                }
+                : undefined,
+            error: {
+                message,
+                type: ToolErrorType.UNHANDLED_EXCEPTION,
+            },
+        };
+    }
+    createCancelledResult(message, agentId, output) {
+        taskLogger.warn(() => `Task tool cancelled for agentId=${agentId ?? DEFAULT_AGENT_ID}: ${message}`);
+        return {
+            llmContent: message,
+            returnDisplay: message,
+            metadata: {
+                agentId: agentId ?? DEFAULT_AGENT_ID,
+                terminateReason: output?.terminate_reason,
+                emittedVars: output?.emitted_vars ?? {},
+                ...(output?.final_message
+                    ? { finalMessage: output.final_message }
+                    : {}),
+                cancelled: true,
+            },
+            error: {
+                message,
+                type: ToolErrorType.EXECUTION_FAILED,
+            },
+        };
+    }
+    createTimeoutControllers(signal) {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- BN4-C-P01: preserve defensive runtime boundary guard despite current static types.
+        const settings = this.config.getEphemeralSettings?.() ?? {};
+        const defaultTimeoutSeconds = settings['task-default-timeout-seconds'] ??
+            DEFAULT_TASK_TIMEOUT_SECONDS;
+        const maxTimeoutSeconds = settings['task-max-timeout-seconds'] ??
+            MAX_TASK_TIMEOUT_SECONDS;
+        const timeoutSeconds = this.resolveTimeoutSeconds(this.params.timeout_seconds, defaultTimeoutSeconds, maxTimeoutSeconds);
+        // Convert seconds to milliseconds for setTimeout
+        const timeoutMs = timeoutSeconds === undefined ? undefined : timeoutSeconds * 1000;
+        const timeoutController = new AbortController();
+        const timeoutId = timeoutMs === undefined
+            ? null
+            : setTimeout(() => timeoutController.abort(), timeoutMs);
+        const onUserAbort = () => {
+            if (timeoutId !== null) {
+                clearTimeout(timeoutId);
+            }
+            timeoutController.abort();
+        };
+        signal.addEventListener('abort', onUserAbort, { once: true });
+        return {
+            timeoutMs,
+            timeoutSeconds,
+            timeoutController,
+            timeoutId,
+            onUserAbort,
+        };
+    }
+    resolveTimeoutSeconds(requestedTimeoutSeconds, defaultTimeoutSeconds, maxTimeoutSeconds) {
+        if (requestedTimeoutSeconds === -1 || defaultTimeoutSeconds === -1) {
+            return undefined;
+        }
+        const effectiveTimeout = requestedTimeoutSeconds ?? defaultTimeoutSeconds;
+        if (maxTimeoutSeconds === -1) {
+            return effectiveTimeout;
+        }
+        if (effectiveTimeout > maxTimeoutSeconds) {
+            return maxTimeoutSeconds;
+        }
+        return effectiveTimeout;
+    }
+    isTimeoutError(signal, timeoutController, error) {
+        if (!timeoutController.signal.aborted || signal.aborted) {
+            return false;
+        }
+        if (error === undefined || error === null) {
+            return true;
+        }
+        return this.isAbortError(error);
+    }
+    createTimeoutResult(timeoutSeconds, output, agentId) {
+        const message = `Task timed out after ${timeoutSeconds ?? DEFAULT_TASK_TIMEOUT_SECONDS}s (timeout_seconds).`;
+        return {
+            llmContent: message,
+            returnDisplay: message,
+            metadata: {
+                agentId: agentId ?? DEFAULT_AGENT_ID,
+                terminateReason: output?.terminate_reason,
+                emittedVars: output?.emitted_vars ?? {},
+                ...(output?.final_message
+                    ? { finalMessage: output.final_message }
+                    : {}),
+                timedOut: true,
+            },
+            error: {
+                message,
+                type: ToolErrorType.TIMEOUT,
+            },
+        };
+    }
+    /**
+     * @plan PLAN-20260130-ASYNCTASK.P11
+     *
+     * Note: Async tasks are designed to run independently in the background.
+     * Unlike foreground task execution, they do NOT wire cancellation or timeout
+     * to the parent agent's signal. This is an intentional design choice to allow
+     * async tasks to continue running even if the foreground agent is interrupted.
+     */
+    async executeAsync(signal, updateOutput) {
+        const settingsCheck = this.checkAsyncSettings();
+        if (settingsCheck) {
+            return settingsCheck;
+        }
+        const asyncTaskManager = this.deps.getAsyncTaskManager?.();
+        if (asyncTaskManager === undefined) {
+            return {
+                llmContent: 'Async mode requires AsyncTaskManager to be configured.',
+                returnDisplay: 'Error: Async mode not available.',
+                error: {
+                    message: 'AsyncTaskManager not configured',
+                    type: ToolErrorType.EXECUTION_FAILED,
+                },
+            };
+        }
+        let orchestrator;
+        try {
+            orchestrator = this.deps.createOrchestrator();
+        }
+        catch (error) {
+            return this.createErrorResult(error, 'Failed to create orchestrator for async task.');
+        }
+        const bookingId = asyncTaskManager.tryReserveAsyncSlot();
+        if (!bookingId) {
+            return this.createAsyncSlotResult(asyncTaskManager);
+        }
+        const setupResult = await this.setupAsyncInfrastructure(orchestrator, asyncTaskManager, bookingId);
+        if ('error' in setupResult && setupResult.error) {
+            return setupResult;
+        }
+        const { launchResult: _launchResult, agentId, scope, contextState, dispose, asyncAbortController, timeoutId, } = setupResult;
+        const asyncStreaming = this.setupAsyncStreaming(scope, agentId, updateOutput);
+        this.executeInBackground(scope, contextState, agentId, asyncTaskManager, dispose, asyncAbortController.signal, timeoutId, asyncStreaming?.emitAsyncClosingSubagentTag);
+        return {
+            llmContent: `Async task launched: subagent '${this.normalized.subagentName}' (ID: ${agentId}). ` +
+                `Task is running in background. Use 'check_async_tasks' to monitor progress.`,
+            returnDisplay: `Async task started: **${this.normalized.subagentName}** (\`${agentId}\`)`,
+            metadata: {
+                agentId,
+                async: true,
+                status: 'running',
+            },
+        };
+    }
+    checkAsyncSettings() {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- BN4-C-P01: preserve defensive runtime boundary guard despite current static types.
+        const settingsService = this.config.getSettingsService?.();
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- BN4-C-P01: preserve defensive runtime boundary guard despite current static types.
+        const globalSettings = settingsService?.getAllGlobalSettings?.() ?? {};
+        const subagentsSettings = globalSettings['subagents'];
+        const globalAsyncEnabled = subagentsSettings?.asyncEnabled !== false;
+        if (!globalAsyncEnabled) {
+            return {
+                llmContent: 'Async subagents are globally disabled via /settings. Enable "Async Subagents Enabled" in /settings to use async mode.',
+                returnDisplay: 'Error: Async subagents are globally disabled.',
+                error: {
+                    message: 'Async subagents are globally disabled via /settings.',
+                    type: ToolErrorType.EXECUTION_FAILED,
+                },
+            };
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- BN4-C-P01: preserve defensive runtime boundary guard despite current static types.
+        const ephemeralSettings = this.config.getEphemeralSettings?.() ?? {};
+        const profileAsyncEnabled = ephemeralSettings['subagents.async.enabled'] !== false;
+        if (!profileAsyncEnabled) {
+            return {
+                llmContent: 'This profile disables async subagents. Re-enable with: /set subagents.async.enabled true',
+                returnDisplay: 'Error: Async subagents disabled in profile.',
+                error: {
+                    message: 'Async subagents disabled in active profile.',
+                    type: ToolErrorType.EXECUTION_FAILED,
+                },
+            };
+        }
+        return undefined;
+    }
+    createAsyncSlotResult(asyncTaskManager) {
+        const canLaunch = asyncTaskManager.canLaunchAsync();
+        const baseReason = canLaunch.reason ?? 'Async task limit reached';
+        const guidance = 'You can: (1) wait for running async tasks to complete using check_async_tasks, ' +
+            '(2) launch this subagent synchronously (without async: true), or ' +
+            '(3) try again later when a slot is available.';
+        const errorMessage = `${baseReason}. ${guidance}`;
+        return {
+            llmContent: errorMessage,
+            returnDisplay: baseReason,
+            error: {
+                message: baseReason,
+                type: ToolErrorType.EXECUTION_FAILED,
+            },
+        };
+    }
+    async setupAsyncInfrastructure(orchestrator, asyncTaskManager, bookingId) {
+        let launchResult;
+        let agentId;
+        let scope;
+        let contextState;
+        let dispose;
+        const asyncAbortController = new AbortController();
+        let timeoutId = null;
+        let taskRegistered = false;
+        try {
+            const launchRequest = this.createLaunchRequest();
+            launchResult = await orchestrator.launch(launchRequest, undefined);
+            agentId = launchResult.agentId;
+            scope = launchResult.scope;
+            dispose = launchResult.dispose;
+            contextState = this.buildContextState();
+            const timeoutSetup = this.setupAsyncTimeout(asyncAbortController);
+            timeoutId = timeoutSetup.timeoutId;
+            asyncTaskManager.registerTask({
+                id: agentId,
+                subagentName: this.normalized.subagentName,
+                goalPrompt: this.normalized.goalPrompt,
+                abortController: asyncAbortController,
+            }, bookingId);
+            taskRegistered = true;
+        }
+        catch (error) {
+            if (!taskRegistered && bookingId) {
+                asyncTaskManager.cancelReservation(bookingId);
+            }
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+            if (dispose) {
+                void dispose();
+            }
+            return this.createErrorResult(error, `Failed to launch async subagent '${this.normalized.subagentName}'.`);
+        }
+        return {
+            launchResult,
+            agentId,
+            scope,
+            contextState,
+            dispose,
+            asyncAbortController,
+            timeoutId,
+        };
+    }
+    setupAsyncTimeout(asyncAbortController) {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- BN4-C-P01: preserve defensive runtime boundary guard despite current static types.
+        const settings = this.config.getEphemeralSettings?.() ?? {};
+        const defaultTimeoutSeconds = settings['task-default-timeout-seconds'] ??
+            DEFAULT_TASK_TIMEOUT_SECONDS;
+        const maxTimeoutSeconds = settings['task-max-timeout-seconds'] ??
+            MAX_TASK_TIMEOUT_SECONDS;
+        const timeoutSeconds = this.resolveTimeoutSeconds(this.params.timeout_seconds, defaultTimeoutSeconds, maxTimeoutSeconds);
+        const timeoutMs = timeoutSeconds === undefined ? undefined : timeoutSeconds * 1000;
+        const timeoutId = timeoutMs === undefined
+            ? null
+            : setTimeout(() => asyncAbortController.abort(), timeoutMs);
+        return { timeoutId };
+    }
+    setupAsyncStreaming(scope, agentId, updateOutput) {
+        if (!updateOutput)
+            return undefined;
+        let asyncXmlOutputOpen = false;
+        const emitAsyncClosingSubagentTag = () => {
+            if (!asyncXmlOutputOpen) {
+                return;
+            }
+            updateOutput(`</subagent name="${this.normalized.subagentName}" id="${agentId}">\n`);
+            asyncXmlOutputOpen = false;
+        };
+        updateOutput(`<subagent name="${this.normalized.subagentName}" id="${agentId}">\n`);
+        asyncXmlOutputOpen = true;
+        const existingHandler = scope.onMessage;
+        scope.onMessage = (message) => {
+            const cleaned = normalizeSubagentStreamingText(message);
+            if (cleaned.trim().length > 0) {
+                updateOutput(cleaned);
+            }
+            existingHandler?.(message);
+        };
+        return { emitAsyncClosingSubagentTag };
+    }
+    /**
+     * @plan PLAN-20260130-ASYNCTASK.P11
+     *
+     * Execute async task in background using the SAME execution path as sync tasks.
+     * The only difference is the foreground agent doesn't wait for completion.
+     * - Interactive environment → runInteractive() with shared scheduler (tool calls show in UI)
+     * - Non-interactive environment → runNonInteractive()
+     */
+    executeInBackground(scope, contextState, agentId, asyncTaskManager, dispose, signal, timeoutId, emitClosingSubagentTag) {
+        void (async () => {
+            try {
+                const environmentInteractive = this.deps.isInteractiveEnvironment?.() ?? true;
+                if (environmentInteractive &&
+                    typeof scope.runInteractive === 'function') {
+                    const schedulerFactory = this.deps.getSchedulerFactory?.();
+                    const interactiveOptions = schedulerFactory
+                        ? { schedulerFactory }
+                        : undefined;
+                    await scope.runInteractive(contextState, interactiveOptions);
+                }
+                else {
+                    await scope.runNonInteractive(contextState);
+                }
+                if (signal.aborted) {
+                    const task = asyncTaskManager.getTask(agentId);
+                    if (task?.status === 'running') {
+                        asyncTaskManager.failTask(agentId, 'Async task timed out');
+                    }
+                    return;
+                }
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- BN4-C-P01: preserve defensive runtime boundary guard despite current static types.
+                const output = scope.output ?? {
+                    terminate_reason: SubagentTerminateMode.ERROR,
+                    emitted_vars: {},
+                };
+                asyncTaskManager.completeTask(agentId, output);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                asyncTaskManager.failTask(agentId, errorMessage);
+            }
+            finally {
+                emitClosingSubagentTag?.();
+                if (timeoutId !== null) {
+                    clearTimeout(timeoutId);
+                }
+                try {
+                    await dispose();
+                }
+                catch {
+                    // Swallow dispose errors
+                }
+            }
+        })();
+    }
+}
+/**
+ * Task tool that launches subagents via SubagentOrchestrator.
+ *
+ * @plan PLAN-20251029-SUBAGENTIC
+ * @requirement REQ-SUBAGENTIC-001, REQ-SUBAGENTIC-002
+ */
+export class TaskTool extends BaseDeclarativeTool {
+    config;
+    dependencies;
+    static Name = 'task';
+    constructor(config, dependencies = {}) {
+        super(TaskTool.Name, 'Task', `Launches a named subagent, streams its progress, and returns the emitted variables upon completion. The subagent runs in an isolated runtime and is disposed after it finishes.`, Kind.Think, {
+            type: 'object',
+            additionalProperties: false,
+            required: ['subagent_name', 'goal_prompt'],
+            properties: {
+                subagent_name: {
+                    type: 'string',
+                    description: 'Name of the registered subagent to launch (as defined in ~/.llxprt/subagents).',
+                },
+                goal_prompt: {
+                    type: 'string',
+                    description: 'Primary goal or prompt to pass to the subagent. Included as the first behavioural prompt.',
+                },
+                behaviour_prompts: {
+                    type: 'array',
+                    description: 'Additional behavioural prompts to append after the goal prompt.',
+                    items: { type: 'string' },
+                },
+                tool_whitelist: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Restrict the subagent to this explicit list of tools. Tool names must match the registry.',
+                },
+                output_spec: {
+                    type: 'object',
+                    description: 'Expected output variables the subagent must emit before completing.',
+                    additionalProperties: { type: 'string' },
+                },
+                timeout_seconds: {
+                    type: 'number',
+                    description: 'Optional timeout in seconds for the task execution (-1 for unlimited).',
+                },
+                grace_period_seconds: {
+                    type: 'number',
+                    description: 'Optional grace period in seconds for recovery after a termination condition (TIMEOUT, MAX_TURNS, or protocol violation). Falls back to 60s if not specified or invalid.',
+                },
+                async: {
+                    type: 'boolean',
+                    description: 'If true, launch subagent in background and return immediately. Default: false.',
+                },
+                context: {
+                    type: 'object',
+                    description: 'Optional key/value pairs exposed to the subagent via the execution context.',
+                    additionalProperties: true,
+                },
+            },
+        }, true, true);
+        this.config = config;
+        this.dependencies = dependencies;
+    }
+    validateToolParamValues(params) {
+        const subagentName = params.subagent_name ?? params.subagentName ?? params.subagentName;
+        if (!subagentName || subagentName.trim().length === 0) {
+            return 'Task tool requires a subagent_name.';
+        }
+        const goalPrompt = params.goal_prompt ?? params.goalPrompt ?? params.goalPrompt;
+        if (!goalPrompt || goalPrompt.trim().length === 0) {
+            return 'Task tool requires a goal_prompt describing the assignment.';
+        }
+        return null;
+    }
+    createInvocation(params, messageBus) {
+        const normalized = this.normalizeParams(params);
+        return new TaskToolInvocation(this.config, params, normalized, {
+            createOrchestrator: () => this.ensureOrchestrator(),
+            getToolRegistry: typeof this.config.getToolRegistry === 'function'
+                ? () => this.config.getToolRegistry()
+                : undefined,
+            getSchedulerFactory: this.dependencies.schedulerFactoryProvider,
+            isInteractiveEnvironment: this.dependencies.isInteractiveEnvironment ??
+                (() => this.config.isInteractive()),
+            getAsyncTaskManager: this.dependencies.getAsyncTaskManager,
+        }, messageBus);
+    }
+    normalizeParams(params) {
+        const subagentName = (params.subagent_name ??
+            params.subagentName ??
+            '').trim();
+        const goalPrompt = (params.goal_prompt ?? params.goalPrompt ?? '').trim();
+        const behaviourPrompts = [
+            goalPrompt,
+            // eslint-disable-next-line sonarjs/expression-complexity -- Existing structure is intentionally preserved; refactoring this boundary is outside the lint slice.
+            ...(params.behaviour_prompts ??
+                params.behavior_prompts ??
+                params.behaviourPrompts ??
+                params.behaviorPrompts ??
+                []),
+        ]
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- BN4-C-P01: preserve defensive runtime boundary guard despite current static types.
+            .map((prompt) => prompt?.trim())
+            .filter((prompt) => Boolean(prompt))
+            .filter((prompt, index, array) => array.indexOf(prompt) === index);
+        const toolWhitelist = (params.tool_whitelist ?? params.toolWhitelist ?? [])
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- BN4-C-P01: preserve defensive runtime boundary guard despite current static types.
+            .map((tool) => tool?.trim())
+            .filter((tool) => Boolean(tool));
+        const outputSpec = params.output_spec ?? params.outputSpec ?? undefined;
+        const context = params.context ?? params.context_vars ?? params.contextVars ?? {};
+        return {
+            subagentName,
+            goalPrompt,
+            behaviourPrompts,
+            toolWhitelist: toolWhitelist.length > 0 ? toolWhitelist : undefined,
+            outputSpec,
+            context,
+            async: params.async ?? false,
+        };
+    }
+    ensureOrchestrator() {
+        if (this.dependencies.orchestratorFactory) {
+            return this.dependencies.orchestratorFactory();
+        }
+        const configWithManagers = this.config;
+        const profileManager = this.dependencies.profileManager ??
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- BN4-C-P01: preserve defensive runtime boundary guard despite current static types.
+            configWithManagers.getProfileManager?.();
+        const subagentManager = this.dependencies.subagentManager ??
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- BN4-C-P01: preserve defensive runtime boundary guard despite current static types.
+            configWithManagers.getSubagentManager?.();
+        if (!profileManager || !subagentManager) {
+            throw new Error('Task tool requires profile and subagent managers to be configured.');
+        }
+        return new SubagentOrchestrator({
+            subagentManager,
+            profileManager,
+            foregroundConfig: this.config,
+        });
+    }
+}
+//# sourceMappingURL=task.js.map