juno-code 1.0.47 → 1.0.50

package/dist/index.d.ts

@@ -0,0 +1,2133 @@
+import { z } from 'zod';
+import { EventEmitter } from 'node:events';
+
+/**
+ * Core type definitions for juno-code
+ */
+type SubagentType = 'claude' | 'cursor' | 'codex' | 'gemini' | 'pi';
+type BackendType = 'shell';
+type SessionStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+type LogLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+type OnHourlyLimit = 'wait' | 'raise';
+type HookType$1 = 'START_RUN' | 'START_ITERATION' | 'END_ITERATION' | 'END_RUN' | 'ON_STALE';
+interface Hook$1 {
+    commands: string[];
+}
+type Hooks = Record<HookType$1, Hook$1>;
+type ProgressEventType$1 = 'tool_start' | 'tool_result' | 'thinking' | 'error' | 'info';
+interface JunoTaskConfig {
+    defaultSubagent: SubagentType;
+    defaultMaxIterations: number;
+    defaultModel?: string;
+    defaultBackend: BackendType;
+    mainTask?: string;
+    logLevel: LogLevel;
+    logFile?: string;
+    /** Verbosity level: 0=quiet, 1=normal+helping texts (default), 2=debug+hooks */
+    verbose: number;
+    quiet: boolean;
+    mcpTimeout: number;
+    mcpRetries: number;
+    mcpServerPath?: string;
+    mcpServerName?: string;
+    hookCommandTimeout?: number;
+    onHourlyLimit: OnHourlyLimit;
+    interactive: boolean;
+    headlessMode: boolean;
+    workingDirectory: string;
+    sessionDirectory: string;
+    /** Path to project env file loaded on startup (relative to workingDirectory or absolute) */
+    envFilePath?: string;
+    /** Tracks whether the configured env file has been initialized from .env.juno */
+    envFileCopied?: boolean;
+    hooks?: Hooks;
+    skipHooks?: boolean;
+}
+declare global {
+    const __VERSION__: string;
+    const __DEV__: boolean;
+}
+
+/**
+ * Core configuration module for juno-code
+ *
+ * Provides comprehensive configuration management with multi-source loading,
+ * validation, and environment variable support.
+ *
+ * @module core/config
+ */
+
+/**
+ * Environment variable mapping for configuration options
+ * All config options can be set via JUNO_CODE_* environment variables
+ * Uses JUNO_CODE_* environment variables
+ */
+declare const ENV_VAR_MAPPING: {
+    readonly JUNO_CODE_DEFAULT_SUBAGENT: "defaultSubagent";
+    readonly JUNO_CODE_DEFAULT_BACKEND: "defaultBackend";
+    readonly JUNO_CODE_DEFAULT_MAX_ITERATIONS: "defaultMaxIterations";
+    readonly JUNO_CODE_DEFAULT_MODEL: "defaultModel";
+    readonly JUNO_CODE_LOG_LEVEL: "logLevel";
+    readonly JUNO_CODE_LOG_FILE: "logFile";
+    readonly JUNO_CODE_VERBOSE: "verbose";
+    readonly JUNO_CODE_QUIET: "quiet";
+    readonly JUNO_CODE_MCP_TIMEOUT: "mcpTimeout";
+    readonly JUNO_CODE_MCP_RETRIES: "mcpRetries";
+    readonly JUNO_CODE_MCP_SERVER_PATH: "mcpServerPath";
+    readonly JUNO_CODE_MCP_SERVER_NAME: "mcpServerName";
+    readonly JUNO_CODE_HOOK_COMMAND_TIMEOUT: "hookCommandTimeout";
+    readonly JUNO_CODE_ON_HOURLY_LIMIT: "onHourlyLimit";
+    readonly JUNO_CODE_INTERACTIVE: "interactive";
+    readonly JUNO_CODE_HEADLESS_MODE: "headlessMode";
+    readonly JUNO_CODE_WORKING_DIRECTORY: "workingDirectory";
+    readonly JUNO_CODE_SESSION_DIRECTORY: "sessionDirectory";
+};
+/**
+ * Zod schema for validating JunoTaskConfig
+ * Provides runtime validation with detailed error messages
+ */
+declare const JunoTaskConfigSchema: z.ZodObject<{
+    defaultSubagent: z.ZodEnum<["claude", "cursor", "codex", "gemini", "pi"]>;
+    defaultBackend: z.ZodEnum<["shell"]>;
+    defaultMaxIterations: z.ZodNumber;
+    defaultModel: z.ZodOptional<z.ZodString>;
+    mainTask: z.ZodOptional<z.ZodString>;
+    logLevel: z.ZodEnum<["error", "warn", "info", "debug", "trace"]>;
+    logFile: z.ZodOptional<z.ZodString>;
+    verbose: z.ZodEffects<z.ZodNumber, number, unknown>;
+    quiet: z.ZodBoolean;
+    mcpTimeout: z.ZodNumber;
+    mcpRetries: z.ZodNumber;
+    mcpServerPath: z.ZodOptional<z.ZodString>;
+    mcpServerName: z.ZodOptional<z.ZodString>;
+    hookCommandTimeout: z.ZodOptional<z.ZodNumber>;
+    onHourlyLimit: z.ZodEnum<["wait", "raise"]>;
+    interactive: z.ZodBoolean;
+    headlessMode: z.ZodBoolean;
+    workingDirectory: z.ZodString;
+    sessionDirectory: z.ZodString;
+    envFilePath: z.ZodOptional<z.ZodString>;
+    envFileCopied: z.ZodOptional<z.ZodBoolean>;
+    hooks: z.ZodOptional<z.ZodRecord<z.ZodEnum<["START_RUN", "START_ITERATION", "END_ITERATION", "END_RUN", "ON_STALE"]>, z.ZodObject<{
+        commands: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        commands?: string[];
+    }, {
+        commands?: string[];
+    }>>>;
+    skipHooks: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    defaultSubagent?: "claude" | "cursor" | "codex" | "gemini" | "pi";
+    defaultBackend?: "shell";
+    defaultMaxIterations?: number;
+    defaultModel?: string;
+    logLevel?: "error" | "warn" | "info" | "debug" | "trace";
+    logFile?: string;
+    verbose?: number;
+    quiet?: boolean;
+    mcpTimeout?: number;
+    mcpRetries?: number;
+    mcpServerPath?: string;
+    mcpServerName?: string;
+    hookCommandTimeout?: number;
+    onHourlyLimit?: "wait" | "raise";
+    interactive?: boolean;
+    headlessMode?: boolean;
+    workingDirectory?: string;
+    sessionDirectory?: string;
+    mainTask?: string;
+    envFilePath?: string;
+    envFileCopied?: boolean;
+    hooks?: Partial<Record<"START_RUN" | "START_ITERATION" | "END_ITERATION" | "END_RUN" | "ON_STALE", {
+        commands?: string[];
+    }>>;
+    skipHooks?: boolean;
+}, {
+    defaultSubagent?: "claude" | "cursor" | "codex" | "gemini" | "pi";
+    defaultBackend?: "shell";
+    defaultMaxIterations?: number;
+    defaultModel?: string;
+    logLevel?: "error" | "warn" | "info" | "debug" | "trace";
+    logFile?: string;
+    verbose?: unknown;
+    quiet?: boolean;
+    mcpTimeout?: number;
+    mcpRetries?: number;
+    mcpServerPath?: string;
+    mcpServerName?: string;
+    hookCommandTimeout?: number;
+    onHourlyLimit?: "wait" | "raise";
+    interactive?: boolean;
+    headlessMode?: boolean;
+    workingDirectory?: string;
+    sessionDirectory?: string;
+    mainTask?: string;
+    envFilePath?: string;
+    envFileCopied?: boolean;
+    hooks?: Partial<Record<"START_RUN" | "START_ITERATION" | "END_ITERATION" | "END_RUN" | "ON_STALE", {
+        commands?: string[];
+    }>>;
+    skipHooks?: boolean;
+}>;
+/**
+ * Default configuration values
+ * These are used as fallbacks when no other configuration is provided
+ */
+declare const DEFAULT_CONFIG: JunoTaskConfig;
+/**
+ * ConfigLoader class for multi-source configuration loading
+ *
+ * Implements configuration precedence: CLI args > Environment Variables > Project Config > Global Config Files > Profile > Defaults
+ */
+declare class ConfigLoader {
+    private baseDir;
+    private configSources;
+    /**
+     * Create a new ConfigLoader instance
+     *
+     * @param baseDir - Base directory for relative path resolution
+     */
+    constructor(baseDir?: string);
+    /**
+     * Load configuration from environment variables
+     *
+     * @returns This ConfigLoader instance for method chaining
+     */
+    fromEnvironment(): this;
+    /**
+     * Load configuration from a specific file
+     *
+     * @param filePath - Path to configuration file
+     * @returns This ConfigLoader instance for method chaining
+     */
+    fromFile(filePath: string): Promise<this>;
+    /**
+     * Load configuration from project-specific config file
+     * Loads from .juno_task/config.json with highest precedence for project settings
+     *
+     * @returns This ConfigLoader instance for method chaining
+     */
+    fromProjectConfig(): Promise<this>;
+    /**
+     * Automatically discover and load configuration files
+     * Searches for both project-specific and global config files in the base directory
+     * Project-specific config (.juno_task/config.json) takes precedence over global configs
+     *
+     * @returns This ConfigLoader instance for method chaining
+     */
+    autoDiscoverFile(): Promise<this>;
+    /**
+     * Load configuration from CLI arguments
+     *
+     * @param cliConfig - Configuration object from CLI argument parsing
+     * @returns This ConfigLoader instance for method chaining
+     */
+    fromCli(cliConfig: Partial<JunoTaskConfig>): this;
+    /**
+     * Merge all configuration sources according to precedence
+     * CLI args > Environment Variables > Project Config > Global Config Files > Defaults
+     *
+     * @returns Merged configuration object
+     */
+    merge(): JunoTaskConfig;
+    /**
+     * Load and merge configuration from all sources
+     * Convenience method that performs auto-discovery and returns validated config
+     *
+     * @param cliConfig - Optional CLI configuration
+     * @returns Promise resolving to validated configuration
+     */
+    loadAll(cliConfig?: Partial<JunoTaskConfig>): Promise<JunoTaskConfig>;
+}
+/**
+ * Validate configuration object against schema
+ *
+ * @param config - Configuration object to validate
+ * @returns Validated configuration object
+ * @throws Error if validation fails
+ */
+declare function validateConfig(config: unknown): JunoTaskConfig;
+/**
+ * Load and validate configuration from all sources
+ *
+ * This is the main entry point for configuration loading.
+ * It performs auto-discovery, merging, and validation.
+ *
+ * @param options - Configuration loading options
+ * @param options.baseDir - Base directory for relative path resolution
+ * @param options.configFile - Specific configuration file to load
+ * @param options.cliConfig - CLI configuration override
+ * @returns Promise resolving to validated configuration
+ *
+ * @example
+ * ```typescript
+ * // Load with auto-discovery
+ * const config = await loadConfig();
+ *
+ * // Load with specific file
+ * const config = await loadConfig({
+ *   configFile: './my-config.json'
+ * });
+ *
+ * // Load with CLI overrides
+ * const config = await loadConfig({
+ *   cliConfig: { verbose: true, logLevel: 'debug' }
+ * });
+ * ```
+ */
+declare function loadConfig(options?: {
+    baseDir?: string;
+    configFile?: string;
+    cliConfig?: Partial<JunoTaskConfig>;
+}): Promise<JunoTaskConfig>;
+/**
+ * Type export for configuration loading options
+ */
+type ConfigLoadOptions = Parameters<typeof loadConfig>[0];
+/**
+ * Type export for environment variable mapping
+ */
+type EnvVarMapping = typeof ENV_VAR_MAPPING;
+
+/**
+ * Default hooks template configuration
+ *
+ * This module provides default hook commands that are shipped with juno-code.
+ * These hooks are automatically configured during project initialization (init command).
+ *
+ * Hook Types:
+ * - START_RUN: Executes at the beginning of a run (before all iterations)
+ * - START_ITERATION: Executes at the start of each iteration
+ * - END_ITERATION: Executes at the end of each iteration
+ * - END_RUN: Executes at the end of a run (after all iterations)
+ *
+ * To modify default hooks:
+ * 1. Update the commands in this file
+ * 2. Rebuild the project (npm run build)
+ * 3. New installations will use the updated defaults
+ *
+ * @module templates/default-hooks
+ */
+
+/**
+ * Default hooks configuration template
+ *
+ * All hook types are included so users can see available hooks without reading documentation.
+ * Empty command arrays indicate hooks that are available but not configured by default.
+ *
+ * These hooks provide useful default behaviors:
+ * - File size monitoring for CLAUDE.md, AGENTS.md, .juno_task/plan.md, .juno_task/tasks.md
+ * - Alerts via juno-kanban when documentation/task files become too large
+ *
+ * Users can customize these hooks by editing .juno_task/config.json after initialization
+ */
+declare const DEFAULT_HOOKS: Hooks;
+/**
+ * Get default hooks configuration
+ *
+ * Returns a copy of the default hooks to prevent mutation of the template.
+ * This function can be used during initialization to populate the config.json file.
+ *
+ * @returns A copy of the default hooks configuration
+ */
+declare function getDefaultHooks(): Hooks;
+/**
+ * Get default hooks as formatted JSON string for config.json
+ *
+ * @param indent - Number of spaces for indentation (default: 2)
+ * @returns Formatted JSON string of default hooks
+ */
+declare function getDefaultHooksJson(indent?: number): string;
+
+/**
+ * Execution error definitions for juno-task-ts
+ *
+ * Provides comprehensive error classes and utilities for execution operations,
+ * including error codes, context tracking, recovery suggestions, and
+ * specialized error types for different failure scenarios.
+ *
+ * Originally migrated from the MCP error module. The MCP system has been
+ * removed; these are now the canonical execution error definitions.
+ * Deprecated MCP-prefixed aliases are retained below for backward compatibility.
+ *
+ * @module core/errors
+ * @version 2.0.0
+ */
+/**
+ * Execution error categories for targeted error handling
+ */
+declare enum ExecutionErrorType {
+    CONNECTION = "connection",
+    TIMEOUT = "timeout",
+    RATE_LIMIT = "rate_limit",
+    TOOL_EXECUTION = "tool_execution",
+    VALIDATION = "validation",
+    SERVER_NOT_FOUND = "server_not_found",
+    PROTOCOL = "protocol",
+    AUTHENTICATION = "authentication"
+}
+/**
+ * Error codes for specific error conditions
+ */
+declare enum ExecutionErrorCode {
+    CONNECTION_FAILED = "MCP_CONNECTION_FAILED",
+    CONNECTION_TIMEOUT = "MCP_CONNECTION_TIMEOUT",
+    CONNECTION_REFUSED = "MCP_CONNECTION_REFUSED",
+    CONNECTION_LOST = "MCP_CONNECTION_LOST",
+    RECONNECTION_FAILED = "MCP_RECONNECTION_FAILED",
+    TOOL_NOT_FOUND = "MCP_TOOL_NOT_FOUND",
+    TOOL_EXECUTION_FAILED = "MCP_TOOL_EXECUTION_FAILED",
+    TOOL_TIMEOUT = "MCP_TOOL_TIMEOUT",
+    TOOL_INVALID_ARGUMENTS = "MCP_TOOL_INVALID_ARGUMENTS",
+    RATE_LIMIT_EXCEEDED = "MCP_RATE_LIMIT_EXCEEDED",
+    RATE_LIMIT_HOURLY = "MCP_RATE_LIMIT_HOURLY",
+    RATE_LIMIT_DAILY = "MCP_RATE_LIMIT_DAILY",
+    VALIDATION_FAILED = "MCP_VALIDATION_FAILED",
+    INVALID_REQUEST = "MCP_INVALID_REQUEST",
+    MISSING_PARAMETERS = "MCP_MISSING_PARAMETERS",
+    INVALID_PARAMETERS = "MCP_INVALID_PARAMETERS",
+    SERVER_NOT_FOUND = "MCP_SERVER_NOT_FOUND",
+    SERVER_NOT_EXECUTABLE = "MCP_SERVER_NOT_EXECUTABLE",
+    SERVER_STARTUP_FAILED = "MCP_SERVER_STARTUP_FAILED",
+    SERVER_CRASHED = "MCP_SERVER_CRASHED",
+    PROTOCOL_ERROR = "MCP_PROTOCOL_ERROR",
+    INVALID_RESPONSE = "MCP_INVALID_RESPONSE",
+    VERSION_MISMATCH = "MCP_VERSION_MISMATCH",
+    AUTHENTICATION_FAILED = "MCP_AUTHENTICATION_FAILED",
+    UNAUTHORIZED = "MCP_UNAUTHORIZED",
+    TOKEN_EXPIRED = "MCP_TOKEN_EXPIRED"
+}
+/**
+ * Base error options for execution errors
+ */
+interface ExecutionErrorOptions {
+    /** Error code for programmatic handling */
+    readonly code?: ExecutionErrorCode | undefined;
+    /** Operation context when error occurred */
+    readonly context?: string | undefined;
+    /** Retry information */
+    readonly retryInfo?: RetryInfo | undefined;
+    /** Recovery suggestions for the user */
+    readonly recoverySuggestions?: readonly string[] | undefined;
+    /** Cause error for error chaining */
+    readonly cause?: Error | undefined;
+    /** Additional metadata */
+    readonly metadata?: Readonly<Record<string, unknown>> | undefined;
+}
+/**
+ * Retry information for error context
+ */
+interface RetryInfo {
+    /** Current attempt number */
+    readonly attempt: number;
+    /** Maximum attempts allowed */
+    readonly maxAttempts: number;
+    /** Next retry time */
+    readonly nextRetryTime?: Date;
+    /** Retry strategy used */
+    readonly strategy: string;
+    /** Backoff delay in milliseconds */
+    readonly backoffDelay?: number;
+}
+/**
+ * Base execution error class with enhanced context and recovery information
+ */
+declare abstract class ExecutionError extends Error {
+    /** Error type classification */
+    readonly type: ExecutionErrorType;
+    /** Error code for programmatic handling */
+    readonly code: ExecutionErrorCode;
+    /** Error timestamp */
+    readonly timestamp: Date;
+    /** Operation context */
+    readonly context?: string | undefined;
+    /** Retry information */
+    readonly retryInfo?: RetryInfo | undefined;
+    /** Recovery suggestions */
+    readonly recoverySuggestions?: readonly string[] | undefined;
+    /** Additional metadata */
+    readonly metadata?: Readonly<Record<string, unknown>> | undefined;
+    /** Cause error for error chaining */
+    readonly cause?: Error | undefined;
+    constructor(message: string, type: ExecutionErrorType, code: ExecutionErrorCode, options?: ExecutionErrorOptions);
+    /**
+     * Get user-friendly error message
+     */
+    getUserMessage(): string;
+    /**
+     * Get technical error details
+     */
+    getTechnicalDetails(): string;
+    /**
+     * Check if error is retryable
+     */
+    isRetryable(): boolean;
+    /**
+     * Get time until next retry
+     */
+    getRetryDelay(): number;
+    /**
+     * Serialize error to JSON
+     */
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * Progress event types from Roundtable server format
+ */
+declare enum ProgressEventType {
+    TOOL_START = "tool_start",
+    TOOL_RESULT = "tool_result",
+    THINKING = "thinking",
+    ERROR = "error",
+    INFO = "info",
+    DEBUG = "debug"
+}
+/**
+ * Tool execution status for tracking
+ */
+declare enum ToolExecutionStatus {
+    PENDING = "pending",
+    RUNNING = "running",
+    COMPLETED = "completed",
+    FAILED = "failed",
+    CANCELLED = "cancelled",
+    TIMEOUT = "timeout"
+}
+/**
+ * Progress event interface matching Roundtable server format
+ * Format: "Backend #count: event_type => content"
+ *
+ * @example
+ * ```typescript
+ * const progressEvent: ProgressEvent = {
+ *   sessionId: 'session-123',
+ *   timestamp: new Date(),
+ *   backend: 'claude',
+ *   count: 1,
+ *   type: ProgressEventType.TOOL_START,
+ *   content: 'Starting code analysis...',
+ *   toolId: 'claude_1',
+ *   metadata: {
+ *     duration: 150,
+ *     tokens: 1024
+ *   }
+ * };
+ * ```
+ */
+interface ProgressEvent {
+    /** Unique session identifier for correlation */
+    readonly sessionId: string;
+    /** Event timestamp */
+    readonly timestamp: Date;
+    /** Subagent backend name (claude, cursor, codex, gemini) */
+    readonly backend: string;
+    /** Sequential event number within session */
+    readonly count: number;
+    /** Progress event classification */
+    readonly type: ProgressEventType;
+    /** Event content/message from subagent */
+    readonly content: string;
+    /** Generated tool correlation ID for tracking */
+    readonly toolId: string;
+    /** Additional event metadata */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    /** Parent event ID for nested operations */
+    readonly parentId?: string;
+    /** Event priority level */
+    readonly priority?: 'low' | 'normal' | 'high';
+}
+/**
+ * Progress callback function signature
+ * Callbacks must never throw errors to avoid breaking execution flow
+ *
+ * @param event - The progress event to handle
+ * @returns Promise<void> - Should handle errors internally
+ */
+type ProgressCallback = (event: ProgressEvent) => Promise<void> | void;
+/**
+ * Tool call request structure
+ *
+ * @example
+ * ```typescript
+ * const request: ToolCallRequest = {
+ *   toolName: 'claude_subagent',
+ *   arguments: {
+ *     instruction: 'Analyze this code',
+ *     project_path: '/path/to/project',
+ *     model: 'sonnet-4'
+ *   },
+ *   timeout: 30000,
+ *   priority: 'high',
+ *   metadata: {
+ *     userId: 'user-123',
+ *     sessionId: 'session-456'
+ *   }
+ * };
+ * ```
+ */
+interface ToolCallRequest {
+    /** Tool name (mapped from subagent name) */
+    readonly toolName: string;
+    /** Tool arguments object */
+    readonly arguments: Readonly<Record<string, unknown>>;
+    /** Request timeout in milliseconds */
+    readonly timeout?: number;
+    /** Request priority level */
+    readonly priority?: 'low' | 'normal' | 'high';
+    /** Additional request metadata */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    /** Callback for progress events */
+    readonly progressCallback?: ProgressCallback;
+    /** Unique request identifier */
+    readonly requestId?: string;
+}
+/**
+ * Tool call result structure
+ */
+interface ToolCallResult {
+    /** Tool execution result content */
+    readonly content: string;
+    /** Execution status */
+    readonly status: ToolExecutionStatus;
+    /** Execution start time */
+    readonly startTime: Date;
+    /** Execution end time */
+    readonly endTime: Date;
+    /** Total execution duration in milliseconds */
+    readonly duration: number;
+    /** Any error that occurred during execution */
+    readonly error?: Error;
+    /** Progress events generated during execution */
+    readonly progressEvents: readonly ProgressEvent[];
+    /** Tool execution metadata */
+    readonly metadata?: ToolExecutionMetadata;
+    /** Request that generated this result */
+    readonly request: ToolCallRequest;
+}
+/**
+ * Tool execution metadata
+ */
+interface ToolExecutionMetadata {
+    /** Number of tokens used */
+    readonly tokensUsed?: number;
+    /** Estimated cost */
+    readonly estimatedCost?: number;
+    /** Model used for execution */
+    readonly model?: string;
+    /** Server version */
+    readonly serverVersion?: string;
+    /** Performance metrics */
+    readonly performanceMetrics?: ToolPerformanceMetrics;
+    /** Raw subagent response payload (for programmatic capture / session resume) */
+    readonly subAgentResponse?: any;
+    /** Indicates the content string is structured (e.g., JSON) and safe to parse */
+    readonly structuredOutput?: boolean;
+    /** Content type for the tool output (e.g., application/json) */
+    readonly contentType?: string;
+    /** Original raw output emitted by the tool (pre-structuring) */
+    readonly rawOutput?: string;
+    /** Quota limit information detected during execution */
+    readonly quotaLimitInfo?: any;
+}
+/**
+ * Tool performance metrics
+ */
+interface ToolPerformanceMetrics {
+    /** CPU usage during execution */
+    readonly cpuUsage: number;
+    /** Memory usage during execution */
+    readonly memoryUsage: number;
+    /** Network usage in bytes */
+    readonly networkUsage: number;
+    /** Processing time breakdown */
+    readonly timingBreakdown: Record<string, number>;
+}
+/**
+ * Session context (renamed from MCPSessionContext)
+ */
+interface SessionContext {
+    /** Unique session identifier */
+    readonly sessionId: string;
+    /** Session start time */
+    readonly startTime: Date;
+    /** User identifier */
+    readonly userId?: string;
+    /** Session metadata */
+    readonly metadata: Readonly<Record<string, unknown>>;
+    /** Active tool calls */
+    readonly activeToolCalls: readonly string[];
+    /** Session state */
+    readonly state: SessionState;
+    /** Last activity time */
+    readonly lastActivity: Date;
+}
+/**
+ * Session state
+ */
+declare enum SessionState {
+    INITIALIZING = "initializing",
+    ACTIVE = "active",
+    IDLE = "idle",
+    SUSPENDED = "suspended",
+    COMPLETED = "completed",
+    FAILED = "failed"
+}
+
+/**
+ * Core execution engine module for juno-task-ts
+ *
+ * This module provides the main execution orchestration engine that manages
+ * the entire workflow for AI task execution, including session management,
+ * backend integration, progress tracking, error handling, and cancellation.
+ *
+ * The implementation closely matches the Python budi-cli execution patterns,
+ * including rate limit handling, iteration logic, and progress tracking.
+ *
+ * @module core/engine
+ * @since 1.0.0
+ */
+
+/**
+ * Execution request interface for starting task execution
+ */
+interface ExecutionRequest {
+    /** Unique request identifier */
+    readonly requestId: string;
+    /** Task instruction or prompt text */
+    readonly instruction: string;
+    /** Subagent to use for execution */
+    readonly subagent: SubagentType;
+    /** Backend to use for execution */
+    readonly backend: BackendType;
+    /** Working directory for execution */
+    readonly workingDirectory: string;
+    /** Maximum number of iterations (-1 for unlimited) */
+    readonly maxIterations: number;
+    /** Optional specific model to use */
+    readonly model?: string;
+    /** Optional timeout in milliseconds (overrides config) */
+    readonly timeoutMs?: number;
+    /** Session metadata */
+    readonly sessionMetadata?: Record<string, unknown>;
+    /** Custom progress callbacks */
+    readonly progressCallbacks?: ProgressCallback[];
+    /** Request priority level */
+    readonly priority?: 'low' | 'normal' | 'high';
+    /** MCP server name (for MCP backend) */
+    readonly mcpServerName?: string;
+    /** Available tools from built-in set (only works with --print mode, forwarded to shell backend) */
+    readonly tools?: string[];
+    /** Permission-based filtering of specific tool instances (forwarded to shell backend) */
+    readonly allowedTools?: string[];
+    /** Disallowed tools (forwarded to shell backend) */
+    readonly disallowedTools?: string[];
+    /** Append tools to default allowed-tools list (forwarded to shell backend) */
+    readonly appendAllowedTools?: string[];
+    /** Agents configuration (forwarded to shell backend) */
+    readonly agents?: string;
+    /** Resume a conversation by session ID (forwarded to shell backend) */
+    readonly resume?: string;
+    /** Continue the most recent conversation (forwarded to shell backend) */
+    readonly continueConversation?: boolean;
+    /** Extended thinking level (forwarded to shell backend --thinking flag) */
+    readonly thinking?: string;
+}
+/**
+ * Execution result interface for completed executions
+ */
+interface ExecutionResult {
+    /** Request that generated this result */
+    readonly request: ExecutionRequest;
+    /** Execution status */
+    readonly status: ExecutionStatus;
+    /** Execution start time */
+    readonly startTime: Date;
+    /** Execution end time */
+    readonly endTime: Date;
+    /** Total execution duration in milliseconds */
+    readonly duration: number;
+    /** All iteration results */
+    readonly iterations: readonly IterationResult[];
+    /** Final execution statistics */
+    readonly statistics: ExecutionStatistics;
+    /** Any error that terminated execution */
+    readonly error?: ExecutionError;
+    /** Session context information */
+    readonly sessionContext: SessionContext;
+    /** All progress events captured during execution */
+    readonly progressEvents: readonly ProgressEvent[];
+}
+/**
+ * Individual iteration result
+ */
+interface IterationResult {
+    /** Iteration number (1-based) */
+    readonly iterationNumber: number;
+    /** Iteration success status */
+    readonly success: boolean;
+    /** Iteration start time */
+    readonly startTime: Date;
+    /** Iteration end time */
+    readonly endTime: Date;
+    /** Iteration duration in milliseconds */
+    readonly duration: number;
+    /** Tool call result */
+    readonly toolResult: ToolCallResult;
+    /** Iteration-specific progress events */
+    readonly progressEvents: readonly ProgressEvent[];
+    /** Any error that occurred during iteration */
+    readonly error?: Error;
+}
+/**
+ * Execution status enumeration
+ */
+declare enum ExecutionStatus {
+    PENDING = "pending",
+    RUNNING = "running",
+    COMPLETED = "completed",
+    FAILED = "failed",
+    CANCELLED = "cancelled",
+    TIMEOUT = "timeout",
+    RATE_LIMITED = "rate_limited"
+}
+/**
+ * Execution statistics for performance tracking
+ */
+interface ExecutionStatistics {
+    /** Total iterations attempted */
+    totalIterations: number;
+    /** Number of successful iterations */
+    successfulIterations: number;
+    /** Number of failed iterations */
+    failedIterations: number;
+    /** Average iteration duration in milliseconds */
+    averageIterationDuration: number;
+    /** Total tool calls made */
+    totalToolCalls: number;
+    /** Total progress events processed */
+    totalProgressEvents: number;
+    /** Rate limit encounters */
+    rateLimitEncounters: number;
+    /** Total rate limit wait time in milliseconds */
+    rateLimitWaitTime: number;
+    /** Quota limit encounters (Claude-specific) */
+    quotaLimitEncounters: number;
+    /** Total quota limit wait time in milliseconds */
+    quotaLimitWaitTime: number;
+    /** Error breakdown by type */
+    errorBreakdown: Record<string, number>;
+    /** Performance metrics */
+    performanceMetrics: PerformanceMetrics;
+}
+/**
+ * Performance metrics for detailed analysis
+ */
+interface PerformanceMetrics {
+    /** CPU usage percentage during execution */
+    cpuUsage: number;
+    /** Memory usage in bytes */
+    memoryUsage: number;
+    /** Network requests made */
+    networkRequests: number;
+    /** File system operations */
+    fileSystemOperations: number;
+    /** Throughput metrics */
+    throughput: ThroughputMetrics;
+}
+/**
+ * Throughput metrics
+ */
+interface ThroughputMetrics {
+    /** Iterations per minute */
+    iterationsPerMinute: number;
+    /** Progress events per second */
+    progressEventsPerSecond: number;
+    /** Tool calls per minute */
+    toolCallsPerMinute: number;
+}
+/**
+ * Rate limit information for handling
+ */
+interface RateLimitInfo {
+    /** Whether currently rate limited */
+    readonly isRateLimited: boolean;
+    /** Rate limit reset time */
+    readonly resetTime?: Date;
+    /** Remaining requests in current window */
+    readonly remaining: number;
+    /** Time to wait before next request in milliseconds */
+    readonly waitTimeMs: number;
+    /** Rate limit tier/category */
+    readonly tier?: string;
+}
+/**
+ * Error recovery strategy configuration
+ */
+interface ErrorRecoveryConfig {
+    /** Maximum recovery attempts per error type */
+    readonly maxAttempts: Record<string, number>;
+    /** Retry delays by error type in milliseconds */
+    readonly retryDelays: Record<string, number>;
+    /** Whether to continue on specific error types */
+    readonly continueOnError: Record<string, boolean>;
+    /** Custom recovery strategies */
+    readonly customStrategies: Record<string, (error: ExecutionError) => Promise<boolean>>;
+}
+/**
+ * Execution engine configuration
+ */
+interface ExecutionEngineConfig {
+    /** Base configuration */
+    readonly config: JunoTaskConfig;
+    /** No longer uses BackendManager; engine creates ShellBackend directly */
+    /** Error recovery configuration */
+    readonly errorRecovery: ErrorRecoveryConfig;
+    /** Rate limit handling configuration */
+    readonly rateLimitConfig: RateLimitHandlingConfig;
+    /** Progress tracking configuration */
+    readonly progressConfig: ProgressTrackingConfig;
+}
+/**
+ * Rate limit handling configuration
+ */
+interface RateLimitHandlingConfig {
+    /** Enable automatic rate limit handling */
+    readonly enabled: boolean;
+    /** Maximum wait time for rate limits in milliseconds */
+    readonly maxWaitTimeMs: number;
+    /** Rate limit detection patterns */
+    readonly detectionPatterns: readonly RegExp[];
+    /** Custom rate limit parsers */
+    readonly customParsers: readonly RateLimitParser[];
+}
+/**
+ * Rate limit parser interface
+ */
+interface RateLimitParser {
+    /** Pattern to match rate limit messages */
+    readonly pattern: RegExp;
+    /** Parse function to extract reset time */
+    readonly parse: (message: string) => Date | null;
+}
+/**
+ * Progress tracking configuration
+ */
+interface ProgressTrackingConfig {
+    /** Enable progress tracking */
+    readonly enabled: boolean;
+    /** Buffer size for progress events */
+    readonly bufferSize: number;
+    /** Progress event filters */
+    readonly filters: readonly ProgressEventFilter[];
+    /** Custom progress processors */
+    readonly processors: readonly ProgressEventProcessor[];
+}
+/**
+ * Progress event filter
+ */
+interface ProgressEventFilter {
+    /** Filter type */
+    readonly type: ProgressEventType$1 | 'custom';
+    /** Filter predicate */
+    readonly predicate: (event: ProgressEvent) => boolean;
+}
+/**
+ * Progress event processor
+ */
+interface ProgressEventProcessor {
+    /** Processor name */
+    readonly name: string;
+    /** Process function */
+    readonly process: (event: ProgressEvent) => Promise<void>;
+}
+/**
+ * Default error recovery configuration
+ */
+declare const DEFAULT_ERROR_RECOVERY_CONFIG: ErrorRecoveryConfig;
+/**
+ * Default rate limit handling configuration
+ */
+declare const DEFAULT_RATE_LIMIT_CONFIG: RateLimitHandlingConfig;
+/**
+ * Default progress tracking configuration
+ */
+declare const DEFAULT_PROGRESS_CONFIG: ProgressTrackingConfig;
+/**
+ * Main execution engine class for orchestrating AI task execution
+ *
+ * This class manages the complete execution lifecycle including:
+ * - Session creation and management
+ * - Iteration loop with rate limit handling
+ * - Progress tracking and statistics collection
+ * - Error handling with recovery strategies
+ * - Cancellation and cleanup
+ *
+ * @example
+ * ```typescript
+ * const engine = createExecutionEngine(await loadConfig());
+ *
+ * const request: ExecutionRequest = {
+ *   requestId: 'req-123',
+ *   instruction: 'Implement a new feature',
+ *   subagent: 'claude',
+ *   workingDirectory: '/path/to/project',
+ *   maxIterations: 10,
+ * };
+ *
+ * const result = await engine.execute(request);
+ * ```
+ */
+declare class ExecutionEngine extends EventEmitter {
+    private readonly engineConfig;
+    private readonly activeExecutions;
+    private readonly progressCallbacks;
+    private readonly cleanupTasks;
+    private isShuttingDown;
+    private currentBackend;
+    /**
+     * Create a new ExecutionEngine instance
+     *
+     * @param config - Engine configuration
+     */
+    constructor(config: ExecutionEngineConfig);
+    /**
+     * Execute a task request with comprehensive orchestration
+     *
+     * @param request - Execution request parameters
+     * @param abortSignal - Optional abort signal for cancellation
+     * @returns Promise resolving to execution result
+     */
+    execute(request: ExecutionRequest, abortSignal?: AbortSignal): Promise<ExecutionResult>;
+    /**
+     * Add a progress callback for all executions
+     *
+     * @param callback - Progress callback function
+     * @returns Cleanup function to remove the callback
+     */
+    onProgress(callback: ProgressCallback): () => void;
+    /**
+     * Get current rate limit information
+     *
+     * @returns Current rate limit status
+     */
+    getRateLimitInfo(): Promise<RateLimitInfo>;
+    /**
+     * Cancel all active executions and shutdown gracefully
+     *
+     * @param timeoutMs - Maximum time to wait for cleanup
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
+    /**
+     * Get statistics for all executions
+     *
+     * @returns Aggregate execution statistics
+     */
+    getExecutionStatistics(): ExecutionStatistics;
+    /**
+     * Setup error handling for the engine
+     */
+    private setupErrorHandling;
+    /**
+     * Setup progress tracking for the engine
+     */
+    private setupProgressTracking;
+    /**
+     * Display hook execution output to stderr at verbose level 2 (debug+hooks).
+     * At level 2: shows hook name, command stdout/stderr output.
+     * At level 0-1: output is suppressed (hooks still execute).
+     */
+    private displayHookOutput;
+    /**
+     * Initialize backend for execution request.
+     * Directly creates and configures a ShellBackend (no factory indirection).
+     */
+    private initializeBackend;
+    /**
+     * Validate execution request parameters
+     */
+    private validateRequest;
+    /**
+     * Create execution context for a request
+     */
+    private createExecutionContext;
+    /**
+     * Create initial statistics object
+     */
+    private createInitialStatistics;
+    /**
+     * Create session context for execution
+     */
+    private createSessionContext;
+    /**
+     * Internal execution implementation
+     */
+    private executeInternal;
+    /**
+     * Run the main iteration loop
+     */
+    private runIterationLoop;
+    /**
+     * Execute a single iteration
+     * @returns QuotaLimitInfo if a quota limit was detected, null otherwise
+     */
+    private executeIteration;
+    /**
+     * Handle rate limit errors with automatic retry
+     */
+    private handleRateLimit;
+    /**
+     * Calculate wait time for rate limit reset
+     */
+    private calculateRateLimitWaitTime;
+    /**
+     * Handle Claude quota limit with automatic sleep and retry
+     * @returns true if we should retry the iteration, false otherwise
+     */
+    private handleQuotaLimit;
+    /**
+     * Sleep with periodic progress updates
+     */
+    private sleepWithProgress;
+    /**
+     * Check if tool result indicates a quota limit error
+     */
+    private extractQuotaLimitInfo;
+    /**
+     * Handle iteration errors with recovery strategies
+     */
+    private handleIterationError;
+    /**
+     * Process individual progress events
+     */
+    private processProgressEvent;
+    /**
+     * Update execution statistics
+     */
+    private updateStatistics;
+    /**
+     * Update performance metrics
+     */
+    private updatePerformanceMetrics;
+    /**
+     * Check if iteration loop should stop
+     */
+    private shouldStopIterating;
+    /**
+     * Check abort signal and throw if aborted
+     */
+    private checkAbortSignal;
+    /**
+     * Get tool name for subagent
+     */
+    private getToolNameForSubagent;
+    /**
+     * Wrap unknown errors as execution errors
+     */
+    private wrapError;
+    /**
+     * Determine execution status from error
+     */
+    private determineErrorStatus;
+    /**
+     * Create final execution result
+     */
+    private createExecutionResult;
+    /**
+     * Cancel an execution
+     */
+    private cancelExecution;
+    /**
+     * Cleanup execution resources
+     */
+    private cleanupExecution;
+    /**
+     * Calculate average iteration duration across contexts
+     */
+    private calculateAverageIterationDuration;
+    /**
+     * Aggregate error breakdown across contexts
+     */
+    private aggregateErrorBreakdown;
+    /**
+     * Calculate performance metrics across contexts
+     */
+    private calculatePerformanceMetrics;
+    /**
+     * Sleep utility for delays
+     */
+    private sleep;
+}
+/**
+ * Create an execution engine with default configuration
+ *
+ * @param config - Base juno-task configuration
+ * @returns Configured execution engine
+ */
+declare function createExecutionEngine(config: JunoTaskConfig): ExecutionEngine;
+/**
+ * Create an execution request with defaults
+ *
+ * @param options - Request options
+ * @returns Execution request
+ */
+declare function createExecutionRequest(options: {
+    instruction: string;
+    subagent?: SubagentType;
+    backend?: BackendType;
+    workingDirectory?: string;
+    maxIterations?: number;
+    model?: string;
+    agents?: string;
+    tools?: string[];
+    allowedTools?: string[];
+    appendAllowedTools?: string[];
+    disallowedTools?: string[];
+    requestId?: string;
+    mcpServerName?: string;
+    resume?: string;
+    continueConversation?: boolean;
+    thinking?: string;
+}): ExecutionRequest;
+
+/** Session metadata */
+interface SessionInfo {
+    id: string;
+    name?: string;
+    status: SessionStatus;
+    subagent: SubagentType;
+    createdAt: Date;
+    updatedAt: Date;
+    completedAt?: Date;
+    workingDirectory: string;
+    config: Partial<JunoTaskConfig>;
+    tags: string[];
+    metadata: Record<string, any>;
+}
+/** Session statistics - essential counters only */
+interface SessionStatistics {
+    duration: number;
+    iterations: number;
+    toolCalls: number;
+    errorCount: number;
+}
+/** Complete session state */
+interface Session {
+    info: SessionInfo;
+    context: {
+        workingDirectory: string;
+        config: JunoTaskConfig;
+    };
+    statistics: SessionStatistics;
+    history: SessionHistoryEntry[];
+    result?: {
+        success: boolean;
+        output?: string;
+        error?: string;
+        finalState?: any;
+    };
+}
+/** History entry for conversation tracking */
+interface SessionHistoryEntry {
+    id: string;
+    timestamp: Date;
+    type: 'prompt' | 'response' | 'tool_call' | 'error' | 'system';
+    content: string;
+    data?: any;
+    duration?: number;
+    iteration?: number;
+}
+/** Persistence layer abstraction */
+interface SessionStorage {
+    saveSession(session: Session): Promise<void>;
+    loadSession(sessionId: string): Promise<Session | null>;
+    listSessions(filter?: SessionListFilter): Promise<SessionInfo[]>;
+    removeSession(sessionId: string): Promise<void>;
+    sessionExists(sessionId: string): Promise<boolean>;
+    cleanup(options: CleanupOptions): Promise<void>;
+}
+/** Filter criteria for listing sessions */
+interface SessionListFilter {
+    status?: SessionStatus[];
+    subagent?: SubagentType[];
+    dateRange?: {
+        start?: Date;
+        end?: Date;
+    };
+    tags?: string[];
+    limit?: number;
+    offset?: number;
+    sortBy?: 'createdAt' | 'updatedAt' | 'name';
+    sortOrder?: 'asc' | 'desc';
+}
+/** Options for storage cleanup */
+interface CleanupOptions {
+    removeEmpty?: boolean;
+    removeOlderThanDays?: number;
+    removeStatus?: SessionStatus[];
+    dryRun?: boolean;
+}
+/** File-based session storage implementation */
+declare class FileSessionStorage implements SessionStorage {
+    private readonly baseDir;
+    private readonly sessionsDir;
+    constructor(baseDir: string);
+    initialize(): Promise<void>;
+    private getSessionPath;
+    saveSession(session: Session): Promise<void>;
+    loadSession(sessionId: string): Promise<Session | null>;
+    listSessions(filter?: SessionListFilter): Promise<SessionInfo[]>;
+    removeSession(sessionId: string): Promise<void>;
+    sessionExists(sessionId: string): Promise<boolean>;
+    cleanup(options: CleanupOptions): Promise<void>;
+}
+/** Session manager - plain class for session lifecycle management */
+declare class SessionManager {
+    private storage;
+    private activeSessions;
+    constructor(storage: SessionStorage);
+    createSession(options: {
+        name?: string;
+        subagent: SubagentType;
+        config: JunoTaskConfig;
+        tags?: string[];
+        metadata?: Record<string, any>;
+    }): Promise<Session>;
+    updateSession(sessionId: string, updates: {
+        status?: SessionStatus;
+        name?: string;
+        tags?: string[];
+        metadata?: Record<string, any>;
+        statistics?: Partial<SessionStatistics>;
+        result?: Session['result'];
+    }): Promise<void>;
+    completeSession(sessionId: string, result: {
+        success: boolean;
+        output?: string;
+        error?: string;
+        finalState?: any;
+    }): Promise<void>;
+    cancelSession(sessionId: string): Promise<void>;
+    getSession(sessionId: string): Promise<Session | null>;
+    listSessions(filter?: SessionListFilter): Promise<SessionInfo[]>;
+    removeSession(sessionId: string): Promise<void>;
+    cleanupSessions(options: CleanupOptions): Promise<void>;
+    addHistoryEntry(sessionId: string, entry: Omit<SessionHistoryEntry, 'id' | 'timestamp'>): Promise<void>;
+    updateStatistics(sessionId: string, stats: Partial<SessionStatistics>): Promise<void>;
+    recordToolCall(sessionId: string, toolCall: {
+        name: string;
+        duration: number;
+        success: boolean;
+    }): Promise<void>;
+    getSessionContext(sessionId: string, options?: {
+        includeHistory?: boolean;
+        includeStats?: boolean;
+        maxHistoryEntries?: number;
+    }): Promise<string>;
+    getSessionSummary(sessionId: string): Promise<{
+        info: SessionInfo;
+        statistics: SessionStatistics;
+        summary: {
+            totalDuration: string;
+            iterationsPerMinute: number;
+            toolCallsPerIteration: number;
+            errorRate: number;
+        };
+    } | null>;
+    private formatDuration;
+}
+/** Create a session manager with file storage */
+declare function createSessionManager(config: JunoTaskConfig): Promise<SessionManager>;
+
+/**
+ * Environment Utilities Module for juno-task-ts
+ *
+ * Provides comprehensive environment variable handling and detection utilities
+ * for the juno-task-ts CLI tool. This module includes environment detection,
+ * terminal capabilities, platform information, configuration directories,
+ * and MCP server path detection.
+ *
+ * @module utils/environment
+ */
+/**
+ * Color support levels for terminal output
+ */
+type ColorSupport = 'none' | 'basic' | '256' | 'truecolor';
+/**
+ * Node.js environment types
+ */
+type NodeEnvironment = 'development' | 'production' | 'test';
+/**
+ * Operating system platforms
+ */
+type Platform = 'win32' | 'darwin' | 'linux' | 'freebsd' | 'openbsd' | 'sunos' | 'aix';
+/**
+ * System architectures
+ */
+type Architecture = 'arm' | 'arm64' | 'ia32' | 'mips' | 'mipsel' | 'ppc' | 'ppc64' | 's390' | 's390x' | 'x64';
+/**
+ * Shell types
+ */
+type ShellType = 'bash' | 'zsh' | 'fish' | 'cmd' | 'powershell' | 'unknown';
+/**
+ * Process information interface
+ */
+interface ProcessInfo {
+    pid: number;
+    ppid: number;
+    platform: Platform;
+    arch: Architecture;
+    nodeVersion: string;
+    uptime: number;
+    cwd: string;
+    execPath: string;
+    argv: string[];
+    env: Record<string, string | undefined>;
+}
+/**
+ * Memory usage information
+ */
+interface MemoryUsage {
+    rss: number;
+    heapTotal: number;
+    heapUsed: number;
+    external: number;
+    arrayBuffers: number;
+}
+/**
+ * CPU usage information
+ */
+interface CpuUsage {
+    user: number;
+    system: number;
+}
+/**
+ * MCP server environment configuration
+ */
+interface MCPServerEnvironment {
+    PATH: string;
+    NODE_ENV: string;
+    [key: string]: string;
+}
+/**
+ * Detect if running in a headless/CI environment where interactive prompts should be avoided.
+ * Based on the Python implementation patterns from budi-cli.
+ *
+ * @returns True if running in headless/CI environment
+ *
+ * @example
+ * ```typescript
+ * if (isHeadlessEnvironment()) {
+ *   console.log('Using non-interactive mode');
+ * }
+ * ```
+ */
+declare function isHeadlessEnvironment(): boolean;
+/**
+ * Detect if running in a continuous integration environment.
+ *
+ * @returns True if running in CI environment
+ *
+ * @example
+ * ```typescript
+ * if (isCIEnvironment()) {
+ *   console.log('Running in CI environment');
+ * }
+ * ```
+ */
+declare function isCIEnvironment(): boolean;
+/**
+ * Check if terminal supports interactive input/output.
+ *
+ * @returns True if terminal supports interaction
+ *
+ * @example
+ * ```typescript
+ * if (isInteractiveTerminal()) {
+ *   // Show interactive prompts
+ * }
+ * ```
+ */
+declare function isInteractiveTerminal(): boolean;
+/**
+ * Detect if running in development mode.
+ *
+ * @returns True if in development mode
+ *
+ * @example
+ * ```typescript
+ * if (isDevelopmentMode()) {
+ *   console.log('Debug logging enabled');
+ * }
+ * ```
+ */
+declare function isDevelopmentMode(): boolean;
+/**
+ * Get Node.js environment type.
+ *
+ * @returns The Node.js environment type
+ *
+ * @example
+ * ```typescript
+ * const env = getNodeEnvironment();
+ * console.log(`Running in ${env} mode`);
+ * ```
+ */
+declare function getNodeEnvironment(): NodeEnvironment;
+/**
+ * Get environment variable with optional type conversion.
+ *
+ * @param key - Environment variable name
+ * @param defaultValue - Default value if variable is not set
+ * @returns Environment variable value or default
+ *
+ * @example
+ * ```typescript
+ * const port = getEnvVar('PORT', '3000');
+ * const timeout = getEnvVar('TIMEOUT', '30');
+ * ```
+ */
+declare function getEnvVar(key: string, defaultValue?: string): string | undefined;
+/**
+ * Get environment variable with fallback value.
+ *
+ * @param key - Environment variable name
+ * @param defaultValue - Default value if variable is not set
+ * @returns Environment variable value or default
+ *
+ * @example
+ * ```typescript
+ * const logLevel = getEnvVarWithDefault('LOG_LEVEL', 'info');
+ * ```
+ */
+declare function getEnvVarWithDefault(key: string, defaultValue: string): string;
+/**
+ * Set environment variable safely.
+ *
+ * @param key - Environment variable name
+ * @param value - Value to set
+ *
+ * @example
+ * ```typescript
+ * setEnvVar('DEBUG', 'true');
+ * ```
+ */
+declare function setEnvVar(key: string, value: string): void;
+/**
+ * Parse boolean value from environment variable string.
+ *
+ * @param value - Environment variable value
+ * @param defaultValue - Default boolean value
+ * @returns Parsed boolean value
+ *
+ * @example
+ * ```typescript
+ * const isVerbose = parseEnvBoolean(process.env.VERBOSE, false);
+ * const isEnabled = parseEnvBoolean('true'); // returns true
+ * ```
+ */
+declare function parseEnvBoolean(value: string | undefined, defaultValue?: boolean): boolean;
+/**
+ * Parse number value from environment variable string.
+ *
+ * @param value - Environment variable value
+ * @param defaultValue - Default number value
+ * @returns Parsed number value
+ *
+ * @example
+ * ```typescript
+ * const port = parseEnvNumber(process.env.PORT, 3000);
+ * const timeout = parseEnvNumber('30'); // returns 30
+ * ```
+ */
+declare function parseEnvNumber(value: string | undefined, defaultValue?: number): number;
+/**
+ * Parse array from delimited environment variable string.
+ *
+ * @param value - Environment variable value
+ * @param delimiter - Delimiter to split on
+ * @param defaultValue - Default array value
+ * @returns Parsed array
+ *
+ * @example
+ * ```typescript
+ * const paths = parseEnvArray(process.env.SEARCH_PATHS, ':', []);
+ * const hosts = parseEnvArray('host1,host2,host3', ','); // returns ['host1', 'host2', 'host3']
+ * ```
+ */
+declare function parseEnvArray(value: string | undefined, delimiter?: string, defaultValue?: string[]): string[];
+/**
+ * Get terminal width for formatting output.
+ *
+ * @returns Terminal width in columns
+ *
+ * @example
+ * ```typescript
+ * const width = getTerminalWidth();
+ * console.log(`Terminal width: ${width} columns`);
+ * ```
+ */
+declare function getTerminalWidth(): number;
+/**
+ * Get terminal height for formatting output.
+ *
+ * @returns Terminal height in rows
+ *
+ * @example
+ * ```typescript
+ * const height = getTerminalHeight();
+ * console.log(`Terminal height: ${height} rows`);
+ * ```
+ */
+declare function getTerminalHeight(): number;
+/**
+ * Check if terminal supports color output.
+ *
+ * @returns True if terminal supports colors
+ *
+ * @example
+ * ```typescript
+ * if (supportsColor()) {
+ *   console.log('\x1b[32mGreen text\x1b[0m');
+ * }
+ * ```
+ */
+declare function supportsColor(): boolean;
+/**
+ * Get color capability level of the terminal.
+ *
+ * @returns Color support level
+ *
+ * @example
+ * ```typescript
+ * const colorSupport = getColorSupport();
+ * if (colorSupport === 'truecolor') {
+ *   // Use RGB colors
+ * }
+ * ```
+ */
+declare function getColorSupport(): ColorSupport;
+/**
+ * Detect if running inside a Docker container.
+ *
+ * @returns True if running in Docker
+ *
+ * @example
+ * ```typescript
+ * if (isInDocker()) {
+ *   console.log('Running in Docker container');
+ * }
+ * ```
+ */
+declare function isInDocker(): boolean;
+/**
+ * Get operating system platform information.
+ *
+ * @returns Platform information
+ *
+ * @example
+ * ```typescript
+ * const platform = getPlatform();
+ * console.log(`Running on ${platform}`);
+ * ```
+ */
+declare function getPlatform(): Platform;
+/**
+ * Get system architecture information.
+ *
+ * @returns System architecture
+ *
+ * @example
+ * ```typescript
+ * const arch = getArchitecture();
+ * console.log(`System architecture: ${arch}`);
+ * ```
+ */
+declare function getArchitecture(): Architecture;
+/**
+ * Detect user's shell (bash, zsh, fish, etc.).
+ *
+ * @returns Detected shell type
+ *
+ * @example
+ * ```typescript
+ * const shell = getShell();
+ * console.log(`User shell: ${shell}`);
+ * ```
+ */
+declare function getShell(): ShellType;
+/**
+ * Get user home directory path.
+ *
+ * @returns User home directory path
+ *
+ * @example
+ * ```typescript
+ * const home = getHomeDirectory();
+ * console.log(`Home directory: ${home}`);
+ * ```
+ */
+declare function getHomeDirectory(): string;
+/**
+ * Get system temporary directory path.
+ *
+ * @returns System temp directory path
+ *
+ * @example
+ * ```typescript
+ * const temp = getTempDirectory();
+ * console.log(`Temp directory: ${temp}`);
+ * ```
+ */
+declare function getTempDirectory(): string;
+/**
+ * Get user configuration directory path.
+ * Follows XDG Base Directory specification on Unix systems.
+ *
+ * @param appName - Application name for subdirectory
+ * @returns Configuration directory path
+ *
+ * @example
+ * ```typescript
+ * const configDir = getConfigDirectory('juno-task');
+ * // Returns: ~/.config/juno-task (Linux), ~/Library/Application Support/juno-task (macOS), etc.
+ * ```
+ */
+declare function getConfigDirectory(appName?: string): string;
+/**
+ * Get user data directory path.
+ *
+ * @param appName - Application name for subdirectory
+ * @returns Data directory path
+ *
+ * @example
+ * ```typescript
+ * const dataDir = getDataDirectory('juno-task');
+ * ```
+ */
+declare function getDataDirectory(appName?: string): string;
+/**
+ * Get user cache directory path.
+ *
+ * @param appName - Application name for subdirectory
+ * @returns Cache directory path
+ *
+ * @example
+ * ```typescript
+ * const cacheDir = getCacheDirectory('juno-task');
+ * ```
+ */
+declare function getCacheDirectory(appName?: string): string;
+/**
+ * Create directory if it doesn't exist.
+ *
+ * @param dirPath - Directory path to create
+ * @returns Promise that resolves when directory is created
+ *
+ * @example
+ * ```typescript
+ * await createDirectoryIfNotExists('/path/to/config');
+ * ```
+ */
+declare function createDirectoryIfNotExists(dirPath: string): Promise<void>;
+/**
+ * Get current process information.
+ *
+ * @returns Process information object
+ *
+ * @example
+ * ```typescript
+ * const info = getProcessInfo();
+ * console.log(`Process ID: ${info.pid}`);
+ * ```
+ */
+declare function getProcessInfo(): ProcessInfo;
+/**
+ * Check if running with root/administrator privileges.
+ *
+ * @returns True if running as root
+ *
+ * @example
+ * ```typescript
+ * if (isRunningAsRoot()) {
+ *   console.warn('Running with elevated privileges');
+ * }
+ * ```
+ */
+declare function isRunningAsRoot(): boolean;
+/**
+ * Get process memory usage information.
+ *
+ * @returns Memory usage information
+ *
+ * @example
+ * ```typescript
+ * const memory = getMemoryUsage();
+ * console.log(`Heap used: ${(memory.heapUsed / 1024 / 1024).toFixed(2)} MB`);
+ * ```
+ */
+declare function getMemoryUsage(): MemoryUsage;
+/**
+ * Get CPU usage information.
+ *
+ * @returns CPU usage information
+ *
+ * @example
+ * ```typescript
+ * const cpu = getCpuUsage();
+ * console.log(`User CPU time: ${cpu.user}μs`);
+ * ```
+ */
+declare function getCpuUsage(): CpuUsage;
+/**
+ * Auto-discover MCP server location.
+ * Searches common installation paths and PATH environment variable.
+ *
+ * @param serverName - MCP server executable name
+ * @returns Promise that resolves to server path or null if not found
+ *
+ * @example
+ * ```typescript
+ * const serverPath = await findMCPServerPath('mcp-server');
+ * if (serverPath) {
+ *   console.log(`Found MCP server at: ${serverPath}`);
+ * }
+ * ```
+ */
+declare function findMCPServerPath(serverName?: string): Promise<string | null>;
+/**
+ * Verify MCP server path is executable.
+ *
+ * @param serverPath - Path to MCP server executable
+ * @returns Promise that resolves to true if valid and executable
+ *
+ * @example
+ * ```typescript
+ * const isValid = await validateMCPServerPath('/usr/local/bin/mcp-server');
+ * if (isValid) {
+ *   console.log('MCP server is valid and executable');
+ * }
+ * ```
+ */
+declare function validateMCPServerPath(serverPath: string): Promise<boolean>;
+/**
+ * Get environment configuration for MCP server.
+ *
+ * @param additionalEnv - Additional environment variables
+ * @returns MCP server environment configuration
+ *
+ * @example
+ * ```typescript
+ * const env = getMCPServerEnvironment({ DEBUG: 'true' });
+ * console.log('MCP server environment:', env);
+ * ```
+ */
+declare function getMCPServerEnvironment(additionalEnv?: Record<string, string>): MCPServerEnvironment;
+
+declare enum LogContext {
+    CLI = "CLI",
+    MCP = "MCP",
+    ENGINE = "ENGINE",
+    SESSION = "SESSION",
+    TEMPLATE = "TEMPLATE",
+    CONFIG = "CONFIG",
+    PERFORMANCE = "PERFORMANCE",
+    SYSTEM = "SYSTEM"
+}
+
+/**
+ * Hook execution utility module for juno-task-ts
+ *
+ * Provides robust hook execution functionality with comprehensive logging,
+ * error handling, and execution context tracking.
+ *
+ * @module utils/hooks
+ */
+
+/**
+ * Supported hook types for lifecycle execution
+ */
+type HookType = 'START_RUN' | 'START_ITERATION' | 'END_ITERATION' | 'END_RUN' | 'ON_STALE';
+/**
+ * Hook configuration interface
+ */
+interface Hook {
+    /** List of bash commands to execute for this hook */
+    commands: string[];
+}
+/**
+ * Complete hooks configuration mapping hook types to their configurations
+ */
+interface HooksConfig {
+    [key: string]: Hook;
+}
+/**
+ * Execution context for hooks - provides information about the current execution state
+ */
+interface HookExecutionContext {
+    /** Current iteration number (for iteration-based hooks) */
+    iteration?: number;
+    /** Session ID for tracking */
+    sessionId?: string;
+    /** Working directory for command execution */
+    workingDirectory?: string;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+    /** Run ID for tracking across hooks */
+    runId?: string;
+    /** Total iterations planned */
+    totalIterations?: number;
+}
+/**
+ * Result of a single command execution within a hook
+ */
+interface CommandExecutionResult {
+    /** The command that was executed */
+    command: string;
+    /** Exit code (0 for success) */
+    exitCode: number;
+    /** Standard output */
+    stdout: string;
+    /** Standard error output */
+    stderr: string;
+    /** Execution duration in milliseconds */
+    duration: number;
+    /** Whether the command succeeded */
+    success: boolean;
+    /** Error if execution failed */
+    error?: Error;
+}
+/**
+ * Result of executing all commands in a hook
+ */
+interface HookExecutionResult {
+    /** Hook type that was executed */
+    hookType: HookType;
+    /** Total execution duration for all commands */
+    totalDuration: number;
+    /** Results for each command */
+    commandResults: CommandExecutionResult[];
+    /** Overall success (true if all commands succeeded) */
+    success: boolean;
+    /** Number of commands executed */
+    commandsExecuted: number;
+    /** Number of commands that failed */
+    commandsFailed: number;
+}
+/**
+ * Hook execution options
+ */
+interface HookExecutionOptions {
+    /** Maximum timeout per command in milliseconds (default: 300000 = 5 minutes) */
+    commandTimeout?: number | undefined;
+    /** Environment variables to pass to commands */
+    env?: Record<string, string> | undefined;
+    /** Whether to continue executing commands if one fails (default: true) */
+    continueOnError?: boolean | undefined;
+    /** Custom logger context (default: 'SYSTEM') */
+    logContext?: LogContext | undefined;
+}
+/**
+ * Execute a specific hook type with the provided context
+ *
+ * This is the main entry point for hook execution. It handles:
+ * - Hook existence validation
+ * - Sequential command execution
+ * - Comprehensive logging with execution context
+ * - Robust error handling (log but don't throw)
+ * - Performance tracking
+ *
+ * @param hookType - The type of hook to execute
+ * @param hooks - The complete hooks configuration
+ * @param context - Execution context with iteration, session info, etc.
+ * @param options - Additional execution options
+ * @returns Promise that resolves when all commands complete (never throws)
+ *
+ * @example
+ * ```typescript
+ * const hooks = {
+ *   START_ITERATION: {
+ *     commands: ['echo "Starting iteration $ITERATION"', 'npm test']
+ *   }
+ * };
+ *
+ * const context = {
+ *   iteration: 1,
+ *   sessionId: 'session-123',
+ *   workingDirectory: '/path/to/project'
+ * };
+ *
+ * await executeHook('START_ITERATION', hooks, context);
+ * ```
+ */
+declare function executeHook(hookType: HookType, hooks: HooksConfig, context?: HookExecutionContext, options?: HookExecutionOptions): Promise<HookExecutionResult>;
+/**
+ * Execute multiple hooks in sequence
+ *
+ * Convenience function for executing multiple hooks with the same context.
+ * Each hook is executed independently - failure of one hook does not stop
+ * execution of subsequent hooks.
+ *
+ * @param hookTypes - Array of hook types to execute
+ * @param hooks - The complete hooks configuration
+ * @param context - Execution context
+ * @param options - Execution options
+ * @returns Promise resolving to array of hook execution results
+ */
+declare function executeHooks(hookTypes: HookType[], hooks: HooksConfig, context?: HookExecutionContext, options?: HookExecutionOptions): Promise<HookExecutionResult[]>;
+/**
+ * Validate hooks configuration
+ *
+ * Checks that all hook configurations are valid and provides warnings
+ * for common issues.
+ *
+ * @param hooks - Hooks configuration to validate
+ * @returns Validation result with any issues found
+ */
+declare function validateHooksConfig(hooks: HooksConfig): {
+    valid: boolean;
+    issues: string[];
+    warnings: string[];
+};
+
+/**
+ * Validation Utilities Module for juno-code
+ *
+ * Provides Zod-based validation for configuration values.
+ *
+ * @module utils/validation
+ */
+
+/**
+ * Schema for validating subagent types with alias support
+ */
+declare const SubagentSchema: z.ZodEffects<z.ZodEffects<z.ZodString, "claude" | "cursor" | "codex" | "gemini" | "pi", string>, SubagentType, string>;
+/**
+ * Schema for validating log levels
+ */
+declare const LogLevelSchema: z.ZodEnum<["error", "warn", "info", "debug", "trace"]>;
+/**
+ * Schema for validating session status
+ */
+declare const SessionStatusSchema: z.ZodEnum<["running", "completed", "failed", "cancelled"]>;
+/**
+ * Schema for validating iteration counts
+ */
+declare const IterationsSchema: z.ZodEffects<z.ZodEffects<z.ZodNumber, number, number>, number, number>;
+/**
+ * Schema for validating model names (subagent-specific)
+ */
+declare const ModelSchema: z.ZodEffects<z.ZodString, string, string>;
+/**
+ * Schema for runtime configuration validation
+ */
+declare const ConfigValidationSchema: z.ZodObject<{
+    defaultSubagent: z.ZodEnum<["claude", "cursor", "codex", "gemini", "pi"]>;
+    defaultBackend: z.ZodEnum<["shell"]>;
+    defaultMaxIterations: z.ZodNumber;
+    defaultModel: z.ZodOptional<z.ZodString>;
+    mainTask: z.ZodOptional<z.ZodString>;
+    logLevel: z.ZodEnum<["error", "warn", "info", "debug", "trace"]>;
+    logFile: z.ZodOptional<z.ZodString>;
+    verbose: z.ZodEffects<z.ZodNumber, number, unknown>;
+    quiet: z.ZodBoolean;
+    mcpTimeout: z.ZodNumber;
+    mcpRetries: z.ZodNumber;
+    mcpServerPath: z.ZodOptional<z.ZodString>;
+    mcpServerName: z.ZodOptional<z.ZodString>;
+    hookCommandTimeout: z.ZodOptional<z.ZodNumber>;
+    onHourlyLimit: z.ZodEnum<["wait", "raise"]>;
+    interactive: z.ZodBoolean;
+    headlessMode: z.ZodBoolean;
+    workingDirectory: z.ZodString;
+    sessionDirectory: z.ZodString;
+    envFilePath: z.ZodOptional<z.ZodString>;
+    envFileCopied: z.ZodOptional<z.ZodBoolean>;
+    hooks: z.ZodOptional<z.ZodRecord<z.ZodEnum<["START_RUN", "START_ITERATION", "END_ITERATION", "END_RUN", "ON_STALE"]>, z.ZodObject<{
+        commands: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        commands?: string[];
+    }, {
+        commands?: string[];
+    }>>>;
+    skipHooks: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    defaultSubagent?: "claude" | "cursor" | "codex" | "gemini" | "pi";
+    defaultBackend?: "shell";
+    defaultMaxIterations?: number;
+    defaultModel?: string;
+    logLevel?: "error" | "warn" | "info" | "debug" | "trace";
+    logFile?: string;
+    verbose?: number;
+    quiet?: boolean;
+    mcpTimeout?: number;
+    mcpRetries?: number;
+    mcpServerPath?: string;
+    mcpServerName?: string;
+    hookCommandTimeout?: number;
+    onHourlyLimit?: "wait" | "raise";
+    interactive?: boolean;
+    headlessMode?: boolean;
+    workingDirectory?: string;
+    sessionDirectory?: string;
+    mainTask?: string;
+    envFilePath?: string;
+    envFileCopied?: boolean;
+    hooks?: Partial<Record<"START_RUN" | "START_ITERATION" | "END_ITERATION" | "END_RUN" | "ON_STALE", {
+        commands?: string[];
+    }>>;
+    skipHooks?: boolean;
+}, {
+    defaultSubagent?: "claude" | "cursor" | "codex" | "gemini" | "pi";
+    defaultBackend?: "shell";
+    defaultMaxIterations?: number;
+    defaultModel?: string;
+    logLevel?: "error" | "warn" | "info" | "debug" | "trace";
+    logFile?: string;
+    verbose?: unknown;
+    quiet?: boolean;
+    mcpTimeout?: number;
+    mcpRetries?: number;
+    mcpServerPath?: string;
+    mcpServerName?: string;
+    hookCommandTimeout?: number;
+    onHourlyLimit?: "wait" | "raise";
+    interactive?: boolean;
+    headlessMode?: boolean;
+    workingDirectory?: string;
+    sessionDirectory?: string;
+    mainTask?: string;
+    envFilePath?: string;
+    envFileCopied?: boolean;
+    hooks?: Partial<Record<"START_RUN" | "START_ITERATION" | "END_ITERATION" | "END_RUN" | "ON_STALE", {
+        commands?: string[];
+    }>>;
+    skipHooks?: boolean;
+}>;
+/**
+ * Validate and normalize subagent names including aliases
+ */
+declare function validateSubagent(subagent: string): SubagentType;
+/**
+ * Validate model names for specific subagents
+ */
+declare function validateModel(model: string, _subagent?: SubagentType): string;
+/**
+ * Validate iteration counts (positive integers or -1 for infinite)
+ */
+declare function validateIterations(iterations: number): number;
+/**
+ * Validate log level strings
+ */
+declare function validateLogLevel(logLevel: string): LogLevel;
+/**
+ * Environment variable validation
+ */
+declare function validateEnvironmentVars(envVars: Record<string, string | undefined>): Partial<JunoTaskConfig>;
+
+/**
+ * Version information for juno-task-ts
+ */
+declare const version: string;
+
+export { type Architecture, type BackendType, type CleanupOptions, type ColorSupport, type CommandExecutionResult, type ConfigLoadOptions, ConfigLoader, ConfigValidationSchema, type CpuUsage, DEFAULT_CONFIG, DEFAULT_ERROR_RECOVERY_CONFIG, DEFAULT_HOOKS, DEFAULT_PROGRESS_CONFIG, DEFAULT_RATE_LIMIT_CONFIG, ENV_VAR_MAPPING, type EnvVarMapping, type ErrorRecoveryConfig, ExecutionEngine, type ExecutionEngineConfig, type ExecutionRequest, type ExecutionResult, type ExecutionStatistics, ExecutionStatus, FileSessionStorage, type Hook$1 as Hook, type HookExecutionContext, type HookExecutionOptions, type HookExecutionResult, type HookType$1 as HookType, type Hooks, type HooksConfig, type IterationResult, IterationsSchema, type JunoTaskConfig, JunoTaskConfigSchema, type LogLevel, LogLevelSchema, type MCPServerEnvironment, type MemoryUsage, ModelSchema, type NodeEnvironment, type OnHourlyLimit, type PerformanceMetrics, type Platform, type ProcessInfo, type ProgressEventFilter, type ProgressEventProcessor, type ProgressEventType$1 as ProgressEventType, type ProgressTrackingConfig, type RateLimitHandlingConfig, type RateLimitInfo, type RateLimitParser, type Session, type SessionHistoryEntry, type SessionInfo, type SessionListFilter, SessionManager, type SessionStatistics, type SessionStatus, SessionStatusSchema, type SessionStorage, type ShellType, SubagentSchema, type SubagentType, type ThroughputMetrics, createDirectoryIfNotExists, createExecutionEngine, createExecutionRequest, createSessionManager, executeHook, executeHooks, findMCPServerPath, getArchitecture, getCacheDirectory, getColorSupport, getConfigDirectory, getCpuUsage, getDataDirectory, getDefaultHooks, getDefaultHooksJson, getEnvVar, getEnvVarWithDefault, getHomeDirectory, getMCPServerEnvironment, getMemoryUsage, getNodeEnvironment, getPlatform, getProcessInfo, getShell, getTempDirectory, getTerminalHeight, getTerminalWidth, isCIEnvironment, isDevelopmentMode, isHeadlessEnvironment, isInDocker, isInteractiveTerminal, isRunningAsRoot, loadConfig, parseEnvArray, parseEnvBoolean, parseEnvNumber, setEnvVar, supportsColor, validateConfig, validateEnvironmentVars, validateHooksConfig, validateIterations, validateLogLevel, validateMCPServerPath, validateModel, validateSubagent, version };