@defai.digital/ax-cli 3.6.2 → 3.7.2

package/dist/sdk/errors.js

@@ -0,0 +1,124 @@
+/**
+ * SDK Error Codes for programmatic error handling
+ *
+ * Use these codes to distinguish between different error types
+ * instead of parsing error messages.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await createAgent();
+ * } catch (error) {
+ *   if (error instanceof SDKError) {
+ *     switch (error.code) {
+ *       case SDKErrorCode.SETUP_NOT_RUN:
+ *         console.log('Run ax-cli setup first');
+ *         break;
+ *       case SDKErrorCode.API_KEY_MISSING:
+ *         console.log('API key not configured');
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export var SDKErrorCode;
+(function (SDKErrorCode) {
+    /** ax-cli setup has not been run */
+    SDKErrorCode["SETUP_NOT_RUN"] = "SDK_SETUP_NOT_RUN";
+    /** API key is not configured in settings */
+    SDKErrorCode["API_KEY_MISSING"] = "SDK_API_KEY_MISSING";
+    /** Base URL is not configured in settings */
+    SDKErrorCode["BASE_URL_MISSING"] = "SDK_BASE_URL_MISSING";
+    /** Agent has been disposed and cannot be used */
+    SDKErrorCode["AGENT_DISPOSED"] = "SDK_AGENT_DISPOSED";
+    /** Input validation failed */
+    SDKErrorCode["VALIDATION_ERROR"] = "SDK_VALIDATION_ERROR";
+    /** Operation was aborted by user */
+    SDKErrorCode["ABORTED"] = "SDK_ABORTED";
+    /** Rate limit exceeded */
+    SDKErrorCode["RATE_LIMIT_EXCEEDED"] = "SDK_RATE_LIMIT_EXCEEDED";
+    /** Invalid configuration */
+    SDKErrorCode["INVALID_CONFIG"] = "SDK_INVALID_CONFIG";
+    /** Internal SDK error */
+    SDKErrorCode["INTERNAL_ERROR"] = "SDK_INTERNAL_ERROR";
+})(SDKErrorCode || (SDKErrorCode = {}));
+/**
+ * Structured error class for SDK errors
+ *
+ * Provides error codes for programmatic handling and preserves
+ * error chains for debugging.
+ *
+ * @example
+ * ```typescript
+ * throw new SDKError(
+ *   SDKErrorCode.API_KEY_MISSING,
+ *   'No API key configured. Please run "ax-cli setup".',
+ *   originalError
+ * );
+ * ```
+ */
+export class SDKError extends Error {
+    code;
+    cause;
+    /**
+     * Create a new SDK error
+     *
+     * @param code - Error code for programmatic handling
+     * @param message - Human-readable error message
+     * @param cause - Original error that caused this error (optional)
+     */
+    constructor(code, message, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = 'SDKError';
+        // Maintain proper stack trace in V8 environments
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, SDKError);
+        }
+    }
+    /**
+     * Type guard to check if an error is an SDKError
+     *
+     * @param error - Error to check
+     * @returns True if error is an SDKError
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await createAgent();
+     * } catch (error) {
+     *   if (SDKError.isSDKError(error)) {
+     *     console.log('SDK error:', error.code);
+     *   }
+     * }
+     * ```
+     */
+    static isSDKError(error) {
+        return error instanceof SDKError;
+    }
+    /**
+     * Convert error to JSON (excludes cause to prevent circular refs)
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            // Exclude cause to prevent circular references
+            // and avoid leaking sensitive information
+        };
+    }
+    /**
+     * Custom inspect for Node.js util.inspect
+     */
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        let result = `${this.name} [${this.code}]: ${this.message}`;
+        if (this.cause) {
+            result += `\n  Caused by: ${this.cause.message}`;
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/sdk/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/sdk/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAN,IAAY,YA2BX;AA3BD,WAAY,YAAY;IACtB,oCAAoC;IACpC,mDAAmC,CAAA;IAEnC,4CAA4C;IAC5C,uDAAuC,CAAA;IAEvC,6CAA6C;IAC7C,yDAAyC,CAAA;IAEzC,iDAAiD;IACjD,qDAAqC,CAAA;IAErC,8BAA8B;IAC9B,yDAAyC,CAAA;IAEzC,oCAAoC;IACpC,uCAAuB,CAAA;IAEvB,0BAA0B;IAC1B,+DAA+C,CAAA;IAE/C,4BAA4B;IAC5B,qDAAqC,CAAA;IAErC,yBAAyB;IACzB,qDAAqC,CAAA;AACvC,CAAC,EA3BW,YAAY,KAAZ,YAAY,QA2BvB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IASf;IAEA;IAVlB;;;;;;OAMG;IACH,YACkB,IAAkB,EAClC,OAAe,EACC,KAAa;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAc;QAElB,UAAK,GAAL,KAAK,CAAQ;QAG7B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QAEvB,iDAAiD;QACjD,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,UAAU,CAAC,KAAc;QAC9B,OAAO,KAAK,YAAY,QAAQ,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,+CAA+C;YAC/C,0CAA0C;SAC3C,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,CAAC,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;QACxC,IAAI,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QAC5D,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,kBAAkB,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACnD,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}

