@defai.digital/ax-cli 4.1.10 → 4.1.14

package/dist/sdk/index.js

@@ -1,54 +1,116 @@
 /**
- * AX CLI SDK - Programmatic API for AX CLI
+ * AX CLI SDK v1.4.0 - Programmatic API for AX CLI
  *
- * This SDK allows you to use AX CLI as a library instead of spawning CLI processes.
- * Perfect for integrations, VSCode extensions, and programmatic AI agent usage.
+ * Use AX CLI as a library for integrations, VSCode extensions, and programmatic AI agents.
+ *
+ * ## Installation
+ *
+ * ```bash
+ * npm install @defai.digital/ax-cli
+ * ```
  *
  * ## Quick Start
  *
- * 1. Run `ax-cli setup` to configure credentials (one-time setup)
- * 2. Use the SDK in your code
+ * ```typescript
+ * import { createAgent, createGLMAgent, createGrokAgent } from '@defai.digital/ax-cli/sdk';
+ *
+ * // Option 1: Auto-detect provider
+ * const agent = await createAgent();
+ *
+ * // Option 2: Explicit provider
+ * const glmAgent = await createGLMAgent();   // Uses ~/.ax-glm/config.json
+ * const grokAgent = await createGrokAgent(); // Uses ~/.ax-grok/config.json
+ *
+ * // Process messages
+ * const result = await agent.processUserMessage('Analyze this code');
+ * agent.dispose();
+ * ```
+ *
+ * ## Public API (v1.4.0)
+ *
+ * ### Agent Creation
+ * - `createAgent(options?)` - Create agent with auto-detected or specified provider
+ * - `createGLMAgent(options?)` - Create GLM (Z.AI) agent
+ * - `createGrokAgent(options?)` - Create Grok (xAI) agent
+ * - `tryCreateAgent(options?)` - Create agent without throwing (returns result object)
+ * - `withAgent(fn, options?)` - Run function with auto-disposed agent
+ *
+ * ### Error Handling
+ * - `SDKError` - Structured error class with error codes
+ * - `SDKErrorCode` - Error code enum (SETUP_NOT_RUN, API_KEY_MISSING, etc.)
+ *
+ * ### Agent Utilities
+ * - `getAgentInfo(agent)` - Get provider, model, config info
+ * - `getAgentStatus(agent)` - Check if agent is available/busy/disposed
+ * - `isAgentDisposed(agent)` - Check disposal state
+ * - `disposeAsync(agent)` - Dispose with async hook support
+ *
+ * ### Provider Utilities
+ * - `detectProvider()` - Auto-detect configured provider
+ * - `checkProviderHealth(provider?)` - Check if provider is configured
+ * - `getAllProviderHealth()` - Check all providers
+ *
+ * ### Version Info
+ * - `SDK_VERSION`, `CLI_VERSION` - Version constants
+ * - `getSDKVersion()`, `getCLIVersion()` - Version strings
+ * - `isSDKVersionCompatible(minVersion)` - Version check
+ *
+ * ### Testing
+ * - `createMockAgent(responses)` - Create mock for testing
+ * - `createMockSettings(overrides)` - Mock settings manager
+ *
+ * ## Example: Streaming Responses
  *
- * @example
  * ```typescript
- * import { createAgent, SDKError, SDKErrorCode } from '@defai.digital/ax-cli/sdk';
+ * import { createGLMAgent, SDKError, SDKErrorCode } from '@defai.digital/ax-cli/sdk';
  *
- * // Create agent (credentials from ax-cli setup)
- * const agent = await createAgent({
- *   maxToolRounds: 50  // Optional: 1-1000, default 400
+ * const agent = await createGLMAgent();
+ *
+ * agent.on('stream', (chunk) => {
+ *   if (chunk.type === 'content') {
+ *     process.stdout.write(chunk.content);
+ *   }
  * });
  *
  * try {
- *   // Listen to streaming responses
- *   agent.on('stream', (chunk) => {
- *     if (chunk.type === 'content') {
- *       console.log(chunk.content);
- *     }
- *   });
- *
- *   // Process messages
- *   const result = await agent.processUserMessage('List all TypeScript files');
- *   console.log('Done!', result.length, 'messages');
+ *   await agent.processUserMessage('Explain async/await');
  * } catch (error) {
- *   // Handle structured errors
  *   if (SDKError.isSDKError(error)) {
- *     if (error.code === SDKErrorCode.SETUP_NOT_RUN) {
- *       console.error('Please run: ax-cli setup');
- *     }
+ *     console.error(`Error [${error.code}]: ${error.message}`);
  *   }
  * } finally {
- *   // Always cleanup resources
  *   agent.dispose();
  * }
  * ```
  *
- * ## Testing
+ * ## Example: Parallel Providers
+ *
+ * ```typescript
+ * import { createGLMAgent, createGrokAgent } from '@defai.digital/ax-cli/sdk';
+ *
+ * // Run GLM and Grok in parallel
+ * const [glm, grok] = await Promise.all([
+ *   createGLMAgent(),
+ *   createGrokAgent(),
+ * ]);
+ *
+ * const [glmResult, grokResult] = await Promise.all([
+ *   glm.processUserMessage('Analyze with GLM'),
+ *   grok.processUserMessage('Analyze with Grok'),
+ * ]);
+ *
+ * glm.dispose();
+ * grok.dispose();
+ * ```
+ *
+ * ## Example: Testing
  *
  * ```typescript
- * import { createMockAgent } from '@defai.digital/ax-cli/sdk/testing';
+ * import { createMockAgent } from '@defai.digital/ax-cli/sdk';
  *
- * const mockAgent = createMockAgent(['Response 1', 'Response 2']);
- * const result = await mockAgent.processUserMessage('Test');
+ * const mock = createMockAgent(['Hello!', 'How can I help?']);
+ * const result = await mock.processUserMessage('Hi');
+ * expect(result).toContain('Hello!');
  * ```
  *
  * @packageDocumentation
@@ -63,80 +125,36 @@ export { ContextManager } from '../agent/context-manager.js';
 // Internal imports for SDK functions
 import { LLMAgent } from '../agent/llm-agent.js';
 import { Subagent } from '../agent/subagent.js';
-import { getSettingsManager } from '../utils/settings-manager.js';
 import { initializeMCPServers } from '../llm/tools.js';
 import { z } from 'zod';
 import { SDKError, SDKErrorCode } from './errors.js';
+// Provider-aware imports
+import { ProviderContext, detectProvider, PROVIDER_CONFIGS, } from '../utils/provider-context.js';
+import { ProviderSettingsManager, } from '../utils/provider-settings.js';
+// File locking utilities - re-exported for SDK users
+export { withFileLock, withFileLockSync, SafeJsonFile, LockGuard, cleanupStaleLocks, } from '../utils/file-lock.js';
 // ============================================================================
 // LLM Client
 // ============================================================================
 export { LLMClient } from '../llm/client.js';
 export { SubagentRole, SubagentState, } from '../agent/subagent-types.js';
 // ============================================================================
-// Settings and Configuration
-// ============================================================================
-export { getSettingsManager } from '../utils/settings-manager.js';
+// NOTE: Internal utilities removed in SDK v1.4.0 to reduce API surface
 // ============================================================================
-// Utilities
-// ============================================================================
-export { createTokenCounter } from '../utils/token-counter.js';
-export { loadCustomInstructions } from '../utils/custom-instructions.js';
-export { buildSystemPrompt } from '../utils/prompt-builder.js';
-export { getUsageTracker } from '../utils/usage-tracker.js';
-export { extractErrorMessage, createErrorMessage, ErrorCategory } from '../utils/error-handler.js';
-// ============================================================================
-// MCP Integration
-// ============================================================================
-export { loadMCPConfig } from '../mcp/config.js';
-export { getMCPManager, initializeMCPServers, getMcpConnectionCount, getMCPConnectionStatus, getMCPPrompts, discoverMCPPrompts, getMCPResources, } from '../llm/tools.js';
-export { MCPManager } from '../mcp/client.js';
-// MCP v2 API (recommended for better type safety)
-export { MCPManagerV2, createServerName, createToolName, } from '../mcp/client-v2.js';
-// MCP Prompt utilities
-export { promptToSlashCommand, parsePromptCommand, formatPromptResult, getPromptDescription, } from '../mcp/prompts.js';
-// MCP Resource utilities
-export { listAllResources, getResourceContent, parseMCPReference, extractMCPReferences, resolveMCPReferences, searchResources, } from '../mcp/resources.js';
-// Z.AI MCP Integration
-export { 
-// Server configuration
-ZAI_SERVER_NAMES, ZAI_ENDPOINTS, ZAI_VISION_PACKAGE, ZAI_MCP_TEMPLATES, ZAI_QUOTA_LIMITS, generateZAIServerConfig, getAllZAIServerNames, isZAIServer, getZAITemplate, } from '../mcp/zai-templates.js';
-export { 
-// Detection and status
-detectZAIServices, getEnabledZAIServers, validateZAIApiKey, getZAIApiKey, isZAIMCPConfigured, getRecommendedServers, isGLMModel, isZAIBaseURL, formatZAIStatus, } from '../mcp/zai-detector.js';
-// Permission system
-export { getPermissionManager, initializePermissionManager, PermissionManager, PermissionTier, } from '../permissions/permission-manager.js';
-// ============================================================================
-// Planning System
-// ============================================================================
-export { getTaskPlanner, isComplexRequest } from '../planner/index.js';
-// ============================================================================
-// Checkpoint System
-// ============================================================================
-export { getCheckpointManager } from '../checkpoint/index.js';
-// ============================================================================
-// Memory and Context Cache
-// ============================================================================
-export { ContextStore, getContextStore, resetDefaultStore } from '../memory/context-store.js';
-// ============================================================================
-// Progress Reporting
-// ============================================================================
-export { ProgressReporter, getProgressReporter, ProgressEventType } from './progress-reporter.js';
-// ============================================================================
-// Unified Logging (Phase 3)
-// ============================================================================
-export { UnifiedLogger, getUnifiedLogger, LogLevel, parseLogLevel, getLogLevelName } from './unified-logger.js';
-// ============================================================================
-// Shared Tool Registry (Phase 3 - AutomatosX Integration)
-// ============================================================================
-export { ToolRegistry, getToolRegistry, registerTools, createToolExecutor } from './tool-registry.js';
-// ============================================================================
-// Internal Tool Registry (Phase 2 - Task 5)
-// ============================================================================
-export { ToolRegistry as InternalToolRegistry } from '../tools/registry.js';
-// ============================================================================
-// Constants
-// ============================================================================
-export { GLM_MODELS, DEFAULT_MODEL, AGENT_CONFIG, PLANNER_CONFIG, VerbosityLevel, UI_CONFIG, } from '../constants.js';
+// The following were intentionally removed from public exports:
+// - Settings utilities (getSettingsManager, createTokenCounter, etc.)
+// - MCP internals (MCPManager, MCPManagerV2, etc.) - use createAgent() instead
+// - Z.AI MCP templates/detector - internal implementation details
+// - Permission system internals
+// - Planning system internals
+// - Checkpoint system internals
+// - Memory/Context internals
+// - Progress reporting
+// - Unified logging
+// - Tool registry internals
+//
+// If you need these, import directly from the specific modules.
+// The SDK public API focuses on: createAgent, createGLMAgent, createGrokAgent, SDKError
 // ============================================================================
 // SDK Version (Phase 1.5: Best Practices)
 // ============================================================================
@@ -149,14 +167,17 @@ export { SDKError, SDKErrorCode } from './errors.js';
 // Testing Utilities (Phase 1: Best Practices)
 // ============================================================================
 export { MockAgent, createMockAgent, MockSettingsManager, createMockSettings, MockMCPServer, createMockMCPServer, waitForAgent, createMockToolResult, assertToolSuccess, assertToolFailure } from './testing.js';
-// ============================================================================
-// SDK Helper Functions
-// ============================================================================
+// Re-export detectProvider for advanced users who need provider detection
+export { detectProvider } from '../utils/provider-context.js';
+// Note: Internal utilities (withFileLock, SafeJsonFile, ProviderFileCache,
+// ProviderContextStore, etc.) are intentionally NOT exported.
+// These are implementation details, not part of the public SDK API.
 /**
  * Validation schema for agent options
  * @internal
  */
 const AgentOptionsSchema = z.object({
+    provider: z.enum(['glm', 'grok', 'generic']).optional(),
     maxToolRounds: z.number().int().min(1).max(1000).optional(),
     debug: z.boolean().optional(),
     autoCleanup: z.boolean().optional(),
@@ -176,6 +197,7 @@ const AgentOptionsSchema = z.object({
  * @throws {SDKError} With code SETUP_NOT_RUN if ax-cli setup has not been run
  * @throws {SDKError} With code API_KEY_MISSING if API key not configured
  * @throws {SDKError} With code BASE_URL_MISSING if base URL not configured
+ * @throws {SDKError} With code MODEL_MISSING if model not configured
  * @throws {SDKError} With code VALIDATION_ERROR if options are invalid
  *
  * @example
@@ -224,24 +246,40 @@ export async function createAgent(options = {}) {
     catch (error) {
         throw new SDKError(SDKErrorCode.VALIDATION_ERROR, `Invalid agent options: ${error instanceof Error ? error.message : 'Unknown validation error'}`, error instanceof Error ? error : undefined);
     }
-    const settingsManager = getSettingsManager();
-    // Load settings from ax-cli setup
+    // Determine provider (explicit > auto-detect)
+    const provider = validated.provider ?? detectProvider();
+    // Create provider context WITHOUT activating globally
+    // This is critical for parallel agent support - each agent gets its own context
+    // without affecting the global state that other agents might be using
+    const providerContext = ProviderContext.create(provider);
+    // Get provider-specific settings manager using the context
+    const providerSettings = ProviderSettingsManager.forContext(providerContext);
+    // Load settings from provider-specific config
     try {
-        settingsManager.loadUserSettings();
+        providerSettings.loadUserSettings();
     }
     catch (error) {
-        throw new SDKError(SDKErrorCode.SETUP_NOT_RUN, 'ax-cli setup has not been run. Please run "ax-cli setup" to configure your API key, model, and base URL before using the SDK.', error instanceof Error ? error : undefined);
+        const cliName = PROVIDER_CONFIGS[provider].cliName;
+        throw new SDKError(SDKErrorCode.SETUP_NOT_RUN, `${cliName} setup has not been run. Please run "${cliName} setup" to configure your API key, model, and base URL before using the SDK.`, error instanceof Error ? error : undefined);
     }
-    // Get configuration ONLY from settings (security requirement)
-    const apiKey = settingsManager.getApiKey();
-    const model = settingsManager.getCurrentModel();
-    const baseURL = settingsManager.getBaseURL();
+    // Get configuration from provider-specific settings
+    const apiKey = providerSettings.getApiKey();
+    const model = providerSettings.getCurrentModel();
+    const baseURL = providerSettings.getBaseURL();
     // Validate required settings exist
+    const cliName = PROVIDER_CONFIGS[provider].cliName;
     if (!apiKey) {
-        throw new SDKError(SDKErrorCode.API_KEY_MISSING, 'No API key configured. Please run "ax-cli setup" to configure your credentials.');
+        throw new SDKError(SDKErrorCode.API_KEY_MISSING, `No API key configured for ${provider}. Please run "${cliName} setup" to configure your credentials.`);
     }
     if (!baseURL) {
-        throw new SDKError(SDKErrorCode.BASE_URL_MISSING, 'No base URL configured. Please run "ax-cli setup" to configure your API provider.');
+        throw new SDKError(SDKErrorCode.BASE_URL_MISSING, `No base URL configured for ${provider}. Please run "${cliName} setup" to configure your API provider.`);
+    }
+    // BUG FIX: Validate model is configured before creating agent
+    // Without this, undefined model would fall back to getSettingsManager().getCurrentModel()
+    // which uses the OLD singleton-based settings manager, not the provider-aware one.
+    // This could cause the agent to use a different model in multi-provider scenarios.
+    if (!model) {
+        throw new SDKError(SDKErrorCode.MODEL_MISSING, `No model configured for ${provider}. Please run "${cliName} setup" to configure your AI model.`);
     }
     // Apply defaults for optional values
     const maxToolRounds = validated.maxToolRounds; // undefined is valid, LLMAgent uses 400 as default
@@ -252,6 +290,8 @@ export async function createAgent(options = {}) {
     // Debug logging
     if (debug) {
         console.error('[AX SDK DEBUG] Creating agent with settings:');
+        console.error('[AX SDK DEBUG]   Provider:', provider);
+        console.error('[AX SDK DEBUG]   Config dir:', providerContext.userDir);
         console.error('[AX SDK DEBUG]   Model:', model);
         console.error('[AX SDK DEBUG]   Base URL:', baseURL);
         console.error('[AX SDK DEBUG]   Max tool rounds:', maxToolRounds ?? 400);
@@ -262,13 +302,25 @@ export async function createAgent(options = {}) {
             onError: !!onError
         });
     }
-    // Create agent instance with settings from ax-cli setup
+    // Create agent instance with provider-specific settings
     const agent = new LLMAgent(apiKey, baseURL, model, maxToolRounds);
+    // Store provider context on agent for later use
+    agent._sdkProvider = provider;
+    agent._sdkProviderContext = providerContext;
+    agent._sdkProviderSettings = providerSettings;
+    // Store the actual model and baseURL used at creation time
+    // This prevents getAgentInfo from returning wrong values if config changes
+    agent._sdkModel = model;
+    agent._sdkBaseURL = baseURL;
+    // Store creation timestamp for debugging and lifecycle tracking
+    agent._sdkCreatedAt = new Date();
     // Store lifecycle hooks on agent
     agent._sdkLifecycleHooks = {
         onDispose,
         onError
     };
+    // Store debug flag so disposeAsync can access it for logging
+    agent._sdkDebug = debug;
     // BUG FIX: Track SDK-added listeners so they can be removed on dispose
     // Without this, listeners would persist after disposal causing memory leaks
     const sdkListeners = [];
@@ -320,14 +372,23 @@ export async function createAgent(options = {}) {
     // Without this, calling dispose() multiple times would run cleanup logic and
     // onDispose hook multiple times, which could cause errors or unexpected behavior
     let sdkDisposeCompleted = false;
+    // Store a reliable disposed flag that works regardless of autoCleanup setting
+    agent._sdkDisposed = false;
     // Phase 3: Wrap dispose() to call onDispose hook
     const originalDispose = agent.dispose.bind(agent);
+    // Store original dispose on agent so disposeAsync can access it
+    agent._sdkOriginalDispose = originalDispose;
     agent.dispose = () => {
         // BUG FIX: Guard against double disposal in SDK wrapper
-        if (sdkDisposeCompleted) {
+        // Check BOTH the closure variable AND the agent property
+        // This handles the case where disposeAsync() was called first (sets _sdkDisposed)
+        // or where dispose() was called first (sets sdkDisposeCompleted)
+        if (sdkDisposeCompleted || agent._sdkDisposed === true) {
             return;
         }
         sdkDisposeCompleted = true;
+        // Set the reliable disposed flag (works regardless of autoCleanup)
+        agent._sdkDisposed = true;
         // Mark as disposed in SDK internal state to prevent auto-cleanup from running again
         const markDisposed = agent._sdkMarkDisposed;
         if (markDisposed) {
@@ -422,20 +483,183 @@ export async function createAgent(options = {}) {
     }
     return agent;
 }
+/**
+ * Create an agent configured for GLM (Z.AI)
+ *
+ * Convenience function that creates an agent with provider: 'glm'.
+ * Uses configuration from ~/.ax-glm/config.json.
+ *
+ * @param options - Agent options (provider is set to 'glm')
+ * @returns Configured LLM Agent for GLM
+ *
+ * @example
+ * ```typescript
+ * const agent = await createGLMAgent();
+ * const result = await agent.processUserMessage('Hello');
+ * agent.dispose();
+ * ```
+ */
+export async function createGLMAgent(options = {}) {
+    return createAgent({ ...options, provider: 'glm' });
+}
+/**
+ * Create an agent configured for Grok (xAI)
+ *
+ * Convenience function that creates an agent with provider: 'grok'.
+ * Uses configuration from ~/.ax-grok/config.json.
+ *
+ * @param options - Agent options (provider is set to 'grok')
+ * @returns Configured LLM Agent for Grok
+ *
+ * @example
+ * ```typescript
+ * const agent = await createGrokAgent();
+ * const result = await agent.processUserMessage('Hello');
+ * agent.dispose();
+ * ```
+ */
+export async function createGrokAgent(options = {}) {
+    return createAgent({ ...options, provider: 'grok' });
+}
+/**
+ * Create an agent without throwing errors
+ *
+ * Unlike createAgent(), this function returns a result object instead of throwing.
+ * Useful for graceful error handling without try-catch blocks.
+ *
+ * @param options - Agent configuration options
+ * @returns Result object with either agent or error
+ *
+ * @example
+ * ```typescript
+ * const result = await tryCreateAgent({ provider: 'glm' });
+ *
+ * if (result.success) {
+ *   // Use agent
+ *   await result.agent.processUserMessage('Hello');
+ *   result.agent.dispose();
+ * } else {
+ *   // Handle error without try-catch
+ *   console.error('Failed:', result.error.code, result.error.message);
+ * }
+ * ```
+ */
+export async function tryCreateAgent(options = {}) {
+    try {
+        const agent = await createAgent(options);
+        return { success: true, agent, error: undefined };
+    }
+    catch (error) {
+        const sdkError = SDKError.isSDKError(error)
+            ? error
+            : new SDKError(SDKErrorCode.INTERNAL_ERROR, error instanceof Error ? error.message : 'Unknown error creating agent', error instanceof Error ? error : undefined);
+        return { success: false, agent: undefined, error: sdkError };
+    }
+}
+/**
+ * Run a function with a temporary agent that is automatically disposed
+ *
+ * This helper creates an agent, runs your function, and ensures the agent
+ * is properly disposed even if an error occurs. Useful for:
+ * - One-off agent operations
+ * - Scripts that need cleanup guarantees
+ * - Testing scenarios
+ *
+ * @param fn - Function to run with the agent
+ * @param options - Agent configuration options
+ * @returns Result of the function
+ *
+ * @example
+ * ```typescript
+ * // Simple usage
+ * const result = await withAgent(async (agent) => {
+ *   return await agent.processUserMessage('Analyze this code');
+ * });
+ *
+ * // With options
+ * const result = await withAgent(
+ *   async (agent) => {
+ *     agent.on('stream', console.log);
+ *     return await agent.processUserMessage('Hello');
+ *   },
+ *   { provider: 'glm', maxToolRounds: 50 }
+ * );
+ * ```
+ */
+export async function withAgent(fn, options = {}) {
+    const agent = await createAgent(options);
+    try {
+        return await fn(agent);
+    }
+    finally {
+        // Use disposeAsync to properly await any async onDispose hooks
+        await disposeAsync(agent);
+    }
+}
+/**
+ * Run a function with a temporary agent, returning result or error
+ *
+ * Combines withAgent and tryCreateAgent - creates agent, runs function,
+ * disposes, and returns result without throwing. Ideal for error-tolerant
+ * workflows.
+ *
+ * @param fn - Function to run with the agent
+ * @param options - Agent configuration options
+ * @returns Result object with either value or error
+ *
+ * @example
+ * ```typescript
+ * const result = await tryWithAgent(async (agent) => {
+ *   return await agent.processUserMessage('Hello');
+ * }, { provider: 'grok' });
+ *
+ * if (result.success) {
+ *   console.log('Got response:', result.value);
+ * } else {
+ *   console.error('Failed:', result.error.message);
+ * }
+ * ```
+ */
+export async function tryWithAgent(fn, options = {}) {
+    const createResult = await tryCreateAgent(options);
+    if (!createResult.success) {
+        return { success: false, value: undefined, error: createResult.error };
+    }
+    try {
+        const value = await fn(createResult.agent);
+        return { success: true, value, error: undefined };
+    }
+    catch (error) {
+        const sdkError = SDKError.isSDKError(error)
+            ? error
+            : new SDKError(SDKErrorCode.INTERNAL_ERROR, error instanceof Error ? error.message : 'Unknown error during agent operation', error instanceof Error ? error : undefined);
+        return { success: false, value: undefined, error: sdkError };
+    }
+    finally {
+        await disposeAsync(createResult.agent);
+    }
+}
 /**
  * Create a specialized subagent for specific tasks
  *
  * @param role - The role/specialty of the subagent
- * @param config - Optional configuration overrides
+ * @param options - Optional configuration including provider
  * @returns Configured Subagent instance
  *
  * @example
  * ```typescript
+ * // Basic usage
  * const testAgent = createSubagent(SubagentRole.TESTING, {
  *   maxToolRounds: 20,
  *   priority: 2
  * });
  *
+ * // With provider for parallel support
+ * const glmSubagent = createSubagent(SubagentRole.ANALYSIS, {
+ *   provider: 'glm',
+ *   maxToolRounds: 30
+ * });
+ *
  * const result = await testAgent.execute({
  *   id: 'task-1',
  *   description: 'Write unit tests for auth module',
@@ -443,16 +667,33 @@ export async function createAgent(options = {}) {
  * });
  * ```
  */
-export function createSubagent(role, config) {
+export function createSubagent(role, options) {
     // BUG FIX: Clone config to prevent external mutation affecting the subagent
     // Without this, the caller could modify config.allowedTools array after creation
     // and unexpectedly change which tools the subagent can use
-    const clonedConfig = config ? {
-        ...config,
-        // Deep clone arrays to prevent mutation
-        allowedTools: config.allowedTools ? [...config.allowedTools] : undefined,
-    } : undefined;
-    return new Subagent(role, clonedConfig);
+    let clonedConfig;
+    if (options) {
+        // BUG FIX: Use destructuring to exclude provider instead of setting undefined
+        // Setting `provider: undefined` explicitly could cause issues if Subagent
+        // constructor checks for presence of `provider` key vs undefined value
+        const { provider: _provider, allowedTools, ...rest } = options;
+        clonedConfig = {
+            ...rest,
+            // Deep clone arrays to prevent mutation
+            allowedTools: allowedTools ? [...allowedTools] : undefined,
+        };
+    }
+    // Create subagent
+    const subagent = new Subagent(role, clonedConfig);
+    // Store provider context if specified for later use
+    if (options?.provider) {
+        const providerContext = ProviderContext.create(options.provider);
+        const providerSettings = ProviderSettingsManager.forContext(providerContext);
+        subagent._sdkProvider = options.provider;
+        subagent._sdkProviderContext = providerContext;
+        subagent._sdkProviderSettings = providerSettings;
+    }
+    return subagent;
 }
 /**
  * Remove auto-cleanup handlers from an agent
@@ -531,4 +772,501 @@ export async function initializeSDK() {
     // Initialize MCP servers from settings configured via ax-cli setup
     await initializeMCPServers();
 }
+/**
+ * Get information about an agent created with createAgent()
+ *
+ * This function extracts the provider, model, and configuration information
+ * from an agent instance. Useful for debugging, logging, and multi-provider
+ * scenarios where you need to know which provider an agent is using.
+ *
+ * @param agent - The agent instance created with createAgent()
+ * @returns AgentInfo object with provider/model details, or null if not SDK-created
+ *
+ * @example
+ * ```typescript
+ * const glmAgent = await createAgent({ provider: 'glm' });
+ * const grokAgent = await createAgent({ provider: 'grok' });
+ *
+ * const glmInfo = getAgentInfo(glmAgent);
+ * console.log(glmInfo?.provider);  // 'glm'
+ * console.log(glmInfo?.model);     // 'glm-4.6'
+ *
+ * const grokInfo = getAgentInfo(grokAgent);
+ * console.log(grokInfo?.provider); // 'grok'
+ * console.log(grokInfo?.model);    // 'grok-3'
+ * ```
+ */
+export function getAgentInfo(agent) {
+    const provider = agent._sdkProvider;
+    const providerContext = agent._sdkProviderContext;
+    // BUG FIX: Use stored model/baseURL from creation time, not from settings
+    // Settings could change after agent creation, giving wrong info
+    const model = agent._sdkModel;
+    const baseURL = agent._sdkBaseURL;
+    // BUG FIX: Use the reliable _sdkDisposed flag instead of _sdkIsDisposed function
+    // _sdkIsDisposed only exists when autoCleanup: true, but _sdkDisposed is always set
+    const isDisposed = agent._sdkDisposed;
+    const createdAt = agent._sdkCreatedAt;
+    if (!provider || !providerContext || !createdAt) {
+        // Not created via SDK createAgent()
+        return null;
+    }
+    const config = PROVIDER_CONFIGS[provider];
+    return {
+        provider,
+        providerDisplayName: config.displayName,
+        model,
+        baseURL,
+        isDisposed: isDisposed ?? false,
+        configDir: providerContext.userDir,
+        cliName: config.cliName,
+        createdAt,
+    };
+}
+/**
+ * Get the model an agent is using
+ *
+ * Quick accessor to get just the model name from an SDK-created agent.
+ * Returns undefined if the agent was not created via createAgent().
+ *
+ * @param agent - The agent instance
+ * @returns The model name or undefined
+ *
+ * @example
+ * ```typescript
+ * const agent = await createAgent({ provider: 'glm' });
+ * console.log(getAgentModel(agent)); // 'glm-4.6'
+ * ```
+ */
+export function getAgentModel(agent) {
+    return agent._sdkModel;
+}
+/**
+ * Get the base URL an agent is using
+ *
+ * Quick accessor to get just the base URL from an SDK-created agent.
+ * Returns undefined if the agent was not created via createAgent().
+ *
+ * @param agent - The agent instance
+ * @returns The base URL or undefined
+ *
+ * @example
+ * ```typescript
+ * const agent = await createAgent({ provider: 'grok' });
+ * console.log(getAgentBaseURL(agent)); // 'https://api.x.ai/v1'
+ * ```
+ */
+export function getAgentBaseURL(agent) {
+    return agent._sdkBaseURL;
+}
+/**
+ * Get the provider an agent is using
+ *
+ * Quick accessor to get just the provider type from an SDK-created agent.
+ * Returns undefined if the agent was not created via createAgent().
+ *
+ * @param agent - The agent instance
+ * @returns The provider type or undefined
+ *
+ * @example
+ * ```typescript
+ * const agent = await createAgent({ provider: 'glm' });
+ * console.log(getAgentProvider(agent)); // 'glm'
+ * ```
+ */
+export function getAgentProvider(agent) {
+    return agent._sdkProvider;
+}
+/**
+ * Get when an agent was created
+ *
+ * Quick accessor to get the creation timestamp from an SDK-created agent.
+ * Useful for logging, monitoring, and debugging agent lifecycle.
+ * Returns undefined if the agent was not created via createAgent().
+ *
+ * @param agent - The agent instance
+ * @returns The creation Date or undefined
+ *
+ * @example
+ * ```typescript
+ * const agent = await createAgent();
+ * console.log(getAgentCreatedAt(agent)); // Date object
+ * ```
+ */
+export function getAgentCreatedAt(agent) {
+    return agent._sdkCreatedAt;
+}
+/**
+ * Get how long an agent has been running (age in milliseconds)
+ *
+ * Returns the time elapsed since the agent was created. Useful for:
+ * - Monitoring long-running agents
+ * - Implementing agent timeouts
+ * - Debugging performance issues
+ * - Logging agent lifecycle metrics
+ *
+ * @param agent - The agent instance
+ * @returns Age in milliseconds, or undefined if not SDK-created
+ *
+ * @example
+ * ```typescript
+ * const agent = await createAgent();
+ *
+ * // ... some work ...
+ *
+ * const ageMs = getAgentAge(agent);
+ * if (ageMs !== undefined) {
+ *   console.log(`Agent running for ${Math.round(ageMs / 1000)}s`);
+ *
+ *   // Implement timeout
+ *   if (ageMs > 5 * 60 * 1000) { // 5 minutes
+ *     console.warn('Agent running too long, disposing');
+ *     agent.dispose();
+ *   }
+ * }
+ * ```
+ */
+export function getAgentAge(agent) {
+    const createdAt = agent._sdkCreatedAt;
+    if (!createdAt) {
+        return undefined;
+    }
+    return Date.now() - createdAt.getTime();
+}
+/**
+ * Format agent age as human-readable string
+ *
+ * Convenience function to get agent age as a formatted string.
+ * Returns undefined if agent was not created via createAgent().
+ *
+ * @param agent - The agent instance
+ * @returns Formatted age string (e.g., "1m 30s", "2h 15m"), or undefined
+ *
+ * @example
+ * ```typescript
+ * const agent = await createAgent();
+ * // ... work ...
+ * console.log(`Agent age: ${formatAgentAge(agent)}`); // "Agent age: 1m 30s"
+ * ```
+ */
+export function formatAgentAge(agent) {
+    const ageMs = getAgentAge(agent);
+    if (ageMs === undefined) {
+        return undefined;
+    }
+    const seconds = Math.floor(ageMs / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    if (hours > 0) {
+        const remainingMinutes = minutes % 60;
+        return `${hours}h ${remainingMinutes}m`;
+    }
+    else if (minutes > 0) {
+        const remainingSeconds = seconds % 60;
+        return `${minutes}m ${remainingSeconds}s`;
+    }
+    else {
+        return `${seconds}s`;
+    }
+}
+/**
+ * Check if an agent is busy (bash executing) or disposed
+ *
+ * This function provides a quick check to determine if an agent is available
+ * to process new messages. An agent is considered "busy" if:
+ * - It has been disposed (cannot be used at all)
+ * - It is currently executing a bash command
+ *
+ * Useful for:
+ * - Pre-flight checks before sending messages
+ * - Implementing request queuing
+ * - Health monitoring dashboards
+ *
+ * @param agent - The agent instance to check
+ * @returns Object with availability status
+ *
+ * @example
+ * ```typescript
+ * const agent = await createAgent();
+ *
+ * // Check before processing
+ * const status = getAgentStatus(agent);
+ * if (!status.available) {
+ *   console.log('Agent not available:', status.reason);
+ *   return;
+ * }
+ *
+ * await agent.processUserMessage('Hello');
+ * ```
+ */
+export function getAgentStatus(agent) {
+    const disposed = isAgentDisposed(agent);
+    const isBusy = typeof agent.isBashExecuting === 'function'
+        ? agent.isBashExecuting()
+        : false;
+    const isDisposed = disposed === true;
+    const available = !isDisposed && !isBusy;
+    let reason;
+    if (isDisposed) {
+        reason = 'Agent has been disposed';
+    }
+    else if (isBusy) {
+        reason = 'Agent is currently executing bash command';
+    }
+    return {
+        available,
+        isDisposed,
+        isBusy,
+        reason,
+        ageMs: getAgentAge(agent),
+    };
+}
+/**
+ * Check if a provider is properly configured and ready to use
+ *
+ * This function validates that a provider has all required configuration
+ * (API key, base URL, model) without actually creating an agent or making
+ * API calls. Useful for:
+ * - Pre-flight checks before creating agents
+ * - Setup wizards and configuration UIs
+ * - Health checks in long-running services
+ *
+ * @param provider - Provider to check (defaults to auto-detect)
+ * @returns ProviderHealthResult with configuration status
+ *
+ * @example
+ * ```typescript
+ * // Check specific provider
+ * const glmHealth = checkProviderHealth('glm');
+ * if (!glmHealth.healthy) {
+ *   console.error('GLM not configured:', glmHealth.message);
+ *   console.log('Run: ax-glm setup');
+ * }
+ *
+ * // Check all providers
+ * const providers: ProviderType[] = ['glm', 'grok'];
+ * for (const p of providers) {
+ *   const health = checkProviderHealth(p);
+ *   console.log(`${p}: ${health.healthy ? '✓' : '✗'} ${health.message}`);
+ * }
+ * ```
+ */
+export function checkProviderHealth(provider) {
+    const targetProvider = provider ?? detectProvider();
+    const config = PROVIDER_CONFIGS[targetProvider];
+    const settings = ProviderSettingsManager.forProvider(targetProvider);
+    const hasApiKey = !!settings.getApiKey();
+    const hasBaseURL = !!settings.getBaseURL();
+    const hasModel = !!settings.getCurrentModel();
+    const issues = [];
+    if (!hasApiKey)
+        issues.push('API key missing');
+    if (!hasBaseURL)
+        issues.push('Base URL missing');
+    if (!hasModel)
+        issues.push('Model not set');
+    const healthy = hasApiKey && hasBaseURL && hasModel;
+    let message;
+    if (healthy) {
+        message = `${config.displayName} is configured and ready`;
+    }
+    else {
+        message = `${config.displayName} needs configuration: ${issues.join(', ')}`;
+    }
+    return {
+        healthy,
+        provider: targetProvider,
+        hasApiKey,
+        hasBaseURL,
+        hasModel,
+        message,
+        error: healthy ? undefined : `Run "${config.cliName} setup" to configure`,
+    };
+}
+/**
+ * Get health status for all supported providers
+ *
+ * @returns Array of health results for all providers
+ *
+ * @example
+ * ```typescript
+ * const allHealth = getAllProviderHealth();
+ * const configured = allHealth.filter(h => h.healthy);
+ * console.log(`${configured.length} providers ready`);
+ * ```
+ */
+export function getAllProviderHealth() {
+    const providers = ['glm', 'grok', 'generic'];
+    return providers.map(p => checkProviderHealth(p));
+}
+// ============================================================================
+// Agent Lifecycle Utilities (v5.1 - High-Value Features)
+// ============================================================================
+/**
+ * Check if an agent has been disposed
+ *
+ * This function provides a reliable way to check if an agent created with
+ * createAgent() has been disposed. Works regardless of the `autoCleanup` setting.
+ *
+ * @param agent - The agent instance to check
+ * @returns true if the agent has been disposed, false otherwise
+ * @returns undefined if the agent was not created via createAgent()
+ *
+ * @example
+ * ```typescript
+ * const agent = await createAgent();
+ * console.log(isAgentDisposed(agent)); // false
+ *
+ * agent.dispose();
+ * console.log(isAgentDisposed(agent)); // true
+ * ```
+ */
+export function isAgentDisposed(agent) {
+    const disposed = agent._sdkDisposed;
+    if (disposed === undefined) {
+        // Not created via SDK createAgent()
+        return undefined;
+    }
+    return disposed;
+}
+/**
+ * Dispose an agent asynchronously, properly awaiting the onDispose hook
+ *
+ * The standard `agent.dispose()` is synchronous and fires async onDispose hooks
+ * in a fire-and-forget manner. Use this function when you need to ensure the
+ * onDispose hook completes before continuing.
+ *
+ * @param agent - The agent instance to dispose
+ * @returns Promise that resolves when disposal is complete
+ *
+ * @example
+ * ```typescript
+ * const agent = await createAgent({
+ *   onDispose: async () => {
+ *     await saveState(); // This WILL be awaited with disposeAsync
+ *   }
+ * });
+ *
+ * // ... use agent ...
+ *
+ * // Properly await cleanup
+ * await disposeAsync(agent);
+ * console.log('Cleanup complete, state saved');
+ * ```
+ */
+export async function disposeAsync(agent) {
+    // Get debug flag for logging
+    const debug = agent._sdkDebug;
+    // Check if this is an SDK-created agent
+    const originalDispose = agent._sdkOriginalDispose;
+    if (typeof originalDispose !== 'function') {
+        // Not created via SDK createAgent() - fall back to regular dispose
+        // This is a graceful fallback for non-SDK agents
+        if (debug) {
+            console.error('[AX SDK DEBUG] disposeAsync: Agent not created via createAgent(), using regular dispose');
+        }
+        agent.dispose();
+        return;
+    }
+    // Check if already disposed
+    const disposed = agent._sdkDisposed;
+    if (disposed === true) {
+        if (debug) {
+            console.error('[AX SDK DEBUG] disposeAsync: Agent already disposed, skipping');
+        }
+        return; // Already disposed
+    }
+    // Get the onDispose hook if it exists
+    const hooks = agent._sdkLifecycleHooks;
+    const onDispose = hooks?.onDispose;
+    // Mark as disposed to prevent sync dispose() from running cleanup again
+    agent._sdkDisposed = true;
+    // Also mark the autoCleanup tracker as disposed to prevent signal handlers from triggering
+    const markDisposed = agent._sdkMarkDisposed;
+    if (markDisposed) {
+        markDisposed();
+    }
+    // Call onDispose hook and await if it returns a promise
+    if (onDispose) {
+        try {
+            if (debug) {
+                console.error('[AX SDK DEBUG] disposeAsync: Calling onDispose hook');
+            }
+            const result = onDispose();
+            if (result && typeof result.then === 'function') {
+                await result;
+            }
+            if (debug) {
+                console.error('[AX SDK DEBUG] disposeAsync: onDispose hook completed');
+            }
+        }
+        catch (error) {
+            // Log but don't throw - disposal should complete even if hook fails
+            if (debug) {
+                console.error('[AX SDK DEBUG] disposeAsync: Error in onDispose hook:', error);
+            }
+            // Users should handle errors in their onDispose hook
+        }
+    }
+    // Remove cleanup handlers from process event listeners
+    const cleanupHandler = agent._sdkCleanupHandler;
+    if (cleanupHandler) {
+        process.removeListener('exit', cleanupHandler);
+        process.removeListener('SIGINT', cleanupHandler);
+        process.removeListener('SIGTERM', cleanupHandler);
+        process.removeListener('SIGHUP', cleanupHandler);
+        delete agent._sdkCleanupHandler;
+    }
+    // Remove SDK-added event listeners
+    const listeners = agent._sdkListeners;
+    if (listeners && listeners.length > 0 && typeof agent.off === 'function') {
+        for (const { event, listener } of listeners) {
+            agent.off(event, listener);
+        }
+        delete agent._sdkListeners;
+    }
+    // Call the stored original dispose directly, NOT agent.dispose()
+    // agent.dispose() would call our wrapper which would:
+    // 1. Skip because sdkDisposeCompleted might be false (closure variable)
+    // 2. Or run the full wrapper logic including onDispose hook AGAIN
+    // Instead, call _sdkOriginalDispose which is the unwrapped LLMAgent.dispose()
+    originalDispose();
+    if (debug) {
+        console.error('[AX SDK DEBUG] disposeAsync: Disposal complete');
+    }
+}
+/**
+ * Get information about a subagent created with createSubagent()
+ *
+ * @param subagent - The subagent instance
+ * @returns SubagentInfo object with provider details
+ *
+ * @example
+ * ```typescript
+ * const subagent = createSubagent(SubagentRole.TESTING, { provider: 'glm' });
+ * const info = getSubagentInfo(subagent);
+ * console.log(info.provider); // 'glm'
+ * console.log(info.role);     // SubagentRole.TESTING
+ * ```
+ */
+export function getSubagentInfo(subagent) {
+    const provider = subagent._sdkProvider;
+    const providerContext = subagent._sdkProviderContext;
+    let providerDisplayName;
+    let configDir;
+    let cliName;
+    if (provider && providerContext) {
+        const config = PROVIDER_CONFIGS[provider];
+        providerDisplayName = config.displayName;
+        configDir = providerContext.userDir;
+        cliName = config.cliName;
+    }
+    return {
+        provider,
+        providerDisplayName,
+        configDir,
+        cliName,
+        role: subagent.role,
+    };
+}
 //# sourceMappingURL=index.js.map