package/dist/sdk/index.d.ts

@@ -4,27 +4,51 @@
  * 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.
  *
+ * ## Quick Start
+ *
+ * 1. Run `ax-cli setup` to configure credentials (one-time setup)
+ * 2. Use the SDK in your code
+ *
  * @example
  * ```typescript
- * import { createAgent, getSettingsManager } from '@defai.digital/ax-cli/sdk';
- *
- * // Initialize settings
- * const settings = getSettingsManager();
- * await settings.loadUserSettings();
+ * import { createAgent, SDKError, SDKErrorCode } from '@defai.digital/ax-cli/sdk';
  *
- * // Create agent
+ * // Create agent (credentials from ax-cli setup)
  * const agent = await createAgent({
- *   model: 'glm-4.6',
- *   maxToolRounds: 50
+ *   maxToolRounds: 50  // Optional: 1-1000, default 400
  * });
  *
- * // Listen to streaming responses
- * agent.on('stream', (chunk) => {
- *   console.log(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');
+ * } catch (error) {
+ *   // Handle structured errors
+ *   if (SDKError.isSDKError(error)) {
+ *     if (error.code === SDKErrorCode.SETUP_NOT_RUN) {
+ *       console.error('Please run: ax-cli setup');
+ *     }
+ *   }
+ * } finally {
+ *   // Always cleanup resources
+ *   await agent.dispose();
+ * }
+ * ```
+ *
+ * ## Testing
+ *
+ * ```typescript
+ * import { createMockAgent } from '@defai.digital/ax-cli/sdk/testing';
  *
- * // Process messages
- * const result = await agent.processUserMessage('List all TypeScript files');
+ * const mockAgent = createMockAgent(['Response 1', 'Response 2']);
+ * const result = await mockAgent.processUserMessage('Test');
  * ```
  *
  * @packageDocumentation
@@ -50,47 +74,97 @@ export { buildSystemPrompt } from '../utils/prompt-builder.js';
 export { getUsageTracker } from '../utils/usage-tracker.js';
 export { extractErrorMessage, createErrorMessage, ErrorCategory } from '../utils/error-handler.js';
 export { loadMCPConfig } from '../mcp/config.js';
-export { getMCPManager, initializeMCPServers } from '../llm/tools.js';
+export { getMCPManager, initializeMCPServers, getMcpConnectionCount } from '../llm/tools.js';
 export type { MCPConfig } from '../mcp/config.js';
-export type { MCPServerConfig } from '../mcp/client.js';
+export type { MCPServerConfig, MCPTool } from '../mcp/client.js';
+export { MCPManager } from '../mcp/client.js';
 export { getTaskPlanner, isComplexRequest } from '../planner/index.js';
 export type { TaskPlanner, TaskPlan, TaskPhase, PhaseResult, PlanResult, } from '../planner/index.js';
 export { getCheckpointManager } from '../checkpoint/index.js';
 export type { CheckpointManager, Checkpoint } from '../checkpoint/index.js';
-export { GLM_MODELS, DEFAULT_MODEL, AGENT_CONFIG, PLANNER_CONFIG, type SupportedModel, } from '../constants.js';
+export { ContextStore, getContextStore, resetDefaultStore } from '../memory/context-store.js';
+export type { StoreResult } from '../memory/context-store.js';
+export type { ProjectMemory, CacheStats } from '../memory/types.js';
+export { ProgressReporter, getProgressReporter, ProgressEventType, type ProgressEvent } from './progress-reporter.js';
+export { UnifiedLogger, getUnifiedLogger, LogLevel, parseLogLevel, getLogLevelName, type LogEntry, type LogSource, type LogFilter } from './unified-logger.js';
+export { ToolRegistry, getToolRegistry, registerTools, createToolExecutor, type RegisteredTool, type ToolExecutor, type ToolExecutionContext, type ToolRegistrationOptions } from './tool-registry.js';
+export { GLM_MODELS, DEFAULT_MODEL, AGENT_CONFIG, PLANNER_CONFIG, VerbosityLevel, UI_CONFIG, type SupportedModel, } from '../constants.js';
+export { SDK_VERSION, SDK_API_VERSION, getSDKVersion, getSDKInfo, } from './version.js';
+export { SDKError, SDKErrorCode } from './errors.js';
+export { MockAgent, createMockAgent, MockSettingsManager, createMockSettings, } from './testing.js';
 /**
  * Agent configuration options for SDK users
+ *
+ * SECURITY: Credentials (apiKey, baseURL) must be configured via "ax-cli setup"
+ * and are NOT exposed through the SDK API to prevent security vulnerabilities.
  */
 export interface AgentOptions {
-    /** API key (optional, will use settings if not provided) */
-    apiKey?: string;
-    /** Model to use (optional, will use settings if not provided) */
-    model?: string;
-    /** Base URL for API (optional, will use settings if not provided) */
-    baseURL?: string;
-    /** Maximum number of tool execution rounds */
+    /** Maximum number of tool execution rounds (1-1000, default: 400) */
     maxToolRounds?: number;
+    /**
+     * Enable debug mode for verbose logging
+     *
+     * When enabled, the SDK will log detailed information about:
+     * - Agent initialization
+     * - Message processing
+     * - Tool executions
+     * - Errors and warnings
+     *
+     * Debug logs are written to stderr and prefixed with [AX SDK DEBUG].
+     *
+     * @default false
+     */
+    debug?: boolean;
 }
 /**
  * Create a new LLM Agent with configuration
  *
- * @param options - Agent configuration options
+ * SECURITY: All credentials (API key, base URL, model) must be configured
+ * via "ax-cli setup" command. This prevents security vulnerabilities where
+ * credentials could be exposed in code or logs.
+ *
+ * @param options - Agent configuration options (non-sensitive only)
  * @returns Configured LLM Agent instance
+ * @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 VALIDATION_ERROR if options are invalid
  *
  * @example
  * ```typescript
+ * import { createAgent, SDKError, SDKErrorCode } from '@defai.digital/ax-cli/sdk';
+ *
+ * // First, user must run: ax-cli setup
+ * // Then use SDK with settings from setup:
+ *
  * const agent = await createAgent({
- *   model: 'glm-4.6',
- *   maxToolRounds: 50
+ *   maxToolRounds: 50  // Optional: 1-1000, default 400
  * });
  *
- * agent.on('stream', (chunk) => {
- *   if (chunk.type === 'content') {
- *     console.log(chunk.content);
+ * try {
+ *   agent.on('stream', (chunk) => {
+ *     if (chunk.type === 'content') {
+ *       console.log(chunk.content);
+ *     }
+ *   });
+ *
+ *   const result = await agent.processUserMessage('Analyze this codebase');
+ *   console.log(result);
+ * } catch (error) {
+ *   if (SDKError.isSDKError(error)) {
+ *     switch (error.code) {
+ *       case SDKErrorCode.SETUP_NOT_RUN:
+ *         console.error('Run ax-cli setup first');
+ *         break;
+ *       case SDKErrorCode.API_KEY_MISSING:
+ *         console.error('API key not configured');
+ *         break;
+ *     }
  *   }
- * });
- *
- * const result = await agent.processUserMessage('Analyze this codebase');
+ * } finally {
+ *   // Always cleanup resources
+ *   await agent.dispose();
+ * }
  * ```
  */
 export declare function createAgent(options?: AgentOptions): Promise<LLMAgent>;
@@ -117,22 +191,18 @@ export declare function createAgent(options?: AgentOptions): Promise<LLMAgent>;
  */
 export declare function createSubagent(role: import('../agent/subagent-types.js').SubagentRole, config?: Partial<import('../agent/subagent-types.js').SubagentConfig>): Subagent;
 /**
- * Initialize SDK with configuration
+ * Initialize SDK and MCP servers
  *
- * @param config - SDK initialization configuration
+ * SECURITY: This function does NOT accept credentials. All credentials must be
+ * configured via "ax-cli setup" command. This function only initializes MCP servers.
  *
  * @example
  * ```typescript
- * await initializeSDK({
- *   apiKey: 'your-api-key',
- *   model: 'glm-4.6',
- *   baseURL: 'https://api.example.com/v1'
- * });
+ * // Initialize MCP servers from ax-cli settings
+ * await initializeSDK();
  * ```
+ *
+ * @deprecated Most SDK users don't need to call this - createAgent() handles initialization.
+ * Only call this if you need to pre-initialize MCP servers.
  */
-export declare function initializeSDK(config: {
-    apiKey?: string;
-    model?: string;
-    baseURL?: string;
-    mcpServers?: Record<string, any>;
-}): Promise<void>;
+export declare function initializeSDK(): Promise<void>;

package/dist/sdk/index.js

@@ -4,27 +4,51 @@
  * 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.
  *
+ * ## Quick Start
+ *
+ * 1. Run `ax-cli setup` to configure credentials (one-time setup)
+ * 2. Use the SDK in your code
+ *
  * @example
  * ```typescript
- * import { createAgent, getSettingsManager } from '@defai.digital/ax-cli/sdk';
- *
- * // Initialize settings
- * const settings = getSettingsManager();
- * await settings.loadUserSettings();
+ * import { createAgent, SDKError, SDKErrorCode } from '@defai.digital/ax-cli/sdk';
  *
- * // Create agent
+ * // Create agent (credentials from ax-cli setup)
  * const agent = await createAgent({
- *   model: 'glm-4.6',
- *   maxToolRounds: 50
+ *   maxToolRounds: 50  // Optional: 1-1000, default 400
  * });
  *
- * // Listen to streaming responses
- * agent.on('stream', (chunk) => {
- *   console.log(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');
+ * } catch (error) {
+ *   // Handle structured errors
+ *   if (SDKError.isSDKError(error)) {
+ *     if (error.code === SDKErrorCode.SETUP_NOT_RUN) {
+ *       console.error('Please run: ax-cli setup');
+ *     }
+ *   }
+ * } finally {
+ *   // Always cleanup resources
+ *   await agent.dispose();
+ * }
+ * ```
+ *
+ * ## Testing
+ *
+ * ```typescript
+ * import { createMockAgent } from '@defai.digital/ax-cli/sdk/testing';
  *
- * // Process messages
- * const result = await agent.processUserMessage('List all TypeScript files');
+ * const mockAgent = createMockAgent(['Response 1', 'Response 2']);
+ * const result = await mockAgent.processUserMessage('Test');
  * ```
  *
  * @packageDocumentation
@@ -41,6 +65,8 @@ 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';
 // ============================================================================
 // LLM Client
 // ============================================================================
@@ -62,7 +88,8 @@ export { extractErrorMessage, createErrorMessage, ErrorCategory } from '../utils
 // MCP Integration
 // ============================================================================
 export { loadMCPConfig } from '../mcp/config.js';
-export { getMCPManager, initializeMCPServers } from '../llm/tools.js';
+export { getMCPManager, initializeMCPServers, getMcpConnectionCount } from '../llm/tools.js';
+export { MCPManager } from '../mcp/client.js';
 // ============================================================================
 // Planning System
 // ============================================================================
@@ -72,47 +99,153 @@ export { getTaskPlanner, isComplexRequest } from '../planner/index.js';
 // ============================================================================
 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)
+// ============================================================================
+export { ToolRegistry, getToolRegistry, registerTools, createToolExecutor } from './tool-registry.js';
+// ============================================================================
 // Constants
 // ============================================================================
-export { GLM_MODELS, DEFAULT_MODEL, AGENT_CONFIG, PLANNER_CONFIG, } from '../constants.js';
+export { GLM_MODELS, DEFAULT_MODEL, AGENT_CONFIG, PLANNER_CONFIG, VerbosityLevel, UI_CONFIG, } from '../constants.js';
+// ============================================================================
+// SDK Version (Phase 1.5: Best Practices)
+// ============================================================================
+export { SDK_VERSION, SDK_API_VERSION, getSDKVersion, getSDKInfo, } from './version.js';
+// ============================================================================
+// SDK Errors (Phase 1: Best Practices)
+// ============================================================================
+export { SDKError, SDKErrorCode } from './errors.js';
+// ============================================================================
+// Testing Utilities (Phase 1: Best Practices)
+// ============================================================================
+export { MockAgent, createMockAgent, MockSettingsManager, createMockSettings, } from './testing.js';
+// ============================================================================
+// SDK Helper Functions
+// ============================================================================
+/**
+ * Validation schema for agent options
+ * @internal
+ */
+const AgentOptionsSchema = z.object({
+    maxToolRounds: z.number().int().min(1).max(1000).optional(),
+    debug: z.boolean().optional(),
+}).strict();
 /**
  * Create a new LLM Agent with configuration
  *
- * @param options - Agent configuration options
+ * SECURITY: All credentials (API key, base URL, model) must be configured
+ * via "ax-cli setup" command. This prevents security vulnerabilities where
+ * credentials could be exposed in code or logs.
+ *
+ * @param options - Agent configuration options (non-sensitive only)
  * @returns Configured LLM Agent instance
+ * @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 VALIDATION_ERROR if options are invalid
  *
  * @example
  * ```typescript
+ * import { createAgent, SDKError, SDKErrorCode } from '@defai.digital/ax-cli/sdk';
+ *
+ * // First, user must run: ax-cli setup
+ * // Then use SDK with settings from setup:
+ *
  * const agent = await createAgent({
- *   model: 'glm-4.6',
- *   maxToolRounds: 50
+ *   maxToolRounds: 50  // Optional: 1-1000, default 400
  * });
  *
- * agent.on('stream', (chunk) => {
- *   if (chunk.type === 'content') {
- *     console.log(chunk.content);
- *   }
- * });
+ * try {
+ *   agent.on('stream', (chunk) => {
+ *     if (chunk.type === 'content') {
+ *       console.log(chunk.content);
+ *     }
+ *   });
  *
- * const result = await agent.processUserMessage('Analyze this codebase');
+ *   const result = await agent.processUserMessage('Analyze this codebase');
+ *   console.log(result);
+ * } catch (error) {
+ *   if (SDKError.isSDKError(error)) {
+ *     switch (error.code) {
+ *       case SDKErrorCode.SETUP_NOT_RUN:
+ *         console.error('Run ax-cli setup first');
+ *         break;
+ *       case SDKErrorCode.API_KEY_MISSING:
+ *         console.error('API key not configured');
+ *         break;
+ *     }
+ *   }
+ * } finally {
+ *   // Always cleanup resources
+ *   await agent.dispose();
+ * }
  * ```
  */
 export async function createAgent(options = {}) {
+    // Validate input options
+    let validated;
+    try {
+        validated = AgentOptionsSchema.parse(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 if not already loaded
+    // Load settings from ax-cli setup
     try {
         settingsManager.loadUserSettings();
     }
-    catch {
-        // Settings may not exist yet, that's okay
+    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);
+    }
+    // Get configuration ONLY from settings (security requirement)
+    const apiKey = settingsManager.getApiKey();
+    const model = settingsManager.getCurrentModel();
+    const baseURL = settingsManager.getBaseURL();
+    // Validate required settings exist
+    if (!apiKey) {
+        throw new SDKError(SDKErrorCode.API_KEY_MISSING, 'No API key configured. Please run "ax-cli 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.');
     }
-    // Get configuration (use options or settings)
-    const apiKey = options.apiKey || settingsManager.getApiKey() || '';
-    const model = options.model || settingsManager.getCurrentModel();
-    const baseURL = options.baseURL || settingsManager.getBaseURL();
-    const maxToolRounds = options.maxToolRounds;
-    // Create agent instance
+    const maxToolRounds = validated.maxToolRounds;
+    const debug = validated.debug ?? false;
+    // Debug logging
+    if (debug) {
+        console.error('[AX SDK DEBUG] Creating agent with settings:');
+        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);
+        console.error('[AX SDK DEBUG]   API key configured:', !!apiKey);
+    }
+    // Create agent instance with settings from ax-cli setup
     const agent = new LLMAgent(apiKey, baseURL, model, maxToolRounds);
+    // Enable debug mode on agent if requested
+    if (debug) {
+        // Add debug event listener
+        agent.on('stream', (chunk) => {
+            if (chunk.type === 'tool_calls' && chunk.toolCalls) {
+                const toolNames = chunk.toolCalls.map((tc) => tc.function.name).join(', ');
+                console.error('[AX SDK DEBUG] Tool calls:', toolNames);
+            }
+            else if (chunk.type === 'tool_result' && chunk.toolResult) {
+                console.error('[AX SDK DEBUG] Tool result:', chunk.toolResult.success ? 'success' : 'failed');
+            }
+        });
+        console.error('[AX SDK DEBUG] Agent created successfully');
+    }
     return agent;
 }
 /**
@@ -140,34 +273,22 @@ export function createSubagent(role, config) {
     return new Subagent(role, config);
 }
 /**
- * Initialize SDK with configuration
+ * Initialize SDK and MCP servers
  *
- * @param config - SDK initialization configuration
+ * SECURITY: This function does NOT accept credentials. All credentials must be
+ * configured via "ax-cli setup" command. This function only initializes MCP servers.
  *
  * @example
  * ```typescript
- * await initializeSDK({
- *   apiKey: 'your-api-key',
- *   model: 'glm-4.6',
- *   baseURL: 'https://api.example.com/v1'
- * });
+ * // Initialize MCP servers from ax-cli settings
+ * await initializeSDK();
  * ```
+ *
+ * @deprecated Most SDK users don't need to call this - createAgent() handles initialization.
+ * Only call this if you need to pre-initialize MCP servers.
  */
-export async function initializeSDK(config) {
-    const settingsManager = getSettingsManager();
-    // Update settings
-    if (config.apiKey) {
-        settingsManager.updateUserSetting('apiKey', config.apiKey);
-    }
-    if (config.model) {
-        settingsManager.updateUserSetting('defaultModel', config.model);
-    }
-    if (config.baseURL) {
-        settingsManager.updateUserSetting('baseURL', config.baseURL);
-    }
-    // Initialize MCP servers if provided
-    if (config.mcpServers) {
-        await initializeMCPServers();
-    }
+export async function initializeSDK() {
+    // Initialize MCP servers from settings configured via ax-cli setup
+    await initializeMCPServers();
 }
 //# sourceMappingURL=index.js.map